Endon (endon v1.0.2) 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 Types
Specs
where_conditions() :: Ecto.Query.t() | keyword() | map()
Link to this section Functions
Specs
aggregate(atom(), :avg | :count | :max | :min | :sum, where_conditions()) :: term() | nil
Calculate the given aggregate over the given column.
conditions
are anything 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
anything 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 likeEcto.Repo.preload/3
:offset
- Number to offset by
Specs
avg(String.t() | atom(), where_conditions()) :: float()
Get the average of a given column.
conditions
are anything accepted by where/2
(including a Ecto.Query.t/0
).
Specs
count(atom() | nil, where_conditions()) :: 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 anything accepted by where/2
(including a Ecto.Query.t/0
).
Specs
create(Ecto.Schema.t() | keyword() | map()) :: {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}
Insert a new record into the data store.
params
can be either a Keyword
list, a Map
of attributes and values, or a struct
of the same type being used to invoke create/1
Returns {:ok, struct}
if one is created, or {:error, changeset}
if there is
a validation error.
Specs
create!(Ecto.Schema.t() | keyword() | map()) :: Ecto.Schema.t()
Insert a new record into the data store.
params
can be either a Keyword
list, a Map
of attributes and values, or a struct
of the same type being used to invoke create!/1
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.
Specs
delete_where(where_conditions()) :: {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?(where_conditions()) :: boolean()
Checks if there exists an entry that matches the given query.
conditions
are the same as those accepted by where/2
.
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
:preload
- A list of fields to preload, much likeEcto.Repo.preload/3
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
:preload
- A list of fields to preload, much likeEcto.Repo.preload/3
Specs
find_by(where_conditions(), 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
:preload
- A list of fields to preload, much likeEcto.Repo.preload/3
Specs
find_or_create_by(where_conditions()) :: 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.
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 anything accepted bywhere/2
(including aEcto.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])
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 anything accepted bywhere/2
(including aEcto.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])
Specs
max(String.t() | atom(), where_conditions()) :: float() | integer()
Get the maximum value of a given column.
conditions
are anything accepted by where/2
(including a Ecto.Query.t/0
).
Specs
min(String.t() | atom(), where_conditions()) :: float() | integer()
Get the minimum value of a given column.
conditions
are anything accepted by where/2
(including a Ecto.Query.t/0
).
Specs
scope(where_conditions()) :: 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
Specs
scope(Ecto.Query.t(), where_conditions()) :: 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.
Specs
stream_where(where_conditions(), 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 anything 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)
Specs
sum(String.t() | atom(), where_conditions()) :: integer()
Get the sum of a given column.
conditions
are anything accepted by where/2
(including a Ecto.Query.t/0
).
Specs
update(Ecto.Schema.t(), keyword() | map()) :: {: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() | map()) :: 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.
Specs
update_where(keyword() | map(), where_conditions()) :: {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.
Specs
where(where_conditions(), 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 likeEcto.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)