Collections

Collections are curated product listings. They’re similar to category pages, however you don’t need to pre-define them in your index. Instead, you can create a collection by manually selecting records or defining them using conditions. After initial setup, creating and editing a collection is fast and code-free.

Collections are ideal for seasonal promotions, featured collections, or any manually curated selection.

This guide shows you how to implement collections:

1. Creating and updating collections with the Algolia dashboard or Merchandising Studio
2. Building the collection pages with InstantSearch on the frontend

Create a collection

To get started with Collections, use the Algolia dashboard or Merchandising Studio.

An index can have up to 25 collections.

In the dashboard

1. Go to Search > Enhance > Collections list page
2. Select New collection to start your build

In the Merchandising Studio

The Merchandising Studio lets you add collections to your existing merchandising strategies.

1. Go to the Merchandising Studio > Visual Merchandiser
2. Open the experience selector and choose Collection
3. Select Create new collection to start your build

Next up, you can start adding items to your collection.

Add items to a collection

Once you’ve created a collection, you can populate it manually or dynamically:

• Manually: you pick exactly what items to include in your collection. The collection only changes when you add or remove items. Use cases include a fixed collection of best sellers or a themed editorial collection.
• Dynamically: you define conditions to match the items to include in your collection (such as brand, category, or price). The collection updates when you update your index with items that match the defined criteria. For example, an “Under $50” collection that updates based on price changes.

You can also combine both options in a single collection. By combining manual and conditional items, you can curate part of the collection while allowing dynamic updates based on real-time record data.

Handpick items from an index (manual)

This option lets you manually select specific items from your index to be included in the collection. This is useful for curated collections where you require exact control over the selection.

You can either query your index or use filters to look for specific items.

You can have up to 1,000 manually selected items in a collection.

Upload a file (manual)

This option lets you bulk upload a predefined list of objectIDs from a file (.csv, .txt and .xlsx).

You can have up to 1,000 manually selected items in a collection.

Set conditions (dynamic)

This option lets you define conditions to populate the collection. The collection dynamically populates with all items that match your conditions. It automatically includes new matching records as they’re added to your index

Attributes must be defined in attributesForFaceting to be used in conditions.

Delete a collection

If a collection is no longer relevant or you’ve reached the limit on the number of collections per index, you can remove them.

1. Go to the collections list page in the Algolia dashboard or Merchandising Studio and find the collection you want to delete.
2. Click the menu for that collection and select Delete.
3. When the confirmation prompt appears, click Delete again to confirm.

The collection will be removed from the list and the index will update accordingly.

To ensure a clean user experience, also make sure a deleted collection has no references left.

• In your frontend: if a collection was linked in your navigation or marketing materials, ensure those links are updated.
• In your rules or Merchandising Studio: update any merchandising rules or display logic that relied on the deleted collection to prevent errors or empty pages.

Deleting a collection is permanent and can’t be undone.

Ensure collections remain up to date

If you’re indexing records with an Algolia API client, you need to update your code to ensure your collections work as intended.

Instead of using the saveObject, addOrUpdateObject, batch, or multipleBatch methods, use the Ingestion API’s pushTask method so that your updates go through the Ingestion pipeline and preserve your collection data.

1. In the Algolia Dashboard, go to Search > Enhance > Collections and select Indexing Guidelines.
2. Go to the After tab, and copy the taskID.
3. Use the Ingestion API pushTask method to send your records with the taskID you copied in the previous step.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
using Algolia.Search.Clients;
using Algolia.Search.Http;
using Algolia.Search.Models.Ingestion;

var client = new IngestionClient(
  new IngestionConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION")
);

var response = await client.PushTaskAsync(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  new PushTaskPayload
  {
    Action = Enum.Parse<Action>("AddObject"),
    Records = new List<PushTaskRecords>
    {
      new PushTaskRecords
      {
        ObjectID = "o",
        AdditionalProperties = new Dictionary<string, object>
        {
          { "key", "bar" },
          { "foo", "1" },
        },
      },
      new PushTaskRecords
      {
        ObjectID = "k",
        AdditionalProperties = new Dictionary<string, object>
        {
          { "key", "baz" },
          { "foo", "2" },
        },
      },
    },
  }
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import "github.com/algolia/algoliasearch-client-go/v4/algolia/ingestion"

client, err := ingestion.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", ingestion.US)
if err != nil {
  // The client can fail to initialize if you pass an invalid parameter.
  panic(err)
}

response, err := client.PushTask(client.NewApiPushTaskRequest(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  ingestion.NewEmptyPushTaskPayload().SetAction(ingestion.Action("addObject")).SetRecords(
    []ingestion.PushTaskRecords{*ingestion.NewEmptyPushTaskRecords().SetAdditionalProperty("key", "bar").SetAdditionalProperty("foo", "1").SetObjectID("o"), *ingestion.NewEmptyPushTaskRecords().SetAdditionalProperty("key", "baz").SetAdditionalProperty("foo", "2").SetObjectID("k")})))
if err != nil {
  // handle the eventual error
  panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import com.algolia.api.IngestionClient;
import com.algolia.config.*;

IngestionClient client = new IngestionClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION");

client.pushTask(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  new PushTaskPayload()
    .setAction(Action.ADD_OBJECT)
    .setRecords(
      Arrays.asList(
        new PushTaskRecords().setAdditionalProperty("key", "bar").setAdditionalProperty("foo", "1").setObjectID("o"),
        new PushTaskRecords().setAdditionalProperty("key", "baz").setAdditionalProperty("foo", "2").setObjectID("k")
      )
    )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { algoliasearch } from 'algoliasearch';

// Replace 'us' with your Algolia Application Region
const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY').initIngestion({ region: 'us' });

const response = await client.pushTask({
  taskID: '6c02aeb1-775e-418e-870b-1faccd4b2c0f',
  pushTaskPayload: {
    action: 'addObject',
    records: [
      { key: 'bar', foo: '1', objectID: 'o' },
      { key: 'baz', foo: '2', objectID: 'k' },
    ],
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import com.algolia.client.api.IngestionClient
import com.algolia.client.configuration.*
import com.algolia.client.transport.*

val client = IngestionClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = "ALGOLIA_APPLICATION_REGION")

var response = client.pushTask(
  taskID = "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  pushTaskPayload = PushTaskPayload(
    action = Action.entries.first { it.value == "addObject" },
    records = listOf(
      PushTaskRecords(
        objectID = "o",
        additionalProperties = mapOf(
          "key" to JsonPrimitive("bar"),
          "foo" to JsonPrimitive("1"),
        ),
      ),
      PushTaskRecords(
        objectID = "k",
        additionalProperties = mapOf(
          "key" to JsonPrimitive("baz"),
          "foo" to JsonPrimitive("2"),
        ),
      ),
    ),
  ),
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
use Algolia\AlgoliaSearch\Api\IngestionClient;

$client = IngestionClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY', 'ALGOLIA_APPLICATION_REGION');

$response = $client->pushTask(
    '6c02aeb1-775e-418e-870b-1faccd4b2c0f',
    ['action' => 'addObject',
        'records' => [
            ['key' => 'bar',
                'foo' => '1',
                'objectID' => 'o',
            ],

            ['key' => 'baz',
                'foo' => '2',
                'objectID' => 'k',
            ],
        ],
    ],
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from algoliasearch.ingestion.client import IngestionClientSync
from json import loads

# In an asynchronous context, you can use IngestionClient instead, which exposes the exact same methods.
client = IngestionClientSync(
    "ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION"
)

response = client.push_task(
    task_id="6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    push_task_payload={
        "action": "addObject",
        "records": [
            {
                "key": "bar",
                "foo": "1",
                "objectID": "o",
            },
            {
                "key": "baz",
                "foo": "2",
                "objectID": "k",
            },
        ],
    },
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
require "algolia"

client = Algolia::IngestionClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION")

response = client.push_task(
  "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
  Algolia::Ingestion::PushTaskPayload.new(
    action: "addObject",
    records: [
      Algolia::Ingestion::PushTaskRecords.new(key: "bar", foo: "1", algolia_object_id: "o"),
      Algolia::Ingestion::PushTaskRecords.new(key: "baz", foo: "2", algolia_object_id: "k")
    ]
  )
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import algoliasearch.api.IngestionClient
import algoliasearch.config.*

val client = IngestionClient(
  appId = "ALGOLIA_APPLICATION_ID",
  apiKey = "ALGOLIA_API_KEY",
  region = "ALGOLIA_APPLICATION_REGION"
)

val response = Await.result(
  client.pushTask(
    taskID = "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    pushTaskPayload = PushTaskPayload(
      action = Action.withName("addObject"),
      records = Seq(
        PushTaskRecords(
          objectID = "o",
          additionalProperties = Some(List(JField("key", JString("bar")), JField("foo", JString("1"))))
        ),
        PushTaskRecords(
          objectID = "k",
          additionalProperties = Some(List(JField("key", JString("baz")), JField("foo", JString("2"))))
        )
      )
    )
  ),
  Duration(100, "sec")
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import Ingestion

let client = try IngestionClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY", region: .us)

let response = try await client.pushTask(
    taskID: "6c02aeb1-775e-418e-870b-1faccd4b2c0f",
    pushTaskPayload: PushTaskPayload(
        action: IngestionAction.addObject,
        records: [
            PushTaskRecords(from: [
                "objectID": AnyCodable("o"),
                "key": AnyCodable("bar"),
                "foo": AnyCodable("1"),
            ]),
            PushTaskRecords(from: [
                "objectID": AnyCodable("k"),
                "key": AnyCodable("baz"),
                "foo": AnyCodable("2"),
            ]),
        ]
    )
)

Update a collection

To update a collection:

1. Go to the collections list page in the Algolia dashboard or Merchandising Studio and find the collection you want to update.
2. Click the menu for that collection and select Edit.
3. Make your changes: update the collection name or description, manually add or remove items, modify the conditions of the collection, and so on.
4. Once you’re done, save your changes.

Build a collections page with InstantSearch

If you don’t use InstantSearch, you can filter on the _collections attribute.

InstantSearch lets you create collection pages using a menu widget and routing capabilities.

You don’t need to create a new page for each collection. Instead, you can define a dynamic template to display any collection.

Installation

Before building your page, install the InstantSearch library:

Set up the collection page

First, you must create a page to display collections (for example, to be rendered on the example.org/collections/ URL). On this page, add the following code to render collections.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import instantsearch from 'instantsearch.js';
import { hits, menu } from 'instantsearch.js/es/widgets';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

const search = instantsearch({
  searchClient,
  indexName: 'INDEX_NAME',
  insights: true,
});

search.addWidgets([
  menu({
    container: '#menu',
    attribute: '_collections',
  }),
  hits({
    container: '#hits',
  }),
]);

search.start();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { Hits, InstantSearch, Menu } from 'react-instantsearch';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="INDEX_NAME"
      insights={true}
    >
      <Menu attribute="_collections" />
      <Hits />
    </InstantSearch>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<template>
  <div>
    <ais-instant-search
      :search-client="searchClient"
      index-name="instant_search"
      :insights="true"
    >
      <ais-menu attribute="_collections" />
      <ais-hits />
    </ais-instant-search>
  </div>
</template>

<script>
import { liteClient as algoliasearch } from 'algoliasearch/lite';

export default {
  data() {
    return {
      searchClient: algoliasearch(
        'YourApplicationID',
        'YourSearchOnlyAPIKey',
      ),
    };
  },
};
</script>

When users go to this page, they’ll see a menu that lets them select any collection and a list of unfiltered hits.

For now, users can click the menu to filter on any collection but you can’t display a given collection by default. To do so, you need to enable routing.

Enable routing

Once your template is ready, you need to be able to link to specific collections and have them already filtered. To do so, you must enable routing so the URL syncs with InstantSearch and displays the right collection.

1
2
3
4
5
6
const search = instantsearch({
  searchClient,
  indexName: 'INDEX_NAME',
  insights: true,
  routing: true
});

1
2
3
4
5
6
7
8
9
10
11
12
function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="INDEX_NAME"
      insights={true}
      routing={true}
    >
      {/* … */}
    </InstantSearch>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
<template>
  <div>
    <ais-instant-search
      :search-client="searchClient"
      index-name="instant_search"
      :insights="true"
      :routing="true"
    >
      <!-- …  -->
    </ais-instant-search>
  </div>
</template>

This option enables basic URL routing, with query parameters. When you go to your collection page with a collection in the URL (for example, “Christmas Deals”), it will only display the records belonging to this collection.

1
example.org/collections/?INDEX_NAME[menu][_collections]=Christmas Deals

For more SEO-friendly URLs, you can write a custom router:

Hide the menu

You may want to avoid displaying unrelated and irrelevant collections in your menus. While you still need a menu for the collection state to exist in InstantSearch, you can make it render nothing by using the connector instead and building a virtual widget.

1
2
3
4
5
6
7
8
9
import { connectMenu } from 'instantsearch.js/es/connectors';

const virtualMenu = connectMenu(() => null);

search.addWidgets([
  virtualMenu({
    attribute: '_collections',
  }),
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { useMenu } from 'react-instantsearch';

function VirtualMenu(props) {
  useMenu(props);

  return null;
}

function App() {
  return (
    <InstantSearch
      routing={true}
      searchClient={searchClient}
      indexName="INDEX_NAME"
    >
      <VirtualMenu />
      <Hits />
    </InstantSearch>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<template>
  <div>
    <ais-instant-search
      :search-client="searchClient"
      index-name="instant_search"
      :insights="true"
      :routing="true"
    >
      <ais-menu attribute="_collections">
        <template />
      </ais-menu>
      <ais-hits />
    </ais-instant-search>
  </div>
</template>

The virtual widget retains the menu features without rendering anything, allowing you to make each collection page fully independent.

Troubleshooting

Debugging collections pipeline

If you encounter issues with your collections, contact support.

Adding an attribute takes too long

When you update a record that should be added to a collection, it takes a few seconds for your index to update because the indexing pipeline is asynchronous.

However if the update takes an unusually long time (hours), you might not be sending your updates to the push endpoint. Make sure you are sending your updates to the push endpoint to trigger the pipeline immediately.

Detecting if updates use the pipeline

If you suspect you might be sending updates to the Search API instead of the Ingestion API, search your code for saveObject, addOrUpdateObject, batch, or multipleBatch. If you find these methods, you are sending updates to the Search API, which could override the collections data in your index.

You can also check the logs in the Algolia dashboard to see if the Ingestion API is being triggered.

To ensure your collections remain up to date, update your code to use the Ingestion API.

A collection is not showing up

A collection might not show up because you’re not sending the entire record to the push endpoint. This is especially true for conditional collections, because even though the endpoint uses partial updates, conditions are re-evaluated whenever the records update.

Make sure to send all attributes that are referenced in the conditions whenever making updates to your records.

Fixing the “_collections is not a facet” error

When creating a collection, the _collections attribute is automatially added in attributesForFaceting so it can be filtered on. If you get an error message with “_collections is not a facet”, this means the attribute might have been accidentally removed from the list of facets, and you need to add it back again in your index settings.

You can do this in the Algolia dashboard or with the API.

The collection page is empty

If you’re manually displaying a collection on an HTML page by referencing the _collections attribute (for example, with a configure widget), delete the page before you remove the collection in the Algolia dashboard. Otherwise, the page will display an empty collection.

To avoid this issue, use a menu widget to generate your page. If you’re already doing so, make sure to remove any static link on your site pointing to the deleted collection.

Next steps

After configuring collections and creating your collections page, you can:

• Add rules to curate them
• Use Dynamic Re-Ranking to adjust the order of categories
• Personalize them

While the following guides refer to category pages, they work the same for collections.