Pagination

Pagination tracks which results have been returned for a given pagination_key to ensure users see new content on subsequent requests. The system filters out items that have already been returned for the same key.

Configuration

Enable pagination by setting page_expiration_in_seconds to a positive value in your engine's deployment config:

deployment:
  pagination:
    page_expiration_in_seconds: 600  # Set to 0 to disable (default)

Pagination only works when page_expiration_in_seconds > 0. When disabled (default), pagination_key has no effect.

Usage

Provide a pagination_key to track which items have been returned:

{
  "query": "SELECT * FROM retrieve(similarity(embedding_ref='als', limit=50)) LIMIT 20",
  "parameters": {
    "user_id": "user123"
  },
  "pagination_key": "user123_session_abc"
}

Use the same pagination_key in subsequent requests to continue pagination. Each request returns the next page of results, excluding items already returned for that key.

Parameters

pagination_key (optional, string)

• Identifier for tracking returned items. Use any string you want.
• Each unique key maintains separate pagination state.
• Common patterns: user_id for per-user feeds, or user_id_session_id for per-session feeds.

ignore_pagination (optional, boolean, default: false)

• When true, ignores pagination and returns results from the beginning.
• Does not update or modify the pagination state for the key.
• Use when you need a fresh result set without affecting continuity for future requests (e.g., preview or refresh).

Example flow

1. Configure page_expiration_in_seconds in your engine's deployment config.
2. Send a query with pagination_key: "user123" and LIMIT 20.
3. Shaped returns the first 20 items and records them for that key.
4. On the next request with the same key, Shaped returns the next 20 items, excluding those already returned.
5. Items expire from the pagination store after page_expiration_in_seconds, after which they can appear again for that key.