Configuring Algolia Faceting for Effective Search Filtering

Useful answer

To let users narrow search results by attributes like category or brand, declare those attributes as facets in your Algolia index and then use the facets and filters parameters in your search request.

How faceting works

Faceting pre‑computes the distinct values of selected attributes so Algolia can return counts (facets section) and apply boolean filters (filters) without scanning the whole record set. An attribute must be listed in attributesForFaceting before it can be used in either parameter.

Worked example: configuring a facet and querying it

1. Set the facet attribute via the Algolia Admin API (requires an admin key). Replace YOUR_APP_ID, YOUR_ADMIN_KEY and your_index with your values.

curl -X PUT \
  "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/your_index/settings" \
  -H "Content-Type: application/json" \
  -H "X-Algolia-Application-ID: YOUR_APP_ID" \
  -H "X-Algolia-API-Key: YOUR_ADMIN_KEY" \
  -d '{
    "attributesForFaceting": ["category", "brand"]
  }'

This call updates the index settings; to revert, send the same PUT with the previous list or an empty array.

1. Search with facet counts and a filter. The facets parameter asks for the distribution; the filters parameter restricts results.

curl -X GET \
  "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/your_index/query" \
  -H "Content-Type: application/json" \
  -H "X-Algolia-Application-ID: YOUR_APP_ID" \
  -H "X-Algolia-API-Key: YOUR_SEARCH_ONLY_KEY" \
  -d '{
    "params": "query=&facets=%5B%22category%22%2C%22brand%22%5D&filters=category%3AElectronics"
  }'

The JSON response will contain a facets object, for example:

{
  "hits": [...],
  "nbHits": 124,
  "facets": {
    "category": { "Electronics": 124, "Books": 0 },
    "brand": { "Apple": 45, "Samsung": 38, "Sony": 21 }
  }
}

If you omit the filters parameter, the facet counts reflect the whole index; adding the filter narrows both hits and the facet counts to the matching subset.

Limits and common mistakes

• High‑cardinality attributes. Using a unique identifier (e.g., product_id) as a facet creates a facet value per record, inflating index size and slowing queries. Reserve faceting for low‑to‑moderate cardinality fields.
• Missing facet declaration. Attempting to filter on an attribute not listed in attributesForFaceting returns an error or ignores the filter. Always verify the setting via the Dashboard or the get settings API.
• Over‑faceting. Adding dozens of attributes increases storage and can degrade indexing speed. Periodically review attributesForFaceting and remove unused ones.
• Case sensitivity. Facet values are stored exactly as indexed; filtering category:electronics will not match Electronics unless you normalize case at indexing time.

Practical verification: after updating attributesForFaceting, run a query with facets but no filters and confirm that the requested attributes appear in the facets section of the response. Then apply a known filter and check that nbHits and the facet counts change as expected.