endon v0.0.3 Endon View Source

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

It's designed to be used within a module that is an Ecto.Schema and provides helpful functions.

Example

defmodule User do
  use Endon
  use Ecto.Schema

  schema "users" do
    field :name, :string
    field :age, :integer, default: 0
    has_many :posts, Post
  end
end

Once Endon has been included, you can immediately use the helpful methods below. For instance:

iex> user = User.find(1)
iex> user = User.find_by(name: "billy")
iex> count = User.count()
iex> user = User.create!(name: "snake", age: 12)
iex> User.update!(user, age: 23)
iex> User.where([age: 23], preload: :posts)

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

Find a single record based on given conditions

Find or create a record based on specific attributes values

Get the first record, or nil if none are found

Get the last record, or nil if none are found

Get the maximum value of a given column

Get the minimum value of a given column

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
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).

Link to this function

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

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

opts can be any of :order_by, :preload, or :offset

Link to this function

avg(column, conditions \\ []) View Source
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(conditions \\ []) View Source
count(keyword() | Ecto.Query.t()) :: integer()

Get a count of all records matching the conditions.

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

Link to this function

create(params) View Source
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.

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 Endon.ValidationError if there was a validation error.

Link to this function

delete(struct) View Source
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.

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 Endon.ValidationError if there was a validation error.

Link to this function

delete_where(conditions \\ []) View Source
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.

Link to this function

exists?(conditions) View Source
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

find(id_or_ids, opts \\ []) View Source
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.

If one primary key is given, then one struct will be returned (or a Endon.RecordNotFoundError 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 Endon.RecordNotFoundError will be raised if any one of the primary keys can't be found).

The only option that matters here is :preload.

Link to this function

find_by(conditions, opts \\ []) View Source
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.

The only option that matters here is :preload.

Link to this function

find_or_create_by(params) View Source
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(opts \\ []) View Source
first(keyword()) :: Ecto.Schema.t() | nil

Get the first record, or nil if none are found.

opts can include :limit and :order_by (by default, orders by primary key ascending).

Get the last record, or nil if none are found.

opts can include :limit and :order_by (by default, orders by primary key descending).

Link to this function

max(column, conditions \\ []) View Source
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
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).

Link to this function

stream_where(conditions \\ [], opts \\ []) View Source
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.

opts can be any of:

  • 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.

And 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.

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
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).

Link to this function

update(struct, params) View Source
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.

Link to this function

update!(struct, params) View Source
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 Endon.ValidationError if there was a validation error.

Link to this function

update_where(params, conditions \\ []) View Source
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
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.

The options can be any of: :limit, :order_by, :offset, :preload.

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)