Ecto v0.13.0 → Overview → Ecto → Model

Ecto.Model

Summary
Types
Functions

Provides convenience functions for defining and working with models.

Using

When used, Ecto.Model works as an “umbrella” module that adds common functionality to your module:

use Ecto.Schema - provides the API necessary to define schemas
import Ecto.Changeset - functions for building and manipulating changesets
import Ecto.Model - functions for working with models and their associations
import Ecto.Query, only: [from: 2] - for generating and manipulating queries

Plus all the modules existing in Ecto.Model.* are brought in too:

use Ecto.Model.Callbacks - provides lifecycle callbacks
use Ecto.Model.Timestamps - automatically set inserted_at and updated_at fields declared via Ecto.Schema.timestamps/1
use Ecto.Model.OptimisticLock - makes the optimistic_lock/1 macro available

However, you can avoid using Ecto.Model altogether in favor of cherry-picking any of the functionality above.

Importing

You may want to import this module in contexts where you are working with different models. For example, in a web application, you may want to import this module into your plugs to provide conveniences for building and accessing model information.

Source

Summary↑

assoc(model_or_models, assoc)	Builds a query for the association in the given model or models
build(struct, assoc, attributes \\ %{})	Builds a struct from the given `assoc` in `model`
primary_key!(struct)	Returns the model primary keys as a keyword list
primary_key(struct)	Returns the model primary keys as a keyword list
put_source(model, new_source)	Update the database source of the model

Types ↑

t :: %atom{}

Functions

assoc(model_or_models, assoc)

(function) # ↑

Builds a query for the association in the given model or models.

Examples

In the example below, we get all comments associated to the given post:

post = Repo.get Post, 1
Repo.all assoc(post, :comments)

assoc/2 can also receive a list of posts, as long as the posts are not empty:

posts = Repo.all from p in Post, where: is_nil(p.published_at)
Repo.all assoc(posts, :comments)

Source

build(struct, assoc, attributes \\ %{})

(function) # ↑

Builds a struct from the given assoc in model.

Examples

If the relationship is a has_one or has_many and the key is set in the given model, the key will automatically be set in the built association:

iex> post = Repo.get(Post, 13)
%Post{id: 13}
iex> build(post, :comments)
%Comment{id: nil, post_id: 13}

Note though it doesn’t happen with belongs to cases, as the key is often the primary key and such is usually generated dynamically:

iex> comment = Repo.get(Post, 13)
%Comment{id: 13, post_id: 25}
iex> build(comment, :post)
%Post{id: nil}

You can also pass the attributes, which can be a map or a keyword list, to set the struct’s fields except the association key.

iex> build(post, :comments, text: "cool")
%Comment{id: nil, post_id: 13, text: "cool"}

iex> build(post, :comments, %{text: "cool"})
%Comment{id: nil, post_id: 13, text: "cool"}

iex> build(post, :comments, post_id: 1)
%Comment{id: nil, post_id: 13}

Source

primary_key(struct)

(function) # ↑

Specs:

primary_key(t) :: Keyword.t

Returns the model primary keys as a keyword list.

Source

primary_key!(struct)

(function) # ↑

Specs:

primary_key!(t) :: Keyword.t | no_return

Returns the model primary keys as a keyword list.

Raises Ecto.NoPrimaryKeyError if the model has no primary key field.

Source

put_source(model, new_source)

(function) # ↑

Update the database source of the model

Examples

post = Repo.get Post, 1
new_post = Ecto.Model.put_source(post, "user_posts")

Source