Ecto v3.0.1 Ecto.Changeset View Source
Changesets allow filtering, casting, validation and definition of constraints when manipulating structs.
There is an example of working with changesets in the introductory
documentation in the Ecto
module. The functions cast/4
and
change/2
are the usual entry points for creating changesets.
The first one is used to cast and validate external parameters,
such as parameters sent through a form, API, command line, etc.
The second one is used to change data directly from your application.
The remaining functions in this module, such as validations, constraints, association handling, are about manipulating changesets. Let’s discuss some of this extra functionality.
External vs internal data
Changesets allow working with both kinds of data:
internal to the application - for example programmatically generated, or coming from other subsystems. This use case is primarily covered by the
change/2
andput_change/3
functions.external to the application - for example data provided by the user in a form that needs to be type-converted and properly validated. This use case is primarily covered by the
cast/4
function.
Validations and constraints
Ecto changesets provide both validations and constraints which are ultimately turned into errors in case something goes wrong.
The difference between them is that most validations can be
executed without a need to interact with the database and, therefore,
are always executed before attempting to insert or update the entry
in the database. Some validations may happen against the database but
they are inherently unsafe. Those validations start with a unsafe_
prefix, such as unsafe_validate_unique/3
.
On the other hand, constraints rely on the database and are always safe. As a consequence, validations are always checked before constraints. Constraints won’t even be checked in case validations failed.
Let’s see an example:
defmodule User do
use Ecto.Schema
import Ecto.Changeset
schema "users" do
field :name
field :email
field :age, :integer
end
def changeset(user, params \\ %{}) do
user
|> cast(params, [:name, :email, :age])
|> validate_required([:name, :email])
|> validate_format(:email, ~r/@/)
|> validate_inclusion(:age, 18..100)
|> unique_constraint(:email)
end
end
In the changeset/2
function above, we define three validations.
They check that name
and email
fields are present in the
changeset, the e-mail is of the specified format, and the age is
between 18 and 100 - as well as a unique constraint in the email
field.
Let’s suppose the e-mail is given but the age is invalid. The changeset would have the following errors:
changeset = User.changeset(%User{}, %{age: 0, email: "mary@example.com"})
{:error, changeset} = Repo.insert(changeset)
changeset.errors #=> [age: {"is invalid", []}, name: {"can't be blank", []}]
In this case, we haven’t checked the unique constraint in the e-mail field because the data did not validate. Let’s fix the age and assume, however, that the e-mail already exists in the database:
changeset = User.changeset(%User{}, %{age: 42, email: "mary@example.com"})
{:error, changeset} = Repo.insert(changeset)
changeset.errors #=> [email: {"has already been taken", []}]
Validations and constraints define an explicit boundary when the check happens. By moving constraints to the database, we also provide a safe, correct and data-race free means of checking the user input.
Deferred constraints
Some databases support deferred constraints, i.e., constraints which are checked at the end of the transaction rather than at the end of each statement.
Changesets do not support this type of constraints. When working with deferred
constraints, a violation while invoking Repo.insert/2
or Repo.update/2
won’t
return {:error, changeset}
, but rather raise an error at the end of the
transaction.
Empty values
Many times, the data given on cast needs to be further pruned, specially
regarding empty values. For example, if you are gathering data to be
cast from the command line or through an HTML form or any other text-based
format, it is likely those means cannot express nil values. For
those reasons, changesets include the concept of empty values, which are
values that will be automatically converted to the field’s default value
on cast/4
. Those values are stored in the changeset empty_values
field
and default to [""]
.
Associations, embeds and on replace
Using changesets you can work with associations as well as with embedded structs. There are two primary APIs:
cast_assoc/3
andcast_embed/3
- those functions are used when working with external data. In particular, they allow you to change associations and embeds alongside the parent struct, all at once.put_assoc/4
andput_embed/4
- it allows you to replace the association or embed as a whole. This can be used to move associated data from one entry to another, to completely remove or replace existing entries.
See the documentation for those functions for more information.
The :on_replace
option
When using any of those APIs, you may run into situations where Ecto sees
data is being replaced. For example, imagine a Post has many Comments where
the comments have IDs 1, 2 and 3. If you call cast_assoc/3
passing only
the IDs 1 and 2, Ecto will consider 3 is being “replaced” and it will raise
by default. Such behaviour can be changed when defining the relation by
setting :on_replace
option when defining your association/embed according
to the values below:
:raise
(default) - do not allow removing association or embedded data via parent changesets:mark_as_invalid
- if attempting to remove the association or embedded data via parent changeset - an error will be added to the parent changeset, and it will be marked as invalid:nilify
- sets owner reference column tonil
(available only for associations). Use this on abelongs_to
column to allow the association to be cleared out so that it can be set to a new value. Will setaction
on associated changesets to:replace
:update
- updates the association, available only forhas_one
andbelongs_to
. This option will update all the fields given to the changeset including the id for the association:delete
- removes the association or related data from the database. This option has to be used carefully. Will setaction
on associated changesets to:replace
The :delete
option in particular must be used carefully as it would allow
users to delete any associated data. If you need deletion, it is often preferred
to add a separate boolean virtual field to the changeset function that will allow
you to manually mark it for deletion, as in the example below:
defmodule Comment do
use Ecto.Schema
import Ecto.Changeset
schema "comments" do
field :body, :string
field :delete, :boolean, virtual: true
end
def changeset(comment, params) do
cast(comment, params, [:body, :delete])
|> maybe_mark_for_deletion
end
defp maybe_mark_for_deletion(changeset) do
if get_change(changeset, :delete) do
%{changeset | action: :delete}
else
changeset
end
end
end
Schemaless changesets
In the changeset examples so far, we have always used changesets to validate
and cast data contained in a struct defined by an Ecto schema, such as the %User{}
struct defined by the User
module.
However, changesets can also be used with “regular” structs too by passing a tuple with the data and its types:
user = %User{}
types = %{first_name: :string, last_name: :string, email: :string}
changeset =
{user, types}
|> Ecto.Changeset.cast(params["name"], Map.keys(types))
|> Ecto.Changeset.validate_required(...)
|> Ecto.Changeset.validate_length(...)
where the user struct refers to the definition in the following module:
defmodule User do
defstruct [:name, :age]
end
Changesets can also be used with data in a plain map, by following the same API:
data = %{}
types = %{name: :string}
params = %{name: "Callum"}
changeset =
{data, types}
|> Ecto.Changeset.cast(params, Map.keys(types))
|> Ecto.Changeset.validate_required(...)
|> Ecto.Changeset.validate_length(...)
Such functionality makes Ecto extremely useful to cast, validate and prune data even if it is not meant to be persisted to the database.
Changeset actions
Changesets have an action field which is usually set by Ecto.Repo
whenever one of the operations such as insert
or update
is called:
changeset = User.changeset(%User{}, %{age: 42, email: "mary@example.com"})
{:error, changeset} = Repo.insert(changeset)
changeset.action
#=> :insert
This means that when working with changesets that are not meant to be persisted to the database, such as schemaless changesets, you may need to explicitly set the action to one specific value. Frameworks such as Phoenix use the action value to define how HTML forms should act.
Instead of setting the action manually, you may use apply_action/2
that
emulates operations such as Repo.insert
. apply_action/2
will return
{:ok, changes}
if the changeset is valid or {:error, changeset}
, with
the given action
set in the changeset in case of errors.
The Ecto.Changeset struct
The public fields are:
valid?
- Stores if the changeset is validdata
- The changeset source data, for example, a structparams
- The parameters as given on changeset creationchanges
- Thechanges
from parameters that were approved in castingerrors
- All errors from validationsrequired
- All required fields as a list of atomsaction
- The action to be performed with the changesettypes
- Cache of the data’s field typesempty_values
- A list of values to be considered emptyrepo
- The repository applying the changeset (only set after a Repo function is called)repo_opts
- A keyword list of options given to the underlying repository operation
The following fields are private and must not be accessed directly.
validations
constraints
filters
Link to this section Summary
Functions
Adds an error to the changeset
Applies the changeset action only if the changes are valid
Applies the changeset changes to the changeset data
Checks the associated field exists
Applies the given params
as changes for the given data
according to
the given set of permitted
keys. Returns a changeset
Casts the given association with the changeset parameters
Casts the given embed with the changeset parameters
Wraps the given data in a changeset or adds changes to a changeset
Checks for a check constraint in the given field
Returns all constraints in a changeset
Deletes a change with the given key
Checks for an exclusion constraint in the given field
Fetches a change from the given changeset
Fetches the given field from changes or from the data
Forces a change on the given key
with value
Checks for foreign key constraint in the given field
Gets a change or returns a default value
Gets a field from changes or from the data
Merges two changesets
Checks the associated field does not exist
Applies optimistic locking to the changeset
Provides a function to run before emitting changes to the repository
Puts the given association entry or entries as a change in the changeset
Puts a change on the given key
with value
Puts the given embed entry or entries as a change in the changeset
Traverses changeset errors and applies the given function to error messages
Checks for a unique constraint in the given field
Validates that no existing record with a different primary key has the same values for these fields
Updates a change
Validates the given parameter was given as true
Validates the given field
change
Stores the validation metadata
and validates the given field
change
Validates that the given field matches the confirmation parameter of that field
Validates a change is not included in the given enumerable
Validates a change has the given format
Validates a change is included in the given enumerable
Validates a change is a string or list of the given length
Validates the properties of a number
Validates that one or more fields are present in the changeset
Validates a change, of type enum, is a subset of the given enumerable. Like
validate_inclusion/4
for lists
Returns a keyword list of the validations for this changeset
Link to this section Types
action() :: nil | :insert | :update | :delete | :replace | :ignore
t(data_type) :: %Ecto.Changeset{ action: action(), changes: %{optional(atom()) => term()}, constraints: [constraint()], data: data_type, empty_values: term(), errors: [{atom(), error()}], filters: %{optional(atom()) => term()}, params: %{optional(String.t()) => term()} | nil, prepare: [(t() -> t())], repo: atom() | nil, repo_opts: Keyword.t(), required: [atom()], types: nil | %{optional(atom()) => Ecto.Type.t()}, valid?: boolean(), validations: [{atom(), term()}] }
Link to this section Functions
Adds an error to the changeset.
An additional keyword list keys
can be passed to provide additional
contextual information for the error. This is useful when using
traverse_errors/2
Examples
iex> changeset = change(%Post{}, %{title: ""})
iex> changeset = add_error(changeset, :title, "empty")
iex> changeset.errors
[title: {"empty", []}]
iex> changeset.valid?
false
iex> changeset = change(%Post{}, %{title: ""})
iex> changeset = add_error(changeset, :title, "empty", additional: "info")
iex> changeset.errors
[title: {"empty", [additional: "info"]}]
iex> changeset.valid?
false
apply_action(t(), :insert | :update | :delete | :replace) :: {:ok, Ecto.Schema.t() | data()} | {:error, t()}
Applies the changeset action only if the changes are valid.
If the changes are valid, all changes are applied to the changeset data. If the changes are invalid, no changes are applied, and an error tuple is returned with the changeset containing the action that was attempted to be applied.
The action may be one of :insert
, :update
, :delete
, :replace
.
Examples
iex> {:ok, data} = apply_action(changeset, :update)
iex> {:error, changeset} = apply_action(changeset, :update)
%Ecto.Changeset{action: :update}
apply_changes(t()) :: Ecto.Schema.t() | data()
Applies the changeset changes to the changeset data.
This operation will return the underlying data with changes regardless if the changeset is valid or not.
Examples
iex> changeset = change(%Post{author: "bar"}, %{title: "foo"})
iex> apply_changes(changeset)
%Post{author: "bar", title: "foo"}
Checks the associated field exists.
This is similar to foreign_key_constraint/3
except that the
field is inferred from the association definition. This is useful
to guarantee that a child will only be created if the parent exists
in the database too. Therefore, it only applies to belongs_to
associations.
As the name says, a constraint is required in the database for this function to work. Such constraint is often added as a reference to the child table:
create table(:comments) do
add :post_id, references(:posts)
end
Now, when inserting a comment, it is possible to forbid any comment to be added if the associated post does not exist:
comment
|> Ecto.Changeset.cast(params, [:post_id])
|> Ecto.Changeset.assoc_constraint(:post)
|> Repo.insert
Options
:message
- the message in case the constraint check fails, defaults to “does not exist”:name
- the constraint name. By default, the constraint name is inferred from the table + association field. May be required explicitly for complex cases
Applies the given params
as changes for the given data
according to
the given set of permitted
keys. Returns a changeset.
The given data
may be either a changeset, a schema struct or a {data, types}
tuple. The second argument is a map of params
that are cast according
to the type information from data
. params
is a map with string keys
or a map with atom keys containing potentially invalid data.
During casting, all permitted
parameters whose values match the specified
type information will have their key name converted to an atom and stored
together with the value as a change in the :changes
field of the changeset.
All parameters that are not explicitly permitted are ignored.
If casting of all fields is successful, the changeset is returned as valid.
Note that cast/4
validates the types in the params
, but not in the given
data
.
Options
:empty_values
- a list of values to be considered as empty when casting. Defaults to the changeset value, which defaults to[""]
Examples
iex> changeset = cast(post, params, [:title])
iex> if changeset.valid? do
...> Repo.update!(changeset)
...> end
Passing a changeset as the first argument:
iex> changeset = cast(post, %{title: "Hello"}, [:title])
iex> new_changeset = cast(changeset, %{title: "Foo", body: "Bar"}, [:body])
iex> new_changeset.params
%{"title" => "Foo", "body" => "Bar"}
Or creating a changeset from a simple map with types:
iex> data = %{title: "hello"}
iex> types = %{title: :string}
iex> changeset = cast({data, types}, %{title: "world"}, [:title])
iex> apply_changes(changeset)
%{title: "world"}
Composing casts
cast/4
also accepts a changeset as its first argument. In such cases, all
the effects caused by the call to cast/4
(additional errors and changes)
are simply added to the ones already present in the argument changeset.
Parameters are merged (not deep-merged) and the ones passed to cast/4
take precedence over the ones already in the changeset.
Casts the given association with the changeset parameters.
This function should be used when working with the entire association at once (and not a single element of a many-style association) and using data external to the application.
cast_assoc/3
works matching the records extracted from the database (preload)
and compares it with the parameters provided from an external source.
For example, imagine a user has many addresses relationship where post data is sent as follows
%{"name" => "john doe", "addresses" => [
%{"street" => "somewhere", "country" => "brazil", "id" => 1},
%{"street" => "elsewhere", "country" => "poland"},
]}
and then
User
|> Repo.get!(id)
|> Repo.preload(:addresses) # Only required when updating data
|> Ecto.Changeset.cast(params, [])
|> Ecto.Changeset.cast_assoc(:addresses, with: &MyApp.Address.changeset/2)
The parameters for the given association will be retrieved
from changeset.params
. Those parameters are expected to be
a map with attributes, similar to the ones passed to cast/4
.
Once parameters are retrieved, cast_assoc/3
will match those
parameters with the associations already in the changeset record.
Once cast_assoc/3
is called, Ecto will compare each parameter
with the user’s already preloaded addresses and act as follows:
- If the parameter does not contain an ID, the parameter data
will be passed to
MyApp.Address.changeset/2
with a new struct and become an insert operation - If the parameter contains an ID and there is no associated child
with such ID, the parameter data will be passed to
MyApp.Address.changeset/2
with a new struct and become an insert operation - If the parameter contains an ID and there is an associated child
with such ID, the parameter data will be passed to
MyApp.Address.changeset/2
with the existing struct and become an update operation - If there is an associated child with an ID and its ID is not given
as parameter, the
:on_replace
callback for that association will be invoked (see the “On replace” section on the module documentation)
Every time the MyApp.Address.changeset/2
function is invoked, it must
return a changeset. This changeset will be applied to your Repo with
the proper action accordingly.
Note developers are allowed to explicitly set the :action
field of a
changeset to instruct Ecto how to act in certain situations. Let’s suppose
that, if one of the associations has only empty fields, you want to ignore
the entry altogether instead of showing an error. The changeset function could
be written like this:
def changeset(struct, params) do
struct
|> cast(params, [:title, :body])
|> validate_required([:title, :body])
|> case do
%{valid?: false, changes: changes} = changeset when changes == %{} ->
# If the changeset is invalid and has no changes, it is
# because all required fields are missing, so we ignore it.
%{changeset | action: :ignore}
changeset ->
changeset
end
end
Partial changes for many-style associations
By preloading an association using a custom query you can confine the behavior
of cast_assoc/3
. This opens up the possibility to work on a subset of the data,
instead of all associations in the database.
Taking the initial example of users having addresses imagine those addresses are set up to belong to a country. If you want to allow users to bulk edit all addresses that belong to a single country, you can do so by changing the preload query:
query = from MyApp.Address, where: [country: ^edit_country]
User
|> Repo.get!(id)
|> Repo.preload(addresses: query)
|> Ecto.Changeset.cast(params, [])
|> Ecto.Changeset.cast_assoc(:addresses)
This will allow you to cast and update only the association for the given country. The important point for partial changes is that any addresses, which were not preloaded won’t be changed.
Options
:with
- the function to build the changeset from params. Defaults to the changeset/2 function in the association module:required
- if the association is a required field:required_message
- the message on failure, defaults to “can’t be blank”:invalid_message
- the message on failure, defaults to “is invalid”:force_update_on_change
- force the parent record to be updated in the repository if there is a change, defaults to true
Casts the given embed with the changeset parameters.
The parameters for the given embed will be retrieved
from changeset.params
. Those parameters are expected to be
a map with attributes, similar to the ones passed to cast/4
.
Once parameters are retrieved, cast_embed/3
will match those
parameters with the embeds already in the changeset record.
See cast_assoc/3
for an example of working with casts and
associations which would also apply for embeds.
The changeset must have been previously cast
using
cast/4
before this function is invoked.
Options
:with
- the function to build the changeset from params. Defaults to the changeset/2 function in the embed module:required
- if the embed is a required field:required_message
- the message on failure, defaults to “can’t be blank”:invalid_message
- the message on failure, defaults to “is invalid”:force_update_on_change
- force the parent record to be updated in the repository if there is a change, defaults to true
Wraps the given data in a changeset or adds changes to a changeset.
changes
is a map or keyword where the key is an atom representing a
field, association or embed and the value is a term. Note the value
is
directly stored in the changeset with no validation whatsoever. For this
reason, this function is meant for working with data internal to the
application.
When changing embeds and associations, see put_assoc/4
for a complete
reference on the accepted values.
This function is useful for:
- wrapping a struct inside a changeset
- directly changing a struct without performing castings nor validations
- directly bulk-adding changes to a changeset
Changed attributes will only be added if the change does not have the same value as the field in the data.
When a changeset is passed as the first argument, the changes passed as the second argument are merged over the changes already in the changeset if they differ from the values in the struct.
When a {data, types}
is passed as the first argument, a changeset is
created with the given data and types and marked as valid.
See cast/4
if you’d prefer to cast and validate external parameters.
Examples
iex> changeset = change(%Post{})
%Ecto.Changeset{...}
iex> changeset.valid?
true
iex> changeset.changes
%{}
iex> changeset = change(%Post{author: "bar"}, title: "title")
iex> changeset.changes
%{title: "title"}
iex> changeset = change(%Post{title: "title"}, title: "title")
iex> changeset.changes
%{}
iex> changeset = change(changeset, %{title: "new title", body: "body"})
iex> changeset.changes.title
"new title"
iex> changeset.changes.body
"body"
Checks for a check constraint in the given field.
The check constraint works by relying on the database to check if the check constraint has been violated or not and, if so, Ecto converts it into a changeset error.
Options
:message
- the message in case the constraint check fails. Defaults to “is invalid”:name
- the name of the constraint. Required.:match
- how the changeset constraint name is matched against the repo constraint, may be:exact
or:suffix
. Defaults to:exact
.:suffix
matches any repo constraint whichends_with?
:name
to this changeset constraint.
Returns all constraints in a changeset.
A constraint is a map with the following fields:
:type
- the type of the constraint that will be checked in the database, such as:check
,:unique
, etc:constraint
- the database constraint name as a string:match
- the type of match Ecto will perform on a violated constraint against the:constraint
value. It is:exact
,:suffix
or:prefix
:field
- the field a violated constraint will apply the error to:error_message
- the error message in case of violated constraints:error_type
- the type of error that identifies the error message
Deletes a change with the given key.
Examples
iex> changeset = change(%Post{}, %{title: "foo"})
iex> changeset = delete_change(changeset, :title)
iex> get_change(changeset, :title)
nil
Checks for an exclusion constraint in the given field.
The exclusion constraint works by relying on the database to check if the exclusion constraint has been violated or not and, if so, Ecto converts it into a changeset error.
Options
:message
- the message in case the constraint check fails, defaults to “violates an exclusion constraint”:name
- the constraint name. By default, the constraint name is inferred from the table + field. May be required explicitly for complex cases:match
- how the changeset constraint name is matched against the repo constraint, may be:exact
or:suffix
. Defaults to:exact
.:suffix
matches any repo constraint whichends_with?
:name
to this changeset constraint.
Fetches a change from the given changeset.
This function only looks at the :changes
field of the given changeset
and
returns {:ok, value}
if the change is present or :error
if it’s not.
Examples
iex> changeset = change(%Post{body: "foo"}, %{title: "bar"})
iex> fetch_change(changeset, :title)
{:ok, "bar"}
iex> fetch_change(changeset, :body)
:error
Fetches the given field from changes or from the data.
While fetch_change/2
only looks at the current changes
to retrieve a value, this function looks at the changes and
then falls back on the data, finally returning :error
if
no value is available.
For relations, these functions will return the changeset
original data with changes applied. To retrieve raw changesets,
please use fetch_change/2
.
Examples
iex> post = %Post{title: "Foo", body: "Bar baz bong"}
iex> changeset = change(post, %{title: "New title"})
iex> fetch_field(changeset, :title)
{:changes, "New title"}
iex> fetch_field(changeset, :body)
{:data, "Bar baz bong"}
iex> fetch_field(changeset, :not_a_field)
:error
Forces a change on the given key
with value
.
If the change is already present, it is overridden with the new value.
Examples
iex> changeset = change(%Post{author: "bar"}, %{title: "foo"})
iex> changeset = force_change(changeset, :title, "bar")
iex> changeset.changes
%{title: "bar"}
iex> changeset = force_change(changeset, :author, "bar")
iex> changeset.changes
%{title: "bar", author: "bar"}
Checks for foreign key constraint in the given field.
The foreign key constraint works by relying on the database to check if the associated data exists or not. This is useful to guarantee that a child will only be created if the parent exists in the database too.
In order to use the foreign key constraint the first step is to define the foreign key in a migration. This is often done with references. For example, imagine you are creating a comments table that belongs to posts. One would have:
create table(:comments) do
add :post_id, references(:posts)
end
By default, Ecto will generate a foreign key constraint with name “comments_post_id_fkey” (the name is configurable).
Now that a constraint exists, when creating comments, we could annotate the changeset with foreign key constraint so Ecto knows how to convert it into an error message:
cast(comment, params, [:post_id])
|> foreign_key_constraint(:post_id)
Now, when invoking Repo.insert/2
or Repo.update/2
, if the
associated post does not exist, it will be converted into an
error and {:error, changeset}
returned by the repository.
Options
:message
- the message in case the constraint check fails, defaults to “does not exist”:name
- the constraint name. By default, the constraint name is inferred from the table + field. May be required explicitly for complex cases
Gets a change or returns a default value.
Examples
iex> changeset = change(%Post{body: "foo"}, %{title: "bar"})
iex> get_change(changeset, :title)
"bar"
iex> get_change(changeset, :body)
nil
Gets a field from changes or from the data.
While get_change/3
only looks at the current changes
to retrieve a value, this function looks at the changes and
then falls back on the data, finally returning default
if
no value is available.
For relations, these functions will return the changeset data
with changes applied. To retrieve raw changesets, please use get_change/3
.
iex> post = %Post{title: "A title", body: "My body is a cage"}
iex> changeset = change(post, %{title: "A new title"})
iex> get_field(changeset, :title)
"A new title"
iex> get_field(changeset, :not_a_field, "Told you, not a field!")
"Told you, not a field!"
Merges two changesets.
This function merges two changesets provided they have been applied to the
same data (their :data
field is equal); if the data differs, an
ArgumentError
exception is raised. If one of the changesets has a :repo
field which is not nil
, then the value of that field is used as the :repo
field of the resulting changeset; if both changesets have a non-nil
and
different :repo
field, an ArgumentError
exception is raised.
The other fields are merged with the following criteria:
params
- params are merged (not deep-merged) giving precedence to the params ofchangeset2
in case of a conflict. If both changesets have their:params
fields set tonil
, the resulting changeset will have its params set tonil
too.changes
- changes are merged giving precedence to thechangeset2
changes.errors
andvalidations
- they are simply concatenated.required
- required fields are merged; all the fields that appear in the required list of both changesets are moved to the required list of the resulting changeset.
Examples
iex> changeset1 = cast(%Post{}, %{title: "Title"}, [:title])
iex> changeset2 = cast(%Post{}, %{title: "New title", body: "Body"}, [:title, :body])
iex> changeset = merge(changeset1, changeset2)
iex> changeset.changes
%{body: "Body", title: "New title"}
iex> changeset1 = cast(%Post{body: "Body"}, %{title: "Title"}, [:title])
iex> changeset2 = cast(%Post{}, %{title: "New title"}, [:title])
iex> merge(changeset1, changeset2)
** (ArgumentError) different :data when merging changesets
Checks the associated field does not exist.
This is similar to foreign_key_constraint/3
except that the
field is inferred from the association definition. This is useful
to guarantee that parent can only be deleted (or have its primary
key changed) if no child exists in the database. Therefore, it only
applies to has_*
associations.
As the name says, a constraint is required in the database for this function to work. Such constraint is often added as a reference to the child table:
create table(:comments) do
add :post_id, references(:posts)
end
Now, when deleting the post, it is possible to forbid any post to be deleted if they still have comments attached to it:
post
|> Ecto.Changeset.change
|> Ecto.Changeset.no_assoc_constraint(:comments)
|> Repo.delete
Options
:message
- the message in case the constraint check fails, defaults to “is still associated with this entry” (forhas_one
) and “are still associated with this entry” (forhas_many
):name
- the constraint name. By default, the constraint name is inferred from the association table + association field. May be required explicitly for complex cases
Applies optimistic locking to the changeset.
Optimistic locking (or optimistic concurrency control) is a technique that allows concurrent edits on a single record. While pessimistic locking works by locking a resource for an entire transaction, optimistic locking only checks if the resource changed before updating it.
This is done by regularly fetching the record from the database, then checking whether another user has made changes to the record only when updating the record. This behaviour is ideal in situations where the chances of concurrent updates to the same record are low; if they’re not, pessimistic locking or other concurrency patterns may be more suited.
Usage
Optimistic locking works by keeping a “version” counter for each record; this counter gets incremented each time a modification is made to a record. Hence, in order to use optimistic locking, a field must exist in your schema for versioning purpose. Such field is usually an integer but other types are supported.
Examples
Assuming we have a Post
schema (stored in the posts
table), the first step
is to add a version column to the posts
table:
alter table(:posts) do
add :lock_version, :integer, default: 1
end
The column name is arbitrary and doesn’t need to be :lock_version
. Now add
a field to the schema too:
defmodule Post do
use Ecto.Schema
schema "posts" do
field :title, :string
field :lock_version, :integer, default: 1
end
def changeset(:update, struct, params \\ %{}) do
struct
|> Ecto.Changeset.cast(params, [:title])
|> Ecto.Changeset.optimistic_lock(:lock_version)
end
end
Now let’s take optimistic locking for a spin:
iex> post = Repo.insert!(%Post{title: "foo"})
%Post{id: 1, title: "foo", lock_version: 1}
iex> valid_change = Post.changeset(:update, post, %{title: "bar"})
iex> stale_change = Post.changeset(:update, post, %{title: "baz"})
iex> Repo.update!(valid_change)
%Post{id: 1, title: "bar", lock_version: 2}
iex> Repo.update!(stale_change)
** (Ecto.StaleEntryError) attempted to update a stale entry:
%Post{id: 1, title: "baz", lock_version: 1}
When a conflict happens (a record which has been previously fetched is
being updated, but that same record has been modified since it was
fetched), an Ecto.StaleEntryError
exception is raised.
Optimistic locking also works with delete operations. Just call the
optimistic_lock/3
function with the data before delete:
iex> changeset = Ecto.Changeset.optimistic_lock(post, :lock_version)
iex> Repo.delete(changeset)
optimistic_lock/3
by default assumes the field
being used as a lock is an integer. If you want to use another type,
you need to pass the third argument customizing how the next value
is generated:
iex> Ecto.Changeset.optimistic_lock(post, :lock_uuid, fn _ -> Ecto.UUID.generate end)
Provides a function to run before emitting changes to the repository.
Such function receives the changeset and must return a changeset, allowing developers to do final adjustments to the changeset or to issue data consistency commands.
The given function is guaranteed to run inside the same transaction as the changeset operation for databases that do support transactions.
Example
A common use case is updating a counter cache, in this case updating a post’s comment count when a comment is created:
def create_comment(comment, params) do
comment
|> cast(params, [:body, :post_id])
|> prepare_changes(fn changeset ->
if post_id = get_change(changeset, :post_id) do
query = from Post, where: [id: ^post_id]
changeset.repo.update_all(query, inc: [comment_count: 1])
end
changeset
end)
end
We retrieve the repo from the comment changeset itself and use update_all to update the counter cache in one query. Finally, the original changeset must be returned.
Puts the given association entry or entries as a change in the changeset.
This function is used to work with associations as a whole. For example, if a Post has many Comments, it allows you to add, remove or change all comments at once. If your goal is to simply add a new comment to a post, then it is preferred to do so manually, as we will describe later in the “Example: Adding a comment to a post” section.
This function requires the associated data to have been preloaded, except
when the parent changeset has been newly build and not yet persisted.
Missing data will invoke the :on_replace
behaviour defined on the
association.
For associations with cardinality one, nil
can be used to remove the existing
entry. For associations with many entries, an empty list may be given instead.
If the association has no changes, it will be skipped. If the association is invalid, the changeset will be marked as invalid. If the given value is not any of values below, it will raise.
The associated data may be given in different formats:
a map or a keyword list representing changes to be applied to the associated data. A map or keyword list can be given to update the associated data as long as they have matching primary keys. For example,
put_assoc(changeset, :comments, [%{id: 1, title: "changed"}])
will locate the comment with:id
of 1 and update its title. If no comment with such id exists, one is created on the fly. Since only a single comment was given, any other associated comment will be replaced. On all cases, it is expected the keys to be atoms. This API is mostly used in scripts and tests, to make it straight- forward to create schemas with associations at once, such as:Ecto.Changeset.change( %Post{}, title: "foo", comments: [ %{body: "first"}, %{body: "second"} ] )
changesets or structs - when a changeset or struct is given, they are treated as the canonical data and the associated data currently stored in the association is ignored. For instance, the operation
put_assoc(changeset, :comments, [%Comment{id: 1, title: "changed"}])
will send theComment
as is to the database, ignoring any comment currently associated, even if a matching ID is found. If the comment is already persisted to the database, thenput_assoc/4
only takes care of guaranteeing that the comments and the parent data are associated. This extremely useful when associating existing data, as we will see in the “Example: Adding tags to a post” section.
Note, however, that put_assoc/4
always expects all data currently associated to
be given. In both examples above, if the changeset has any other comment besides
the comment with id
equal to 1, all of them will be considered as replaced,
invoking the relevant :on_replace
callback which may potentially remove the
data. In other words, if only a comment with a id equal to 1 is given, it will
be the only one kept. Therefore, put_assoc/4
always works with the whole data,
which may be undesired in some cases. Let’s see an example.
Example: Adding a comment to a post
Imagine a relationship where Post has many comments and you want to add a
new comment to an existing post. While it is possible to use put_assoc/4
for this, it would be unecessarily complex. Let’s see an example.
First, let’s fetch the post with all existing comments:
post = Post |> Repo.get!(1) |> Repo.preload(:comments)
The following approach is wrong:
post
|> Ecto.Changeset.put_assoc(:comments, [%Comment{body: "bad example!"}])
|> Repo.update!()
The reason why the example above is wrong is because put_assoc/4
always
works with the full data. So the example above will effectively erase
all previous comments and only keep the comment you are currently adding.
Instead, you could try:
post
|> Ecto.Changeset.put_assoc(:comments, [%Comment{body: "so-so example!"} | post.comments])
|> Repo.update!()
In this example, we prepend the new comment to the list of existing comments.
Ecto will diff the list of comments currently in post
with the list of comments
given, and correctly insert the new comment to the database. Note, however,
Ecto is doing a lot of work just to figure out something we knew since the
beginning, which is that there is only one new comment.
In cases like above, when you want to work only on a single entry, it is
much easier to simply work on the associated directly. For example, we
could instead set the post
association in the comment:
%Comment{body: "better example"}
|> Ecto.Changeset.change()
|> Ecto.Changeset.put_assoc(:post, post)
|> Repo.insert!()
Alternatively, we can make sure that when we create a comment, it is already associated to the post:
Ecto.build_assoc(post, :comments)
|> Ecto.Changeset.change(body: "great example!")
|> Repo.insert!()
Or we can simply set the post_id in the comment itself:
%Comment{body: "better example", post_id: post.id}
|> Repo.insert!()
In other words, when you find yourself wanting to work only with a subset
of the data, then using put_assoc/4
is most likely unnecessary. Instead,
you want to work on the other side of the association.
Let’s see an example where using put_assoc/4
is a good fit.
Example: Adding tags to a post
Imagine you are receiving a set of tags you want to associate to a post. Let’s imagine that those tags exist upfront and are all persisted to the database. Imagine we get the data in this format:
params = %{"title" => "new post", "tags" => ["learner"]}
Now, since the tags already exist, we will bring all of them from the database and put them directly in the post:
tags = Repo.all(from t in Tag, where: t.name in ^params["tags"])
post
|> Repo.preload(:tags)
|> Ecto.Changeset.cast(params, [:title]) # No need to allow :tags as we put them directly
|> Ecto.Changeset.put_assoc(:tags, tags) # Explicitly set the tags
Since in this case we always require the user to pass all tags
directly, using put_assoc/4
is a great fit. It will automatically
remove any tag not given and properly associate all of the given
tags with the post.
Furthermore, since the tag information is given as structs read directly from the database, Ecto will treat the data as correct and only do the minimum necessary to guarantee that posts and tags are associated, without trying to update or diff any of the fields in the tag struct.
Puts a change on the given key
with value
.
key
is an atom that represents any field, embed or
association in the changeset. Note the value
is directly
stored in the changeset with no validation whatsoever.
For this reason, this function is meant for working with
data internal to the application.
If the change is already present, it is overridden with the new value. If the change has the same value as in the changeset data, it is not added to the list of changes.
When changing embeds and associations, see put_assoc/4
for a complete reference on the accepted values.
Examples
iex> changeset = change(%Post{author: "bar"}, %{title: "foo"})
iex> changeset = put_change(changeset, :title, "bar")
iex> changeset.changes
%{title: "bar"}
iex> changeset = put_change(changeset, :author, "bar")
iex> changeset.changes
%{title: "bar"}
Puts the given embed entry or entries as a change in the changeset.
This function is used to work with embeds as a whole. For embeds with
cardinality one, nil
can be used to remove the existing entry. For
embeds with many entries, an empty list may be given instead.
If the embed has no changes, it will be skipped. If the embed is invalid, the changeset will be marked as invalid.
The list of supported values and their behaviour is described in
put_assoc/4
. If the given value is not any of values listed there,
it will raise.
Although this function accepts an opts
argument, there are no options
currently supported by put_embed/4
.
Traverses changeset errors and applies the given function to error messages.
This function is particularly useful when associations and embeds are cast in the changeset as it will traverse all associations and embeds and place all errors in a series of nested maps.
A changeset is supplied along with a function to apply to each
error message as the changeset is traversed. The error message
function receives an error tuple {msg, opts}
, for example:
{"should be at least %{count} characters", [count: 3, validation: :length, min: 3]}
Examples
iex> traverse_errors(changeset, fn {msg, opts} ->
...> Enum.reduce(opts, msg, fn {key, value}, acc ->
...> String.replace(acc, "%{#{key}}", to_string(value))
...> end)
...> end)
%{title: ["should be at least 3 characters"]}
Optionally function can accept three arguments: changeset
, field
and error tuple {msg, opts}
. It is useful whenever you want to extract
validations rules from changeset.validations
to build detailed error
description.
Checks for a unique constraint in the given field.
The unique constraint works by relying on the database to check if the unique constraint has been violated or not and, if so, Ecto converts it into a changeset error.
In order to use the uniqueness constraint, the first step is to define the unique index in a migration:
create unique_index(:users, [:email])
Now that a constraint exists, when modifying users, we could annotate the changeset with unique constraint so Ecto knows how to convert it into an error message:
cast(user, params, [:email])
|> unique_constraint(:email)
Now, when invoking Repo.insert/2
or Repo.update/2
, if the
email already exists, it will be converted into an error and
{:error, changeset}
returned by the repository. Note that the error
will occur only after hitting the database so it will not be visible
until all other validations pass.
Options
:message
- the message in case the constraint check fails, defaults to “has already been taken”:name
- the constraint name. By default, the constraint name is inferred from the table + field. May be required explicitly for complex cases:match
- how the changeset constraint name is matched against the repo constraint, may be:exact
or:suffix
. Defaults to:exact
.:suffix
matches any repo constraint whichends_with?
:name
to this changeset constraint.
Complex constraints
Because the constraint logic is in the database, we can leverage all the database functionality when defining them. For example, let’s suppose the e-mails are scoped by company id. We would write in a migration:
create unique_index(:users, [:email, :company_id])
Because such indexes have usually more complex names, we need
to explicitly tell the changeset which constraint name to use (here we’re
using the naming convention that unique_index
uses):
cast(user, params, [:email])
|> unique_constraint(:email, name: :users_email_company_id_index)
Notice that the first param is just one of the unique index fields, this will
be used as the error key to the changeset errors keyword list. For example,
the above unique_constraint/3
would generate something like:
Repo.insert!(%User{email: "john@elixir.org", company_id: 1})
changeset = User.changeset(%User{}, %{email: "john@elixir.org", company_id: 1})
{:error, changeset} = Repo.insert(changeset)
changeset.errors #=> [email: {"has already been taken", []}]
Alternatively, you can give both unique_index
and unique_constraint
the same name:
# In the migration
create unique_index(:users, [:email, :company_id], name: :users_email_company_id_index)
# In the changeset function
cast(user, params, [:email])
|> unique_constraint(:email, name: :users_email_company_id_index)
Case sensitivity
Unfortunately, different databases provide different guarantees
when it comes to case-sensitiveness. For example, in MySQL, comparisons
are case-insensitive by default. In Postgres, users can define case
insensitive column by using the :citext
type/extension. In your migration:
execute "CREATE EXTENSION IF NOT EXISTS citext"
create table(:users) do
...
add :email, :citext
...
end
If for some reason your database does not support case insensitive columns, you can explicitly downcase values before inserting/updating them:
cast(data, params, [:email])
|> update_change(:email, &String.downcase/1)
|> unique_constraint(:email)
Validates that no existing record with a different primary key has the same values for these fields.
This function exists to provide quick feedback to users of your
application. It should not be relied on for any data guarantee as it
has race conditions and is inherently unsafe. For example, if this
check happens twice in the same time interval (because the user
submitted a form twice), both checks may pass and you may end-up with
duplicate entries in the database. Therefore, a unique_constraint/3
should also be used to ensure your data won’t get corrupted.
However, because constraints are only checked if all validations succeed, this function can be used as an early check to provide early feedback to users, since most conflicting data will have been inserted prior to the current validation phase.
Examples
unsafe_validate_unique(changeset, [:email], repo)
unsafe_validate_unique(changeset, [:city_name, :state_name], repo)
unsafe_validate_unique(changeset, [:city_name, :state_name], repo, message: "city must be unique within state")
unsafe_validate_unique(changeset, [:city_name, :state_name], repo, prefix: "public")
Updates a change.
The given function
is invoked with the change value only if there
is a change for the given key
. Note that the value of the change
can still be nil
(unless the field was marked as required on validate_required/3
).
Examples
iex> changeset = change(%Post{}, %{impressions: 1})
iex> changeset = update_change(changeset, :impressions, &(&1 + 1))
iex> changeset.changes.impressions
2
Validates the given parameter was given as true.
This validation is used to check for one specific parameter being true and as such does not require the field to effectively exist in the schema or the data being validated.
Options
:message
- the message on failure, defaults to “must be accepted”
Examples
validate_acceptance(changeset, :terms_of_service)
validate_acceptance(changeset, :rules, message: "please accept rules")
Validates the given field
change.
It invokes the validator
function to perform the validation
only if a change for the given field
exists and the change
value is not nil
. The function must return a list of errors
(with an empty list meaning no errors).
In case there’s at least one error, the list of errors will be appended to the
:errors
field of the changeset and the :valid?
flag will be set to
false
.
Examples
iex> changeset = change(%Post{}, %{title: "foo"})
iex> changeset = validate_change changeset, :title, fn :title, title ->
...> # Value must not be "foo"!
...> if title == "foo" do
...> [title: "cannot be foo"]
...> else
...> []
...> end
...> end
iex> changeset.errors
[title: {"cannot be foo", []}]
Stores the validation metadata
and validates the given field
change.
Similar to validate_change/3
but stores the validation metadata
into the changeset validators. The validator metadata is often used
as a reflection mechanism, to automatically generate code based on
the available validations.
Examples
iex> changeset = change(%Post{}, %{title: "foo"})
iex> changeset = validate_change changeset, :title, :useless_validator, fn
...> _, _ -> []
...> end
iex> changeset.validations
[title: :useless_validator]
Validates that the given field matches the confirmation parameter of that field.
By calling validate_confirmation(changeset, :email)
, this
validation will check if both “email” and “email_confirmation”
in the parameter map matches.
Note that if the confirmation field is nil or missing, by default this does not add a validation error. You can specify that the confirmation field is required in the options (see below). Note “email_confirmation” does not need to be added as a virtual field in your schema.
Options
:message
- the message on failure, defaults to “does not match confirmation”:required
- boolean, sets whether existence of confirmation parameter is required for addition of error. Defaults to false
Examples
validate_confirmation(changeset, :email)
validate_confirmation(changeset, :password, message: "does not match password")
cast(data, params, [:password])
|> validate_confirmation(:password, message: "does not match password")
Validates a change is not included in the given enumerable.
Options
:message
- the message on failure, defaults to “is reserved”
Examples
validate_exclusion(changeset, :name, ~w(admin superadmin))
Validates a change has the given format.
The format has to be expressed as a regular expression.
Options
:message
- the message on failure, defaults to “has invalid format”
Examples
validate_format(changeset, :email, ~r/@/)
Validates a change is included in the given enumerable.
Options
:message
- the message on failure, defaults to “is invalid”
Examples
validate_inclusion(changeset, :gender, ["man", "woman", "other", "prefer not to say"])
validate_inclusion(changeset, :age, 0..99)
Validates a change is a string or list of the given length.
Note that the length of a string is counted in graphemes. If using
this validation to match a character limit of a database backend,
it’s likely that the limit ignores graphemes and limits the number
of unicode characters. Then consider using the :count
option to
limit the number of codepoints.
Options
:is
- the length must be exactly this value:min
- the length must be greater than or equal to this value:max
- the length must be less than or equal to this value:count
- what length to count for string,:graphemes
(default) or:codepoints
:message
- the message on failure, depending on the validation, is one of:for strings:
- “should be %{count} character(s)”
- “should be at least %{count} character(s)”
- “should be at most %{count} character(s)”
for lists:
- “should have %{count} item(s)”
- “should have at least %{count} item(s)”
- “should have at most %{count} item(s)”
Examples
validate_length(changeset, :title, min: 3)
validate_length(changeset, :title, max: 100)
validate_length(changeset, :title, min: 3, max: 100)
validate_length(changeset, :code, is: 9)
validate_length(changeset, :topics, is: 2)
Validates the properties of a number.
Options
:less_than
:greater_than
:less_than_or_equal_to
:greater_than_or_equal_to
:equal_to
:message
- the message on failure, defaults to one of:- “must be less than %{number}”
- “must be greater than %{number}”
- “must be less than or equal to %{number}”
- “must be greater than or equal to %{number}”
- “must be equal to %{number}”
Examples
validate_number(changeset, :count, less_than: 3)
validate_number(changeset, :pi, greater_than: 3, less_than: 4)
validate_number(changeset, :the_answer_to_life_the_universe_and_everything, equal_to: 42)
Validates that one or more fields are present in the changeset.
If the value of a field is nil
or a string made only of whitespace,
the changeset is marked as invalid, the field is removed from the changeset’s
changes, and an error is added. Note the error won’t be added though if the
field already has an error.
You can pass a single field name or a list of field names that are required.
Do not use this function to validate associations are required,
instead pass the :required
option to cast_assoc/3
.
Options
:message
- the message on failure, defaults to “can’t be blank”:trim
- a boolean that sets whether whitespaces are removed before running the validation on binaries/strings, defaults to true
Examples
validate_required(changeset, :title)
validate_required(changeset, [:title, :body])
Validates a change, of type enum, is a subset of the given enumerable. Like
validate_inclusion/4
for lists.
Options
:message
- the message on failure, defaults to “has an invalid entry”
Examples
validate_subset(changeset, :pets, ["cat", "dog", "parrot"])
validate_subset(changeset, :lottery_numbers, 0..99)
Returns a keyword list of the validations for this changeset.
The keys in the list are the names of fields, and the values are a validation associated with the field. A field may occur multiple times in the list.
Example
%Post{}
|> change()
|> validate_format(:title, ~r/^\w+:\s/, message: "must start with a topic")
|> validate_length(:title, max: 100)
|> validations()
#=> [
title: {:length, [ max: 100 ]},
title: {:format, ~r/^\w+:\s/}
]
The following validations may be included in the result. The list is not necessarily exhaustive. For example, custom validations written by the developer will also appear in our return value.
This first group contains validations that take a keyword list of validators,
where the validators are shown immediately following the validation type.
This list may also include a message:
key.
{:length, [option]}
min: n
max: n
is: n
count: :graphemes | :codepoints
{:number, [option]}
equal_to: n
greater_than: n
greater_than_or_equal_to: n
less_than: n
less_than_or_equal_to: n
The other validators simply take a value:
{:exclusion, Enum.t}
{:format, ~r/pattern/}
{:inclusion, Enum.t}
{:subset, Enum.t}