Endon (endon v1.0.1) View Source

Endon is an Elixir library that provides helper functions for Ecto, with some inspiration from Ruby on Rails' ActiveRecord.

It's designed to be used within a module that is an Ecto.Schema and provides helpful functions. See the overview and features page for examples.

Link to this section Summary

Functions

Calculate the given aggregate over the given column.

Fetches all entries from the data store matching the given query.

Get the average of a given column.

Get a count of all records matching the conditions.

Insert a new record into the data store.

Insert a new record into the data store.

Delete a record in the data store.

Delete a record in the data store.

Delete multiple records in the data store based on conditions.

Checks if there exists an entry that matches the given query.

Fetches one or more structs from the data store based on the primary key(s) given.

Fetches one or more structs from the data store based on the primary key(s) given.

Find a single record based on given conditions.

Find or create a record based on specific attributes values.

Get the first count records.

Get the last count records.

Get the maximum value of a given column.

Get the minimum value of a given column.

Create a query with the given conditions (the same as where/2 accepts).

Take a query and add conditions (the same as where/2 accepts).

Create a Stream that queries the data store in batches for matching records.

Get the sum of a given column.

Update a record in the data store.

Update a record in the data store.

Update multiple records in the data store based on conditions.

Fetch all entries that match the given conditions.

Link to this section Functions

Link to this function

aggregate(column, aggregate, conditions \\ [])

View Source

Specs

aggregate(
  atom(),
  :avg | :count | :max | :min | :sum,
  keyword() | Ecto.Query.t()
) :: term() | nil

Calculate the given aggregate over the given column.

conditions are anyting accepted by where/2 (including a Ecto.Query.t/0).

Specs

all(opts :: keyword()) :: [Ecto.Schema.t()]

Fetches all entries from the data store matching the given query.

Limit results to those matching these conditions. Value can be anyting accepted by where/2 (including a Ecto.Query.t/0).

Options

  • :order_by - By default, orders by primary key ascending
  • :preload - A list of fields to preload, much like Ecto.Repo.preload/3
  • :offset - Number to offset by
Link to this function

avg(column, conditions \\ [])

View Source

Specs

avg(String.t() | atom(), keyword()) :: float()

Get the average of a given column.

conditions are anyting accepted by where/2 (including a Ecto.Query.t/0).

Link to this function

count(column \\ nil, conditions \\ [])

View Source

Specs

count(atom() | nil, keyword() | Ecto.Query.t()) :: integer()

Get a count of all records matching the conditions.

You can give an optional column; if none is specified, then it's the equivalent of a select count(*).

conditions are anyting accepted by where/2 (including a Ecto.Query.t/0).

Specs

create(keyword() | struct()) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Insert a new record into the data store.

params can be either a Keyword list or Map of attributes and values.

Returns {:ok, struct} if one is created, or {:error, changeset} if there is a validation error.

Specs

create!(keyword() | struct()) :: Ecto.Schema.t()

Insert a new record into the data store.

params can be either a Keyword list or Map of attributes and values.

Returns the struct if created, or raises a Ecto.InvalidChangesetError if there was a validation error.

Specs

delete(Ecto.Schema.t()) :: {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Delete a record in the data store.

The struct must be a Ecto.Schema.t/0 (your module that uses Ecto.Schema).

Returns {:ok, struct} if the record is deleted, or {:error, changeset} if there is a validation error.

Specs

delete!(Ecto.Schema.t()) :: Ecto.Schema.t()

Delete a record in the data store.

The struct must be a Ecto.Schema.t/0 (your module that uses Ecto.Schema).

Returns the struct if it was deleted, or raises a Ecto.InvalidChangesetError if there was a validation error.

Link to this function

delete_where(conditions \\ [])

View Source

Specs

delete_where(keyword()) :: {integer(), nil | [term()]}

Delete multiple records in the data store based on conditions.

Delete all the records that match the given conditions (the same as for where/2).

Note: If you don't supply any conditions, all records will be deleted.

It returns a tuple containing the number of entries and any returned result as second element. The second element is nil by default unless a select is supplied in the update query.

Examples

# this line using Ecto.Repo
from(p in Post, where: p.user_id == 123) |> MyRepo.delete_all

# is the same as this line in Endon
Post.delete_where(user_id: 123)

Specs

exists?(keyword() | Ecto.Query.t()) :: boolean()

Checks if there exists an entry that matches the given query.

conditions are the same as those accepted by where/2.

Link to this function

fetch(id_or_ids, opts \\ [])

View Source

Specs

fetch(integer() | [integer()], keyword()) ::
  {:ok, [Ecto.Schema.t()]} | {:ok, Ecto.Schema.t()} | :error

Fetches one or more structs from the data store based on the primary key(s) given.

If one primary key is given, then one struct will be returned (or :error if not found)

If more than one primary key is given in a list, then all of the structs with those ids will be returned (and :error will be returned if any one of the primary keys can't be found).

Options

Link to this function

find(id_or_ids, opts \\ [])

View Source

Specs

find(integer() | [integer()], keyword()) :: [Ecto.Schema.t()] | Ecto.Schema.t()

Fetches one or more structs from the data store based on the primary key(s) given.

Much like fetch/2, except an error is raised if the record(s) can't be found.

If one primary key is given, then one struct will be returned (or a Ecto.NoResultsError raised if a match isn't found).

If more than one primary key is given in a list, then all of the structs with those ids will be returned (and a Ecto.NoResultsError will be raised if any one of the primary keys can't be found).

Options

Link to this function

find_by(conditions, opts \\ [])

View Source

Specs

find_by(keyword(), keyword()) :: Ecto.Schema.t() | nil

Find a single record based on given conditions.

If a record can't be found, then nil is returned.

Options

Link to this function

find_or_create_by(params)

View Source

Specs

find_or_create_by(keyword() | struct()) :: Ecto.Schema.t()

Find or create a record based on specific attributes values.

Similar to find_by, except that if a record cannot be found with the given attributes then a new one will be created.

Returns {:ok, struct} if one is found/created, or {:error, changeset} if there is a validation error.

Link to this function

first(count \\ 1, opts \\ [])

View Source

Specs

first(integer(), keyword()) :: [Ecto.Schema.t()] | Ecto.Schema.t() | nil

Get the first count records.

If you ask for one thing (count of 1), you will get back the first record or nil if none are found. If you ask for more than one thing (count > 1), you'll get back a list of 0 or more records.

If no order is defined it will order by primary key ascending.

Options

  • :order_by - By default, orders by primary key descending
  • :conditions - Limit results to those matching these conditions. Value can be anyting accepted by where/2 (including a Ecto.Query.t/0).

Examples

 # get the first 3 posts, will return a list
 posts = Post.first(3)

 # get the first post, will return one item (or nil if none found)
 post = Post.first()

 # get the first 3 posts by author id 1
 posts = Post.first(3, conditions: [author_id: 1])
Link to this function

last(count \\ 1, opts \\ [])

View Source

Specs

last(integer(), keyword()) :: [Ecto.Schema.t()] | Ecto.Schema.t() | nil

Get the last count records.

If you ask for one thing (count of 1), you will get back the last record or nil if none are found. If you ask for more than one thing (count > 1), you'll get back a list of 0 or more records.

If no order is defined it will order by primary key descending.

Options

  • :order_by - By default, orders by primary key descending
  • :conditions - Limit results to those matching these conditions. Value can be anyting accepted by where/2 (including a Ecto.Query.t/0).

Examples

 # get the last 3 posts, will return a list
 posts = Post.last(3)

 # get the last post, will return one item
 post = Post.last()

 # get the last 3 posts by author id 1
 posts = Post.last(3, conditions: [author_id: 1])
Link to this function

max(column, conditions \\ [])

View Source

Specs

max(String.t() | atom(), keyword()) :: float() | integer()

Get the maximum value of a given column.

conditions are anyting accepted by where/2 (including a Ecto.Query.t/0).

Link to this function

min(column, conditions \\ [])

View Source

Specs

min(String.t() | atom(), keyword()) :: float() | integer()

Get the minimum value of a given column.

conditions are anyting accepted by where/2 (including a Ecto.Query.t/0).

Specs

scope(keyword()) :: Ecto.Query.t()

Create a query with the given conditions (the same as where/2 accepts).

This will not actually run the query, so you will need to pass the result to where/2 or Ecto.Repo.all/2/Ecto.Repo.one/2.

For instance, this will just run one query to find a record with id 1 with name Bill.

Post.scope(id: 1) |> Post.scope(name: 'Bill') |> Post.first()

This is just a helpful function to make adding conditions easier to an existing Ecto.Schema

Link to this function

scope(query, conditions)

View Source

Specs

scope(Ecto.Query.t(), keyword()) :: Ecto.Query.t()

Take a query and add conditions (the same as where/2 accepts).

This will not actually run the query, so you will need to pass the result to where/2 or Ecto.Repo.all/2/Ecto.Repo.one/2.

For instance:

existing_query = from x in Post
Post.scope(existing_query, id: 1) |> Post.first()

This is just a helpful function to make adding conditions easier to an existing query.

Link to this function

stream_where(conditions \\ [], opts \\ [])

View Source

Specs

stream_where(keyword(), keyword()) :: Enumerable.t()

Create a Stream that queries the data store in batches for matching records.

This is useful for paginating through a very large result set in chunks. The Stream is a composable, lazy enumerable that allows you to iterate through what could be a very large number of records efficiently.

The conditions are anyting accepted by where/2 (including a Ecto.Query.t/0). This function will only work for types that have a primary key that is an integer.

Options

  • :batch_size - Specifies the size of the batch. Defaults to 1000.
  • :start - Specifies the primary key value to start from, inclusive of the value.
  • :finish - Specifies the primary key value to end at, inclusive of the value.

Examples

iex> Enum.each(User.stream_where(), &User.do_some_processing/1)

iex> query = from u in User, where: u.id > 100
iex> Enum.each(User.stream_where(query, batch_size: 10), fn user ->
iex>   User.do_some_processing(user)
iex> end)
Link to this function

sum(column, conditions \\ [])

View Source

Specs

sum(String.t() | atom(), keyword()) :: integer()

Get the sum of a given column.

conditions are anyting accepted by where/2 (including a Ecto.Query.t/0).

Specs

update(Ecto.Schema.t(), keyword() | struct()) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Update a record in the data store.

The struct must be a Ecto.Schema.t/0 (your module that uses Ecto.Schema). params can be either a Keyword list or Map of attributes and values.

Returns {:ok, struct} if one is created, or {:error, changeset} if there is a validation error.

Specs

update!(Ecto.Schema.t(), keyword() | struct()) :: Ecto.Schema.t()

Update a record in the data store.

The struct must be a Ecto.Schema.t/0 (your module that uses Ecto.Schema). params can be either a Keyword list or Map of attributes and values.

Returns the struct if it was updated, or raises a Ecto.InvalidChangesetError if there was a validation error.

Link to this function

update_where(params, conditions \\ [])

View Source

Specs

update_where(keyword(), keyword() | Ecto.Query.t()) ::
  {integer(), nil | [term()]}

Update multiple records in the data store based on conditions.

Update all the records that match the given conditions, setting the given params as attributes. params can be either a Keyword list or Map of attributes and values, and conditions is the same as for where/2.

It returns a tuple containing the number of entries and any returned result as second element. The second element is nil by default unless a select is supplied in the update query.

Link to this function

where(conditions, opts \\ [])

View Source

Specs

where(keyword() | Ecto.Query.t(), keyword()) :: [Ecto.Schema.t()]

Fetch all entries that match the given conditions.

The conditions can be a Ecto.Query.t/0 or a Keyword.t/0.

Options

  • :order_by - By default, orders by primary key ascending
  • :preload - A list of fields to preload, much like Ecto.Repo.preload/3
  • :offset - Number to offset by
  • :limit - Limit results to the given count

Examples

iex> User.where(id: 1)
iex> User.where(name: "billy", age: 23)
iex> User.where([name: "billy", age: 23], limit: 10, order_by: [desc: :id])
iex> query = from u in User, where: u.id > 10
iex> User.where(query, limit: 1)