Algolia Search API vs. Client Pagination: Is Stable Ordering Guaranteed Across Pages?

Question

Goal: Stable Pagination for Large, Dynamic Indices
Developers often need to present users with a paginated view of a sizable Algolia index (tens of thousands of records). The goal is to fetch each page in sequence while ensuring that no record is omitted or duplicated, even when the index is updated between requests.
Constraints and Uncertainty
Algolia’s public API offers hitsPerPage and page parameters, and the more granular offset and length options. However, the API does not guarantee a stable ordering across successive calls when the underlying index changes. The nbHits field is computed on the fly, so its value may not reflect real‑time updates. Additionally, the API lacks a native cursor‑based mechanism, forcing developers to implement custom logic if they wish to track state (e.g., using the last record’s primary key). These factors create uncertainty about whether offset‑based pagination can reliably deliver consistent results for large, frequently updated datasets.
Unresolved Questions
1. Does Algolia guarantee stable ordering across pages when using offset and length or page and hitsPerPage, even when records are added or removed between requests?
2. What, if any, mechanisms does Algolia provide to maintain consistency across paginated results for dynamic indices?
3. For indices that exceed a few thousand records and receive frequent updates, is a custom cursor strategy (e.g., filtering by a monotonically increasing primary key) recommended, and what are the trade‑offs in terms of latency and API usage?

Tasadduq Burney · Answer

Answer to the Core Question
Algolia does not guarantee stable ordering across successive calls that use offset/length or page/hitsPerPage when the underlying index is modified between requests.  New documents can shift the internal ranking, causing records to appear on a different page or to be omitted entirely.
Why Offset/ Page Parameters Are Unstable

The ranking algorithm is recomputed on each request; insertion or deletion can change the order of all hits.
The nbHits field is calculated per query, so it may not reflect the current total after an update.
There is no native cursor or token that pins the search state across requests.

Confirmed Facts

Offset‑based pagination can produce duplicates or gaps when the index changes.
Algolia offers no built‑in cursor‑based mechanism.
Using a filter on a unique, monotonically increasing attribute (e.g., objectID or a custom seq_id) is the only supported way to achieve deterministic paging.

Recommended Stable‑Pagination Pattern

Introduce a monotonic field. Add a numeric seq_id that increments with each new record and is indexed for filtering.
First page. Query normally with hitsPerPage=10 and record the highest seq_id returned.
Subsequent pages. Use a filter such as filters=seq_id > 12345 (where 12345 is the last seen seq_id) together with hitsPerPage.  This guarantees that only newer records are returned, even if older ones were inserted or removed.
Maintain state. Store the last seq_id (or objectID if it is monotonically increasing) on the client side.  Pass it back to the server with each request.
Handle edge cases. Ensure the field is unique and strictly increasing; otherwise gaps or repeats may still appear.

Verification Steps (Optional)

Create a test index and populate it with records that include a seq_id.
Request the first page (e.g., offset=0, hitsPerPage=10) and note the returned seq_id values.
Insert a new record with a seq_id that would appear before the current offset range.
Request the next page using offset=10, hitsPerPage=10 and observe whether any records from the first page re‑appear or are missing.
Repeat the same test using the monotonic‑filter approach (filters=seq_id > lastSeen) to confirm stability.

Missing Diagnostic Detail
Do you have a unique, monotonically increasing attribute (e.g., seq_id or a timestamp) that can be indexed for filtering?  This is critical for implementing the cursor strategy safely.
Practical Takeaway
For indices that grow or change frequently, rely on a cursor‑based approach with a monotonic filter rather than plain offset or page parameters.  This avoids duplicates, omissions, and the pitfalls of an unstable nbHits count.

Algolia Search API vs. Client Pagination: Is Stable Ordering Guaranteed Across Pages?

Goal: Stable Pagination for Large, Dynamic Indices

Constraints and Uncertainty

Unresolved Questions

1 answer

Answer to the Core Question

Why Offset/ Page Parameters Are Unstable

Confirmed Facts

Recommended Stable‑Pagination Pattern

Verification Steps (Optional)

Missing Diagnostic Detail

Practical Takeaway

Your perspective belongs here.

0 question comments