Skip to main content

Pagination

Shaped uses a pagination store to manage result freshness and continuity for each user across ranking requests. This ensures that users are consistently presented with new, relevant content rather than seeing the same items repeatedly.

How It Works​

  • Pagination is controlled by the pagination_store_ttl parameter defined in your model configuration which sets how long the recommended item_id remain in the store before expiring. The default TTL is 3600 seconds.
  • All served user_ids are recorded in the pagination store to ensure previously returned items are filtered out in future requests.
  • The store tracks returned results per user within the configured TTL window, enabling consistent pagination over time.
  • It is keyed by user_id — ensuring personalized pagination behavior for every unique user.

Example Flow​

  1. Configure the pagination store TTL in your model configuration file:
model:
    name: shaped_recsys_prod
    pagination_store_ttl: 3600 //time-to-live in seconds
  1. A rank request is made for a specific user_id.
  2. Shaped returns the first 30 items based on the ranking logic.
  3. On a subsequent request for the same user, Shaped continues where it left off, returning the next 30 items, and so on.
  4. The pagination store tracks the served items, ensuring users don't see the same content again within the configured TTL window.

Controlling Pagination Behavior​

You can customize pagination behavior at request time using the following flags:

  • flush_paginations: true
    • Resets the pagination store for the given user_id.
    • Allows previously returned items to be recommended again.
    • Useful for testing purposes or when you want to refresh the result set.
    • Results may differ slightly from the original request, but you can expect roughly 80% overlap.
    • ⚠️ Recommendation: Avoid using this flag in every request unless you have a specific need. It is primarily intended for debugging and test scenarios.
  • ignore_paginations: true
    • Bypass pagination logic for the current request without resetting the pagination store.
    • Does not update or modify the user's pagination history.
    • Useful for previewing or fetching fresh results while preserving the continuity for future requests.
    • ✅ Use this when you want a temporary override of pagination without losing state.