This protocol allows you to set query options in your Ecto schemas.

Usage

Derive Flop.Schema in your Ecto schema and set the filterable and sortable fields.

defmodule Flop.Pet do
  use Ecto.Schema

  @derive {Flop.Schema,
           filterable: [:name, :species],
           sortable: [:name, :age]}

  schema "pets" do
    field :name, :string
    field :age, :integer
    field :species, :string
  end
end

After that, you can pass the module as the :for option to Flop.validate/2.

iex> Flop.validate(%Flop{order_by: [:name]}, for: Flop.Pet)
{:ok,
 %Flop{
   filters: [],
   limit: nil,
   offset: nil,
   order_by: [:name],
   order_directions: nil,
   page: nil,
   page_size: nil
 }}

iex> {:error, changeset} = Flop.validate(
...>   %Flop{order_by: [:species]}, for: Flop.Pet
...> )
iex> changeset.valid?
false
iex> changeset.errors
[
  order_by: {"has an invalid entry",
   [validation: :subset, enum: [:name, :age]]}
]

Defining default and maximum limits

To define a default or maximum limit, you can set the default_limit and max_limit option when deriving Flop.Schema. The maximum limit will be validated and the default limit applied by Flop.validate/1.

@derive {Flop.Schema,
          filterable: [:name, :species],
          sortable: [:name, :age],
          max_limit: 100,
          default_limit: 50}

Defining a default sort order

To define a default sort order, you can set the default_order_by and default_order_directions options when deriving Flop.Schema. The default values are applied by Flop.validate/1. If no order directions are set, :asc is assumed for all fields.

@derive {Flop.Schema,
          filterable: [:name, :species],
          sortable: [:name, :age],
          default_order_by: [:name, :age],
          default_order_directions: [:asc, :desc]}

Restricting pagination types

By default, page/page_size, offset/limit and cursor-based pagination (first/after and last/before) are enabled. If you want to restrict the pagination type for a schema, you can do that by setting the pagination_types option.

@derive {Flop.Schema,
          filterable: [:name, :species],
          sortable: [:name, :age],
          pagination_types: [:first, :last]}

See also Flop.option/0 and Flop.pagination_type/0. Setting the value to nil allows all pagination types.