Collections

Collections are curated product listings. They’re similar to category pages but 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.

The Collections feature is ideal for seasonal promotions, featured collections, or any manually curated selection.

This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

Here’s how to set up collections:

1. Create and update collections with the Algolia dashboard or Merchandising Studio.
2. Build 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 per index.

Collections don’t support quotes and escape characters in object IDs. Ensure you “clean” the objectID attributes in your index before creating a collection.

In the dashboard

1. Go to the Algolia dashboard and select your Algolia application.
2. On the left sidebar, select Search.

3. Select your Algolia index:

   

4. Go to Collections
5. Select New collection to start your build.

In the Merchandising Studio

The Merchandising Studio is a feature that lets you add collections to your existing merchandising strategies.

This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

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.

Now, 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 choose individual items for 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 also 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 include in the collection. This is useful for curated collections requiring 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 object IDs from a file (.csv, .txt, or .xlsx). The file should contain a single column with one objectID per row and no header.

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.

Define the attributesForFaceting to use 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 it:

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 “actions” icon and select Delete collection.
3. To confirm, click Delete.

The collection is removed from the list and the index updated accordingly.

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

• In your frontend: if a collection is linked in your navigation or marketing materials, update those links.
• In your rules or Merchandising Studio: update any merchandising rules or display logic that rely 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, 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, open the Collections page and select Indexing Guidelines.
2. On the After tab, copy the task ID for updating your collections (Your unique Push Task ID).
3. Use the Ingestion API pushTask method to send your records with the task ID 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"),
            ]),
        ]
    )
)

Periodic reindex operations are also performed to ensure that collections remain up-to-date. They help maintain the accuracy of your collections by synchronizing them with the latest changes in your index, ensuring that any new or modified records are reflected in your collections.

This adds read and write operations which might lead to costs, depending on your plan.

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. For example, update the collection name or description, add or remove items, or modify the conditions of the collection.
4. 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, 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 render to 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 this, 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 this, 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 only displays the records belonging to this collection.

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

For more SEO-friendly URLs, create 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.

Troubleshoot problems

Debug the collections pipeline

If you encounter issues with your collections, contact the Algolia support team.

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.

If updates take an unusually long time (hours), check that you’re sending them to the push endpoint with the pushtask method. This ensures immediate pipeline triggering.

Determine 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 triggered.

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

A collection isn’t 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.

When updating your records, ensure you include all attributes referenced in the conditions.

Fix the “_collections is not a facet” error

When creating a collection, the _collections attribute is automatically added to the attributesForFaceting setting so it can be filtered. The “_collections is not a facet” error indicates that the _collections attribute has been removed from the list of facets. You need to re-enable it 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.