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

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

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

Casts the given association with the changeset parameters.

This function requires the association to have been preloaded in the changeset struct. Missing data will invoke the :on_replace behaviour defined on the association.

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/3. Once parameters are retrieved, cast_assoc/3 will match those parameters with the associations already in the changeset record.

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.preload(:addresses)
|> Ecto.Changeset.cast(params, [])
|> Ecto.Changeset.cast_assoc(:addresses)

Once cast_assoc/3 is called, Ecto will compare those parameters with the addresses already associated with the user and act as follows:

• If the parameter does not contain an ID, the parameter data will be passed to 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 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 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)

In other words, cast_assoc/3 is useful when the associated data is managed alongside the parent struct, all at once. If each side of the association is managed separately, it is preferable to use put_assoc/3 and directly instruct Ecto how the association should look like.

For example, imagine you are receiving a set of tags you want to associate to an user. Those tags are meant to exist upfront. Using cast_assoc/3 won’t work as desired because the tags are not managed alongside the user. In such cases, put_assoc/3 will work as desired. With the given parameters:

%{"name" => "john doe", "tags" => ["learner"]}

and then:

tags = Repo.all(from t in Tag, where: t.name in ^params["tags"])

user
|> Repo.preload(:tags)
|> Ecto.Changeset.cast(params) # No need to allow :tags as we put them directly
|> Ecto.Changeset.put_assoc(:tags, tags) # Explicitly set the tags

Note the changeset must have been previously cast using cast/3 before this function is invoked.

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”

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/3. 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/3 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”

Wraps the given data in a changeset or adds 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.

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

Since neither validation nor casting is performed, change/2 expects the keys in changes to be atoms. changes can be a map as well as a keyword list.

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. If changes is an empty map, this function is a no-op.

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/3 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 it matched against the repo constraint, may be :exact or :suffix. Defaults to :exact. :suffix matches any repo constraint which ends_with? :name to this changeset constraint.

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 it matched against the repo constraint, may be :exact or :suffix. Defaults to :exact. :suffix matches any repo constraint which ends_with? :name to this changeset constraint.

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!"

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” (for has_one) and “are still associated with this entry” (for has_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 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)

Puts the given association as a change in the changeset.

This function requires the association to have been preloaded in the changeset struct. Missing data will invoke the :on_replace behaviour defined on the association.

The given value may either be the association struct, a changeset for the given association or a map or keyword list of changes to be applied to the current association. If a map or keyword list are given and there is no association, one will be created.

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 an association struct or changeset, it will raise.

Also see cast_assoc/3 for a discussion of when to use cast_assoc/3 and put_assoc/3.

Puts the given embed as a change in the changeset.

The given value may either be the embed struct, a changeset for the given embed or a map or keyword list of changes to be applied to the current embed. If a map or keyword list are given and there is no embed, one will be created.

If the embed has no changes, it will be skipped. If the embed is invalid, the changeset will be marked as invalid. If the given value is not an embed struct or changeset, it will raise.

Also see cast_assoc/3 for a discussion of when to use cast_assoc/3 and put_assoc/3 which also applies to put_embed/3.

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 it matched against the repo constraint, may be :exact or :suffix. Defaults to :exact. :suffix matches any repo constraint which ends_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:

cast(user, params, [:email])
|> unique_constraint(:email, name: :posts_special_email_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: :posts_email_company_id_index)

# In the changeset function
cast(user, params, [:email])
|> unique_constraint(:email, name: :posts_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 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 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”
• :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 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 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”

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)