Ecto

v1.0.5

Ecto.Model

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.Autogenerate - automatically handle autogenerate columns before insertion
  • use Ecto.Model.Dependent - performs dependency (associations) management
  • use Ecto.Model.Callbacks - provides lifecycle callbacks
  • use Ecto.Model.Timestamps - automatically sets 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.

Summary

Types

t()

Functions

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_meta(model, opts)

Updates the model metadata

Types 

t :: %atom{}

Functions

assoc(model_or_models, assoc)

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)
build(struct, assoc, attributes \\ %{})

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(Comment, 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}
primary_key(struct)

Specs

primary_key(t) :: Keyword.t

Returns the model primary keys as a keyword list.

primary_key!(struct)

Specs

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

Returns the model primary keys as a keyword list.

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

put_meta(model, opts)

Specs

put_meta(Ecto.Model.t, source: String.t, prefix: String.t, context: term, state: :built | :loaded | :deleted) :: Ecto.Model.t

Updates the model metadata.

It is possible to set:

  • :source - changes the model query source
  • :prefix - changes the model query prefix
  • :context - changes the model meta context
  • :state - changes the model state