Collections

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

Collections are curated product listings. They’re similar to category pages but you don’t need to create them in your index ahead of time. 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. Here’s how to set up collections:

Create and update collections with the Algolia dashboard or Merchandising Studio.
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 supports up to 500 (Premium) / 1,000 (Elevate) 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

Go to the Algolia dashboard and select your Algolia application.
On the left sidebar, select Search.
Select your Algolia index and go to Collections.
Select New collection to start your build.

In the Merchandising Studio

Using the Merchandising Studio you can add collections to your existing merchandising strategies.

Go to the Merchandising Studio > Visual Merchandiser.
Open the experience selector and choose Collection.
Select Create new collection to start your build.
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)

Use this option to 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 10,000 manually selected items per collection.

Upload a file (manual)

You can bulk upload a predefined list of object IDs from a file (.csv, .txt, or .xlsx). Include one objectID per row, in a single-column file with no header.

You can have up to 10,000 manually selected items per collection.

Set conditions (dynamic)

This option dynamically adds items to the collection based on conditions you define. It automatically includes new matching records as they’re added to your index.

Define the attributesForFaceting to use in conditions. You can have up to 50 conditions per collection.

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:

Go to the collections list page in the Algolia dashboard or Merchandising Studio and find the collection you want to delete.
Open the Actions menu and select Delete collection.
To confirm, click Delete.

Removing the collection also updates the index. 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.

`withTransformation` methods

The Ingestion API client has withTransformation methods which ensure that your collections are updated correctly. You can replace your calls to the Search API with these methods:

With the `pushTask` method

If your version of the client doesn’t have withTransformation methods, instead of using the saveObject, addOrUpdateObject, batch, or multipleBatch methods, use the Ingestion API pushTask method so that your updates go through the Ingestion pipeline and preserve your collection data.

In the Algolia dashboard, open the Collections page and select Indexing Guidelines.
On the After tab, copy the task ID for updating your collections (Your unique Push Task ID).
Use the Ingestion API pushTask method to send your records with the task ID you copied in the previous step.

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("AddObject"),
    Records = new List
    {
      new PushTaskRecords
      {
        ObjectID = "o",
        AdditionalProperties = new Dictionary
        {
          { "key", "bar" },
          { "foo", "1" },
        },
      },
      new PushTaskRecords
      {
        ObjectID = "k",
        AdditionalProperties = new Dictionary
        {
          { "key", "baz" },
          { "foo", "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:

Go to the collections list page in the Algolia dashboard or Merchandising Studio and find the collection you want to update.
Click the menu for that collection and select Edit.
Make your changes. For example, update the collection name or description, add or remove items, or modify the conditions of the collection.
Save your changes.

Build a collections page with InstantSearch

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.

The _collections attribute is reserved only if you’re using InstantSearch to implement a collections page. If you’re not using InstantSearch, _collections behaves like any other attribute.

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:

import { liteClient as algoliasearch } from "algoliasearch/lite";
import instantsearch from "instantsearch.js";
import { hits, menu } from "instantsearch.js/es/widgets";

const searchClient = algoliasearch("undefined", "undefined");

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

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

search.start();

When users go to this page, they can select any collection and see 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:

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

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.

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

For more SEO-friendly URLs, create a custom router:

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.

import { connectMenu } from "instantsearch.js/es/connectors";

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

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

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

Collection status

The list of collections in the Algolia dashboard shows the status of each collection:

Synchronized. The collection is up-to-date with the index.
Synchronizing. The collection is being updated. This happens when you add or remove items, use the push task, or when the periodic reindex operation runs. This can take a few seconds to a few minutes, depending on the number of items in the collection and the size of your index.
Pending. The collection and the index aren’t synchronized. This can happen if you add new items without using the push task or if the periodic reindex operation fails. However, if it goes straight from “Synchronizing” to “Pending”, contact the Algolia support team.
Error. This indicates a problem retrieving the collection’s status, not that the collection itself is experiencing an error. If you see this status, refresh the page or check your network connection. If the issue persists, contact the Algolia support team.

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:

Guides

Create a collection

In the dashboard

In the Merchandising Studio

Add items to a collection

Handpick items from an index (manual)

Upload a file (manual)

Set conditions (dynamic)

Delete a collection

Ensure collections remain up-to-date

`withTransformation` methods

With the `pushTask` method

Update a collection

Build a collections page with InstantSearch

Installation

Set up the collection page

Enable routing

Hide the menu

Troubleshoot problems

Debug the collections pipeline

Adding an attribute takes too long

Determine if updates use the pipeline

A collection isn’t showing up

Fix the ” `_collections` is not a facet” error

The collection page is empty

Collection status

Next steps

Guides

​Create a collection

​In the dashboard

​In the Merchandising Studio

​Add items to a collection

​Handpick items from an index (manual)

​Upload a file (manual)

​Set conditions (dynamic)

​Delete a collection

​Ensure collections remain up-to-date

​withTransformation methods

​With the pushTask method

​Update a collection

​Build a collections page with InstantSearch

​Installation

​Set up the collection page

​Enable routing

​Hide the menu

​Troubleshoot problems

​Debug the collections pipeline

​Adding an attribute takes too long

​Determine if updates use the pipeline

​A collection isn’t showing up

​Fix the ” _collections is not a facet” error

​The collection page is empty

​Collection status

​Next steps

Create a collection

In the dashboard

In the Merchandising Studio

Add items to a collection

Handpick items from an index (manual)

Upload a file (manual)

Set conditions (dynamic)

Delete a collection

Ensure collections remain up-to-date

`withTransformation` methods

With the `pushTask` method

Update a collection

Build a collections page with InstantSearch

Installation

Set up the collection page

Enable routing

Hide the menu

Troubleshoot problems

Debug the collections pipeline

Adding an attribute takes too long

Determine if updates use the pipeline

A collection isn’t showing up

Fix the ” `_collections` is not a facet” error

The collection page is empty

Collection status

Next steps