kura_paginator (kura v2.0.6)

View Source

Pagination helpers for Kura queries.

Offset-based pagination:

Q = kura_query:from(my_schema),
{ok, Page} = kura_paginator:paginate(my_repo, Q, #{page => 2, page_size => 20}).
%% #{entries => [...], page => 2, page_size => 20,
%%   total_entries => 150, total_pages => 8}

Cursor-based (keyset) pagination:

Q = kura_query:from(my_schema),
{ok, Page} = kura_paginator:cursor_paginate(my_repo, Q, #{limit => 20}).
%% #{entries => [...], has_next => true, has_prev => false,
%%   start_cursor => 1, end_cursor => 20}

%% Next page:
{ok, Page2} = kura_paginator:cursor_paginate(my_repo, Q, #{
    limit => 20, after => maps:get(end_cursor, Page)
}).

Summary

Functions

cursor_paginate(Repo, Query, Opts)

Cursor-based (keyset) pagination. Efficient for large datasets - avoids counting and offset scanning.

paginate(Repo, Query, Opts)

Offset-based pagination. Returns entries for the given page along with total counts.

total_pages/2

Calculate total number of pages given total entries and page size.

Functions

cursor_paginate(Repo, Query, Opts)

-spec cursor_paginate(module(),
                      #kura_query{from :: atom() | module() | undefined,
                                  select :: [atom() | term()] | {exprs, [term()]},
                                  wheres :: [term()],
                                  joins :: [term()],
                                  order_bys :: [term()],
                                  group_bys :: [atom()],
                                  havings :: [term()],
                                  limit :: non_neg_integer() | undefined,
                                  offset :: non_neg_integer() | undefined,
                                  distinct :: boolean() | [atom()],
                                  lock :: binary() | undefined,
                                  prefix :: binary() | undefined,
                                  preloads :: [atom() | {atom(), list()}],
                                  ctes :: [{binary(), #kura_query{}}],
                                  combinations ::
                                      [{union | union_all | intersect | except, #kura_query{}}],
                                  include_deleted :: boolean()},
                      map()) ->
                         {ok, map()} | {error, term()}.

Cursor-based (keyset) pagination. Efficient for large datasets - avoids counting and offset scanning.

Options:

  • limit - max entries to return (default: 20)
  • cursor_field - field to paginate on (default: id)
  • 'after' - cursor value; fetch entries after this value (forward)
  • before - cursor value; fetch entries before this value (backward)

When neither after nor before is given, fetches from the beginning.

paginate(Repo, Query, Opts)

-spec paginate(module(),
               #kura_query{from :: atom() | module() | undefined,
                           select :: [atom() | term()] | {exprs, [term()]},
                           wheres :: [term()],
                           joins :: [term()],
                           order_bys :: [term()],
                           group_bys :: [atom()],
                           havings :: [term()],
                           limit :: non_neg_integer() | undefined,
                           offset :: non_neg_integer() | undefined,
                           distinct :: boolean() | [atom()],
                           lock :: binary() | undefined,
                           prefix :: binary() | undefined,
                           preloads :: [atom() | {atom(), list()}],
                           ctes :: [{binary(), #kura_query{}}],
                           combinations :: [{union | union_all | intersect | except, #kura_query{}}],
                           include_deleted :: boolean()},
               map()) ->
                  {ok, map()} | {error, term()}.

Offset-based pagination. Returns entries for the given page along with total counts.

Options:

  • page - page number, 1-based (default: 1)
  • page_size - entries per page (default: 20)

total_pages/2

-spec total_pages(non_neg_integer(), pos_integer()) -> non_neg_integer().

Calculate total number of pages given total entries and page size.