Implementing Faceted Search with Pagination in Algolia for Web Apps

Desired Outcome

Enable a web application to present search results that can be filtered by facets (e.g., brand, category) and paginated. The goal is to have a responsive UI that shows accurate hit counts, facet counts, and supports zero‑based page navigation.

Prerequisites

• Algolia account with an application ID and admin API key.
• Index already created in the dashboard or via the API.
• Data objects that include the attributes you want to facet on (e.g., brand, category).
• Basic knowledge of JSON and HTTP requests (curl or a client library).

Configure Facets

Faceted search requires that the attributes you want to filter on are listed in attributesForFaceting. This can be done through the dashboard or the API.

1. Navigate to Index → Settings → Facets in the Algolia dashboard.
2. Click Add a facet and enter the attribute name (e.g., brand).
3. Repeat for each attribute (e.g., category).
4. Save the settings.

Alternatively, use the API to update the setting:

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

Add Data

Upload or update records that contain the faceted attributes. Example record:

{
  "objectID": "12345",
  "name": "iPhone 15",
  "brand": "Apple",
  "category": "Phones",
  "price": 999
}

Search with Facets and Pagination

A typical search request includes the query string, page number, hits per page, and optional facetFilters. Pagination in Algolia is zero‑based: page=0 returns the first page.

curl -X POST \
  https://-dsn.algolia.net/1/indexes//search \
  -H "X-Algolia-API-Key: " \
  -H "X-Algolia-Application-Id: " \
  -H "Content-Type: application/json" \
  -d '{
    "query": "iPhone",
    "hitsPerPage": 20,
    "page": 0,
    "facetFilters": [
      ["brand:Apple"],
      ["category:Phones"]
    ],
    "facets": ["brand", "category"]
  }'

Replace the placeholders with your actual values. The response JSON will contain:

• hits – array of matching records.
• nbHits – total number of hits for the query.
• page – current page number.
• hitsPerPage – page size.
• facets – object mapping facet names to value counts.

Validate Results

After sending the request, perform the following checks:

1. Confirm that hits contains the expected number of items (≤ hitsPerPage).
2. Verify that page equals the value you sent (0 for the first page).
3. Check that facets includes the attributes you requested and that the counts match your dataset.
4. If a facet is missing or its count is zero, revisit the attributesForFaceting setting.

Recovery Options

• Missing Facet in Results: Ensure the attribute is listed in attributesForFaceting and re‑index the data.
• Facet Count Inaccurate: If the index is undergoing a reindex, wait until the process completes. Check the indexing status in the dashboard.
• Query Complexity Exceeded: Reduce the number of facetFilters per request. Algolia limits the total number of filters.
• Stale Pagination: For real‑time data, consider cursor‑based pagination via aroundLatLng or aroundRadius if applicable, or schedule a reindex.

Practical Check: Dashboard Verification

Navigate to the index settings in the Algolia dashboard:

1. Index → Settings → Facets.
2. Verify that the list of facets matches the attributes you used in the API request.
3. Use the Query tab to run a quick search with the same parameters and inspect the returned facets.

Limitations & Notes

• Facet counts are computed on the fly; large indices may incur higher latency.
• The default facetHits limit is 10. Increase it if you need more facet values.
• Pagination offset can become stale if the dataset changes between requests.
• Algolia enforces a maximum of 5 facetFilters per query to avoid excessive complexity.

Conclusion

By configuring attributesForFaceting, correctly structuring search queries with facetFilters, and using zero‑based pagination, you can build a robust faceted search experience. Validate each step through the dashboard and API responses, and be prepared to adjust facet limits or query complexity as your data grows.