@spec aliases(t(), module()) :: [atom()]

Returns the names of the alias fields that are required for the order clause of the given Flop.

The second argument is the schema module that derives Flop.Schema.

For example, your schema module might define an alias field called :pet_count.

@derive {
  Flop.Schema,
  filterable: [],
  sortable: [:name, :pet_count],
  adapter_opts: [
    alias_fields: [:pet_count]
  ]
}

If you pass a Flop that orders by the :pet_count field, the returned list will include the :pet_count alias.

iex> aliases(%Flop{order_by: [:name, :pet_count]}, MyApp.Owner)
[:pet_count]

If on the other hand only normal fields are used in the order_by parameter, an empty list will be returned.

iex> aliases(%Flop{order_by: [:name]}, MyApp.Owner)
[]

You can use this to dynamically build the select clause needed for the query.

For more information about alias fields, refer to the module documentation of Flop.Schema.

@spec all(Ecto.Queryable.t(), t(), [option()]) :: [any()]

Applies the given Flop to the given queryable and returns all matchings entries.

iex> Flop.all(MyApp.Pet, %Flop{}, repo: Flop.Repo)
[]

You can also configure a default repo in your config files:

config :flop, repo: MyApp.Repo

This allows you to omit the third argument:

iex> Flop.all(MyApp.Pet, %Flop{}, for: MyApp.Pet)
[]

Note that when using cursor-based pagination, the applied limit will be first + 1 or last + 1. The extra record is removed by Flop.run/3, but not by this function.

Also note that you will need to pass the for option in order for Flop to be able to find your join, compound, alias and custom field configuration.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

@spec count(Ecto.Queryable.t(), t(), [option()]) :: non_neg_integer()

Returns the total count of entries matching the filter conditions of the Flop.

The pagination and ordering option are disregarded.

iex> Flop.count(MyApp.Pet, %Flop{}, repo: Flop.Repo)
0

You can also configure a default repo in your config files:

config :flop, repo: MyApp.Repo

This allows you to omit the third argument:

iex> Flop.count(MyApp.Pet, %Flop{})
0

You can override the default query by passing the :count_query option. This doesn't make a lot of sense when you use count/3 directly, but allows you to optimize the count query when you use one of the run/3, validate_and_run/3 and validate_and_run!/3 functions.

query = join(Pet, :left, [p], o in assoc(p, :owner))
count_query = Pet
count(query, %Flop{}, count_query: count_query, for: Pet)

The filter parameters of the given Flop are applied to the custom count query.

If for some reason you already have the count, you can pass it as the :count option.

count(query, %Flop{}, count: 42, for: Pet)

If you pass both the :count and the :count_query options, the :count option will take precedence.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

Note that you will need to pass the for option in order for Flop to be able to find your join, compound, alias and custom field configuration.

@spec filter(Ecto.Queryable.t(), t(), [option()]) :: Ecto.Queryable.t()

Applies the filter parameter of a Flop.t/0 to an Ecto.Queryable.t/0.

Used by Flop.query/2.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

Note that you will need to pass the for option in order for Flop to be able to find your join, compound, alias and custom field configuration.

@spec meta(Ecto.Queryable.t() | [any()], t(), [option()]) :: Flop.Meta.t()

Returns meta information for the given query and flop that can be used for building the pagination links.

iex> Flop.meta(MyApp.Pet, %Flop{limit: 10}, repo: Flop.Repo)
%Flop.Meta{
  current_offset: 0,
  current_page: 1,
  end_cursor: nil,
  flop: %Flop{limit: 10},
  has_next_page?: false,
  has_previous_page?: false,
  next_offset: nil,
  next_page: nil,
  opts: [repo: Flop.Repo],
  page_size: 10,
  previous_offset: nil,
  previous_page: nil,
  start_cursor: nil,
  total_count: 0,
  total_pages: 0
}

The function returns both the current offset and the current page, regardless of the pagination type. If the offset lies in between pages, the current page number is rounded up. This means that it is possible that the values for current_page and next_page can be identical. This can only occur if you use offset/limit based pagination with arbitrary offsets, but in that case, you will use the previous_offset, current_offset and next_offset values to render the pagination links anyway, so this shouldn't be a problem.

Unless cursor-based pagination is used, this function will run a query to figure get the total count of matching records.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

@spec named_bindings(t(), module(), keyword()) :: [atom()]

Returns the names of the bindings that are required for the filters and order clauses of the given Flop.

The second argument is the schema module that derives Flop.Schema.

For example, your schema module might define a join field called :owner_age.

@derive {
  Flop.Schema,
  filterable: [:name, :owner_age],
  sortable: [:name, :owner_age],
  adapter_opts: [
    join_fields: [owner_age: {:owner, :age}]
  ]
}

If you pass a Flop with a filter on the :owner_age field, the returned list will include the :owner binding.

iex> named_bindings(
...>   %Flop{
...>     filters: [%Flop.Filter{field: :owner_age, op: :==, value: 5}]
...>   },
...>   MyApp.Pet
...> )
[:owner]

If on the other hand only normal fields or compound fields are used in the filter and order options, or if the filter values are nil, an empty list will be returned.

iex> named_bindings(
...>   %Flop{
...>     filters: [
...>       %Flop.Filter{field: :name, op: :==, value: "George"},
...>       %Flop.Filter{field: :owner_age, op: :==, value: nil}
...>     ]
...>   },
...>   MyApp.Pet
...> )
[]

If a join field is part of a compound field, it will be returned.

iex> named_bindings(
...>   %Flop{
...>     filters: [
...>       %Flop.Filter{field: :pet_and_owner_name, op: :==, value: "Mae"}
...>     ]
...>   },
...>   MyApp.Pet
...> )
[:owner]

For custom fields, you can set the :bindings option when you derive the Flop.Schema protocol.

You can use this to dynamically build the join clauses needed for the query. See also Flop.with_named_bindings/4.

For more information about join fields, refer to the module documentation of Flop.Schema.

Options

• :order - If false, only bindings needed for filtering are included. Defaults to true.

@spec order_by(Ecto.Queryable.t(), t(), [option()]) :: Ecto.Queryable.t()

Applies the order_by and order_directions parameters of a Flop.t/0 to an Ecto.Queryable.t/0.

Used by Flop.query/2.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

Note that you will need to pass the for option in order for Flop to be able to find your join, compound, alias and custom field configuration.

@spec paginate(Ecto.Queryable.t(), t(), [option()]) :: Ecto.Queryable.t()

Applies the pagination parameters of a Flop.t/0 to an Ecto.Queryable.t/0.

The function supports both offset/limit based pagination and page/page_size based pagination.

If you validated the Flop.t/0 with Flop.validate/1 before, you can be sure that the given Flop.t/0 only has pagination parameters set for one pagination method. If you pass an unvalidated Flop.t/0 that has pagination parameters set for multiple pagination methods, this function will arbitrarily only apply one of the pagination methods.

Used by Flop.query/2.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

Note that you will need to pass the for option in order for Flop to be able to find your join, compound, alias and custom field configuration.

@spec query(Ecto.Queryable.t(), t(), [option()]) :: Ecto.Queryable.t()

Adds clauses for filtering, ordering and pagination to a Ecto.Queryable.t/0.

The parameters are represented by the Flop.t/0 type. Any nil values will be ignored.

This function does not validate or apply default parameters to the given Flop struct. Be sure to validate any user-generated parameters with validate/2 or validate!/2 before passing them to this function.

Examples

iex> flop = %Flop{limit: 10, offset: 19}
iex> Flop.query(MyApp.Pet, flop)
#Ecto.Query<from p0 in MyApp.Pet, limit: ^10, offset: ^19>

Or enhance an already defined query:

iex> require Ecto.Query
iex> flop = %Flop{limit: 10}
iex> q = Ecto.Query.where(MyApp.Pet, species: "dog")
iex> Flop.query(q, flop, for: MyApp.Pet)
#Ecto.Query<from p0 in MyApp.Pet, where: p0.species == "dog", limit: ^10>

Note that when using cursor-based pagination, the applied limit will be first + 1 or last + 1. The extra record is removed by Flop.run/3.

Also note that you will need to pass the for option in order for Flop to be able to find your join, compound, alias and custom field configuration.

@spec run(Ecto.Queryable.t(), t(), [option()]) :: {[any()], Flop.Meta.t()}

Applies the given Flop to the given queryable, retrieves the data and the meta data.

This function does not validate or apply default parameters to the given flop parameters. You can validate the parameters with Flop.validate/2 or Flop.validate!/2, or you can use Flop.validate_and_run/3 or Flop.validate_and_run!/3 instead of this function.

Note that you will need to pass the for option to both to validate/2, validate!/2 and run/3. Otherwise, Flop would not know how to find your field configuration (join fields, alias fields, custom fields, compound fields).

iex> opts = [for: MyApp.Pet]
iex> flop = Flop.validate!(%{}, opts)
iex> {data, meta} = Flop.run(MyApp.Pet, flop, opts)
iex> data == []
true
iex> match?(%Flop.Meta{}, meta)
true

See the documentation for Flop.validate_and_run/3 for supported options.

@spec validate(t() | map(), [option()]) :: {:ok, t()} | {:error, Flop.Meta.t()}

Validates a Flop.t/0.

Examples

iex> params = %{"limit" => 10, "offset" => 0, "texture" => "fluffy"}
iex> Flop.validate(params)
{:ok,
 %Flop{
   filters: [],
   limit: 10,
   offset: 0,
   order_by: nil,
   order_directions: nil,
   page: nil,
   page_size: nil
 }}

iex> flop = %Flop{offset: -1}
iex> {:error, %Flop.Meta{} = meta} = Flop.validate(flop)
iex> meta.errors
[
  offset: [
    {"must be greater than or equal to %{number}",
     [validation: :number, kind: :greater_than_or_equal_to, number: 0]}
  ]
]

It also makes sure that only one pagination method is used.

iex> params = %{limit: 10, offset: 0, page: 5, page_size: 10}
iex> {:error, %Flop.Meta{} = meta} = Flop.validate(params)
iex> meta.errors
[limit: [{"cannot combine multiple pagination types", []}]]

If you derived Flop.Schema in your Ecto schema to define the filterable and sortable fields, you can pass the module name to the function to validate that only allowed fields are used. The function will also apply any default values set for the schema.

iex> params = %{"order_by" => ["species"]}
iex> {:error, %Flop.Meta{} = meta} = Flop.validate(params, for: MyApp.Pet)
iex> [order_by: [{msg, [_, {_, enum}]}]] = meta.errors
iex> msg
"has an invalid entry"
iex> enum
[:name, :age, :owner_name, :owner_age]

Note that currently, trying to use an existing field that is not allowed as seen above will result in the error message has an invalid entry, while trying to use a field name that does not exist in the schema (or more precisely: a field name that doesn't exist as an atom) will result in the error message is invalid. This might change in the future.

@spec validate!(t() | map(), [option()]) :: t()

Same as Flop.validate/2, but raises an Ecto.InvalidChangesetError if the parameters are invalid.

@spec validate_and_run(Ecto.Queryable.t(), map() | t(), [option()]) ::
  {:ok, {[any()], Flop.Meta.t()}} | {:error, Flop.Meta.t()}

Validates the given flop parameters and retrieves the data and meta data on success.

iex> {:ok, {[], %Flop.Meta{}}} =
...>   Flop.validate_and_run(MyApp.Pet, %Flop{}, for: MyApp.Pet)
iex> {:error, %Flop.Meta{} = meta} =
...>   Flop.validate_and_run(MyApp.Pet, %Flop{limit: -1})
iex> meta.errors
[
  limit: [
    {"must be greater than %{number}",
     [validation: :number, kind: :greater_than, number: 0]}
  ]
]

Options

• for: Passed to Flop.validate/2. Also used to look up the join, alias, compound and custom field configuration.
• repo: The Ecto.Repo module. Required if no default repo is configured.
• cursor_value_func: An arity-2 function to be used to retrieve an unencoded cursor value from a query result item and the order_by fields. Defaults to Flop.Cursor.get_cursor_from_node/2.
• count_query: Lets you override the base query for counting, e.g. if you don't want to include unnecessary joins. The filter parameters are applied to the given query. See also Flop.count/3.

@spec validate_and_run!(Ecto.Queryable.t(), map() | t(), [option()]) ::
  {[any()], Flop.Meta.t()}

Same as Flop.validate_and_run/3, but raises on error.

@spec with_named_bindings(
  Ecto.Queryable.t(),
  t(),
  (Ecto.Queryable.t(), atom() -> Ecto.Queryable.t()),
  keyword()
) :: Ecto.Queryable.t()

Applies a callback function to a query for all named bindings that are necessary for the given Flop parameters.

The callback function must accept a queryable and the name of the binding and return a query that includes the given binding. This is the same as Ecto.Query.with_named_binding/3, except that the callback function must take the second argument.

Options

• :for (required) - The schema module that derives Flop.Schema.
• :order - If false, only bindings needed for filtering are included. Defaults to true.

Example

def list_pets(params) do
  opts = [for: Pet]

  with {:ok, flop} <- Flop.validate(params, opts) do
    Pet
    |> Flop.with_named_bindings(flop, &join_pet_assocs/2, opts)
    |> Flop.run(flop, opts)
  end
end

defp join_pet_assocs(query, :owner) do
  join(query, [p], o in assoc(p, :owner), as: :owner)
end

defp join_pet_assocs(query, :toys) do
  join(query, [p], t in assoc(p, :toys), as: :toys)
end

Since the callback function has the same arguments and return value as the one passed to Ecto.Query.with_named_binding/3, you can reuse the function to add any other bindings you may need for the query besides the ones for Flop filters.

This also means you can use Ecto.Query.with_named_binding/3 to recursively add bindings in case you need intermediate joins to get to a nested association.

def list_owners(params) do
  opts = [for: Owner]

  with {:ok, flop} <- Flop.validate(params, opts) do
    Pet
    |> Flop.with_named_bindings(flop, &join_owner_assocs/2, opts)
    |> Flop.run(flop, opts)
  end
end

defp join_owner_assocs(query, :pets) do
  join(query, [o], p in assoc(o, :pets), as: :pets)
end

defp join_owner_assocs(query, :toys) do
  query
  |> Ecto.Query.with_named_binding(:pets, &join_owner_assocs/2)
  |> join(query, [pets: p], t in assoc(p, :toys), as: :toys)
end