Token-based pagination support for AshScylla.
ScyllaDB/Cassandra uses Xandra's native paging state mechanism for efficient pagination.
Token-Based Pagination
AshScylla uses keyset pagination by default (data_layer_keyset_by_default?/0
returns true). When pagination :token is set in the scylla DSL,
queries use Xandra's built-in paging state to efficiently page through results.
Usage
# First page
{:ok, records, next_page_token} =
AshScylla.DataLayer.Pagination.fetch_page(repo, table, filters, nil, 10)
# Subsequent pages
{:ok, records, next_page_token} =
AshScylla.DataLayer.Pagination.fetch_page(repo, table, filters, page_token, 10)Page Token Format
Page tokens are opaque binaries returned by Xandra's paging_state. They should be treated as opaque by callers and only passed back to fetch the next page.
Limits
Default page size: 50. Maximum page size: 1000.
Summary
Functions
Builds a CQL query string with LIMIT for pagination.
Builds a CQL query string with LIMIT for pagination, with optional page token.
Decodes a cursor string back to a paging state binary.
Returns {:ok, binary} on success or {:error, :invalid_cursor} on failure.
Decodes a page token string back to a paging state binary.
Returns the default page size.
Encodes a paging state binary to an opaque cursor string (base64url).
Encodes a paging state binary to an opaque page token string.
Extract the paging_state from a query result for use in the next page request.
Returns nil if this was the last page.
Fetches a page of results using Xandra's native paging state.
Returns the maximum allowed page size.
Build query options for a given page request.
Pass nil for the first page, or a previously returned paging_state
binary for subsequent pages.
Types
Functions
@spec build_paginated_query(String.t(), list(), pos_integer()) :: {:ok, {String.t(), list()}} | {:error, {:unknown_filter, term()}}
Builds a CQL query string with LIMIT for pagination.
Returns {query, params} suitable for repo.query/3.
@spec build_paginated_query(String.t(), list(), page_token(), pos_integer()) :: {:ok, {String.t(), list()}} | {:error, {:unknown_filter, term()}}
Builds a CQL query string with LIMIT for pagination, with optional page token.
When page_token is non-nil, adds a token() > ? condition to the WHERE clause.
Returns {query, params} suitable for repo.query/3.
uuid_fields and cql_types are optional and, when provided, ensure UUID
filter values are converted to 16-byte binaries tagged as {"uuid", bin}
(otherwise ScyllaDB rejects them with "Validation failed for uuid - got N bytes").
Decodes a cursor string back to a paging state binary.
Returns {:ok, binary} on success or {:error, :invalid_cursor} on failure.
Decodes a page token string back to a paging state binary.
Returns {:ok, binary} on success or {:error, :invalid_token} on failure.
@spec default_page_size() :: pos_integer()
Returns the default page size.
Encodes a paging state binary to an opaque cursor string (base64url).
Encodes a paging state binary to an opaque page token string.
Extract the paging_state from a query result for use in the next page request.
Returns nil if this was the last page.
@spec fetch_page(module(), String.t(), list(), page_token(), pos_integer()) :: page_result()
Fetches a page of results using Xandra's native paging state.
Parameters
repo- The Ecto repo moduletable- The table namefilters- Filter list for WHERE clausepage_token- Opaque page token from previous page (nil for first page)page_size- Number of results per page (default: 50, max: 1000)
Returns
{:ok, records, next_page_token} where next_page_token is nil
when there are no more pages.
@spec fetch_page( module(), String.t(), list(), page_token(), pos_integer(), MapSet.t(), map() ) :: page_result()
@spec max_page_size() :: pos_integer()
Returns the maximum allowed page size.
@spec page_opts(page_token() | nil, pos_integer()) :: keyword()
Build query options for a given page request.
Pass nil for the first page, or a previously returned paging_state
binary for subsequent pages.