EctoCursor (ecto_cursor v0.1.5)

Documentation for EctoCursor.

This is a fully automatic cursor based pagination for Ecto. It requires zero configuraion and is aiming to support arbitrary queries: joins, grouppings with aggregates, etc. Currently absolute support is not guaranteed, as this library is still under development (I appreciate issues).

Usage

defmodule YourApp.Repo do
  use Ecto.Repo,
    otp_app: :your_app,
    adapter: Ecto.Adapters.Postgres
  use EctoCursor
end

This adds function paginate to the Repo:

params = %{cursor: str limit: int max_limit: int}
%Page{entries: [...], cursor: next} = Repo.paginate(query, params)

All parameters are optional, max_limit is used to trim client passed limit. Missing cursor means the beginning of the stream.

Validation of cursor

Cursor produced by the query is signed and supposed to work with the query with exactly the same ordering. Invalid cursor will be simply ignored.

Generation of cursor

Unlike very first version, where cursor was generated with a separate request, now it's all happening in one call. This might break with some complex expressions in select clause. Please report if it's broken for you.

Summary

Functions

Injecting next cursor components into the query. This is done by wrapping original (or default) select into the tuple select({original_select, {componen1, component2, ...}}) and potentiall can mess up complex queries.

Applying condition from the cursor to the query. This includes generating additional where or having clauses and applying a limit.

Functions

Link to this function

append_cursor(query, ctx)

@spec append_cursor(Ecto.Query.t(), EctoCursor.Context.t()) :: Ecto.Query.t()

Injecting next cursor components into the query. This is done by wrapping original (or default) select into the tuple select({original_select, {componen1, component2, ...}}) and potentiall can mess up complex queries.

Link to this function

augument_query(query, map)

@spec augument_query(Ecto.Query.t(), EctoCursor.Context.t()) :: Ecto.Query.t()

Applying condition from the cursor to the query. This includes generating additional where or having clauses and applying a limit.