AshScylla.DataLayer.Pagination (AshScylla v1.0.4)

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

Types

page_result()

page_token()

Functions

build_paginated_query(table, filters, page_size)

Builds a CQL query string with LIMIT for pagination.

build_paginated_query(table, filters, page_token, page_size)

Builds a CQL query string with LIMIT for pagination, with optional page token.

decode_cursor(cursor)

Decodes a cursor string back to a paging state binary. Returns {:ok, binary} on success or {:error, :invalid_cursor} on failure.

decode_page_token(page_token)

Decodes a page token string back to a paging state binary.

default_page_size()

Returns the default page size.

encode_cursor(paging_state)

Encodes a paging state binary to an opaque cursor string (base64url).

encode_page_token(paging_state)

Encodes a paging state binary to an opaque page token string.

extract_paging_state(arg1)

Extract the paging_state from a query result for use in the next page request. Returns nil if this was the last page.

fetch_page(repo, table, filters, page_token, page_size \\ 50)

Fetches a page of results using Xandra's native paging state.

max_page_size()

Returns the maximum allowed page size.

page_opts(paging_state, 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

page_result()

@type page_result() :: {:ok, [term()], String.t() | nil} | {:error, term()}

page_token()

@type page_token() :: String.t() | nil

Functions

build_paginated_query(table, filters, page_size)

@spec build_paginated_query(String.t(), list(), pos_integer()) :: {String.t(), list()}

Builds a CQL query string with LIMIT for pagination.

Returns {query, params} suitable for repo.query/3.

build_paginated_query(table, filters, page_token, page_size)

@spec build_paginated_query(String.t(), list(), page_token(), pos_integer()) ::
  {String.t(), list()}

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.

decode_cursor(cursor)

@spec decode_cursor(String.t()) :: {:ok, binary()} | {:error, :invalid_cursor}

Decodes a cursor string back to a paging state binary. Returns {:ok, binary} on success or {:error, :invalid_cursor} on failure.

decode_page_token(page_token)

@spec decode_page_token(String.t()) :: {:ok, binary()} | {:error, :invalid_token}

Decodes a page token string back to a paging state binary.

Returns {:ok, binary} on success or {:error, :invalid_token} on failure.

default_page_size()

@spec default_page_size() :: pos_integer()

Returns the default page size.

encode_cursor(paging_state)

@spec encode_cursor(binary()) :: String.t()

Encodes a paging state binary to an opaque cursor string (base64url).

encode_page_token(paging_state)

@spec encode_page_token(binary()) :: String.t()

Encodes a paging state binary to an opaque page token string.

extract_paging_state(arg1)

@spec extract_paging_state(term()) :: binary() | nil

Extract the paging_state from a query result for use in the next page request. Returns nil if this was the last page.

fetch_page(repo, table, filters, page_token, page_size \\ 50)

@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 module
table - The table name
filters - Filter list for WHERE clause
page_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.

max_page_size()

@spec max_page_size() :: pos_integer()

Returns the maximum allowed page size.

page_opts(paging_state, 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.