Paginator v0.6.0 Paginator behaviour View Source

Defines a paginator.

This module adds a paginate/3 function to your Ecto.Repo so that you can paginate through results using opaque cursors.

Usage

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app
  use Paginator
end

Options

Paginator can take any options accepted by paginate/3. This is useful when you want to enforce some options globally across your project.

Example

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app
  use Paginator,
    limit: 10,                           # sets the default limit to 10
    maximum_limit: 100,                  # sets the maximum limit to 100
    include_total_count: true,           # include total count by default
    total_count_primary_key_field: :uuid # sets the total_count_primary_key_field to uuid for calculate total_count
end

Note that these values can be still be overriden when paginate/3 is called.

Use without macros

If you wish to avoid use of macros or you wish to use a different name for the pagination function you can define your own function like so:

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app

  def my_paginate_function(queryable, opts \ [], repo_opts \ []) do
    defaults = [limit: 10] # Default options of your choice here
    opts = Keyword.merge(defaults, opts)
    Paginator.paginate(queryable, opts, __MODULE__, repo_opts)
  end
end

Link to this section Summary

Functions

Generate a cursor for the supplied record, in the same manner as the before and after cursors generated by paginate/3

Callbacks

Fetches all the results matching the query within the cursors

Link to this section Functions

Link to this function cursor_for_record(record, cursor_fields) View Source
cursor_for_record(any(), [atom()]) :: binary()

Generate a cursor for the supplied record, in the same manner as the before and after cursors generated by paginate/3.

For the cursor to be compatiable with paginate/3, cursor_fields must have the same value as the cursor_fields option passed to it.

Link to this section Callbacks

Link to this callback paginate(queryable, opts, repo_opts) View Source
paginate(
  queryable :: Ecto.Query.t(),
  opts :: Keyword.t(),
  repo_opts :: Keyword.t()
) :: Paginator.Page.t()

Fetches all the results matching the query within the cursors.

Options

  • :after - Fetch the records after this cursor.
  • :before - Fetch the records before this cursor.
  • :cursor_fields - The fields used to determine the cursor. In most cases, this should be the same fields as the ones used for sorting in the query.
  • :include_total_count - Set this to true to return the total number of records matching the query. Note that this number will be capped by :total_count_limit. Defaults to false.
  • :total_count_primary_key_field - Running count queries on specified column of the table
  • :limit - Limits the number of records returned per page. Note that this number will be capped by :maximum_limit. Defaults to 50.
  • :maximum_limit - Sets a maximum cap for :limit. This option can be useful when :limit is set dynamically (e.g from a URL param set by a user) but you still want to enfore a maximum. Defaults to 500.
  • :sort_direction - The direction used for sorting. Defaults to :asc.
  • :total_count_limit - Running count queries on tables with a large number of records is expensive so it is capped by default. Can be set to :infinity in order to count all the records. Defaults to 10,000.

Repo options

This will be passed directly to Ecto.Repo.all/2, as such any option supported by this function can be used here.

Example

query = from(p in Post, order_by: [asc: p.inserted_at, asc: p.id], select: p)

Repo.paginate(query, cursor_fields: [:inserted_at, :id], limit: 50)