Ecto.Changeset

Changesets allow filtering, casting, validation and definition of constraints when manipulating models..

There is an example of working with changesets in the introductory documentation in the Ecto module. The functions change/2 and cast/4 are the usual entry points for creating changesets, while the remaining functions are useful for manipulating them.

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 validations can be executed without a need to interact with the database and, therefore, are always executed before attemping to insert or update the entry in the database.

However, constraints can only be checked in a safe way when performing the operation in the database. 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.Model

  schema "users" do
    field :name
    field :email
    field :age, :integer
  end

  def changeset(user, params \\ :empty) do
    user
    |> cast(params, ~w(name email), ~w(age))
    |> validate_format(:email, ~r/@/)
    |> validate_inclusion(:age, 18..100)
    |> unique_constraint(:email)
  end
end

In the changeset/2 function above, we define two validations - one for checking the e-mail format and another to check the age - 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"]

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.

The Ecto.Changeset struct

The fields are:

  • valid? - Stores if the changeset is valid
  • repo - The repository applying the changeset (only set after a Repo function is called)
  • model - The changeset root model
  • params - The parameters as given on changeset creation
  • changes - The changes from parameters that were approved in casting
  • errors - All errors from validations
  • validations - All validations performed in the changeset
  • constraints - All constraints defined in the changeset
  • required - All required fields as a list of atoms
  • optional - All optional fields as a list of atoms
  • filters - Filters (as a map %{field => value}) to narrow the scope of update/delete queries
  • action - The action to be performed with the changeset
  • types - Cache of the model’s field types

Related models

Using changesets you can work with has_one and has_many associations as well as with embedded models. When defining those relations, they have two options that configure how changesets work:

  • :on_cast - specifies function that will be called when casting to a child changeset

  • :on_replace - action that should be taken when the child model is no longer associated to the parent one. This may be invoked in different occasions, for example, when it has been ommited in the list of models for a many relation, or new model was specified for a one relation. Valid values are: :delete (default for associations, and the only one available for embedded models) that deletes the related model from the database, and :nilify that sets the corresponding owner reference column to nil.
Source

Summary

add_error(changeset, key, error)

Adds an error to the changeset

apply_changes(changeset)

Applies the changeset changes to the changeset model

assoc_constraint(changeset, assoc, opts \\ [])

Checks the associated model exists

cast(model_or_changeset, params, required, optional \\ [])

Converts the given params into a changeset for model keeping only the set of required and optional keys

change(model_or_changeset, changes \\ %{})

Wraps the given model in a changeset or adds changes to a changeset

delete_change(changeset, key)

Deletes a change with the given key

fetch_change(changeset, key)

Fetches a change from the given changeset

fetch_field(changeset, key)

Fetches the given field from changes or from the model

force_change(changeset, key, value)

Puts a change on the given key with value

foreign_key_constraint(changeset, field, opts \\ [])

Checks for foreign key constraint in the given field

get_change(changeset, key, default \\ nil)

Gets a change or returns a default value

get_field(changeset, key, default \\ nil)

Gets a field from changes or from the model

merge(changeset1, changeset2)

Merges two changesets

no_assoc_constraint(changeset, assoc, opts \\ [])

Checks the associated model does not exist

put_change(changeset, key, value)

Puts a change on the given key with value

unique_constraint(changeset, field, opts \\ [])

Checks for a unique constraint in the given field

update_change(changeset, key, function)

Updates a change

validate_change(changeset, field, validator)

Validates the given field change

validate_change(changeset, field, metadata, validator)

Stores the validation metadata and validates the given field change

validate_confirmation(changeset, field, opts \\ [])

Validates that the given field matches the confirmation parameter of that field

validate_exclusion(changeset, field, data, opts \\ [])

Validates a change is not included in given the enumerable

validate_format(changeset, field, format, opts \\ [])

Validates a change has the given format

validate_inclusion(changeset, field, data, opts \\ [])

Validates a change is included in the given enumerable

validate_length(changeset, field, opts)

Validates a change is a string of the given length

validate_number(changeset, field, opts)

Validates the properties of a number

validate_subset(changeset, field, data, opts \\ [])

Validates a change, of type enum, is a subset of the given enumerable. Like validate_inclusion/4 for lists

Types

t :: %Ecto.Changeset{valid?: boolean, repo: atom | nil, model: Ecto.Model.t | nil, params: %{String.t => term} | nil, changes: %{atom => term}, required: [atom], optional: [atom], errors: [error], constraints: [constraint], validations: Keyword.t, filters: %{atom => term}, action: action, types: nil | %{atom => Ecto.Type.t}}

error :: {atom, error_message}

error_message :: String.t | {String.t, integer}

action :: nil | :insert | :update | :delete

constraint :: %{type: :unique, constraint: String.t, field: atom, message: error_message}

Functions

add_error(changeset, key, error)

Specs:

Adds an error to the changeset.

Examples

iex> changeset = change(%Post{}, %{title: ""})
iex> changeset = add_error(changeset, :title, "empty")
iex> changeset.errors
[title: "empty"]
iex> changeset.valid?
false
Source
apply_changes(changeset)

Specs:

Applies the changeset changes to the changeset model.

Note this operation is automatically performed on Ecto.Repo.insert!/2 and Ecto.Repo.update!/2, however this function is provided for debugging and testing purposes.

Examples

apply_changes(changeset)
Source
assoc_constraint(changeset, assoc, opts \\ [])

Checks the associated model exists.

This is similar to foreign_key_constraint/3 except that the field is inflected 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 contraint 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, ~w(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 inflected from the table + association field. May be required explicitly for complex cases
Source
cast(model_or_changeset, params, required, optional \\ [])

Specs:

Converts the given params into a changeset for model keeping only the set of required and optional keys.

This function receives a model and some params, and casts the params according to the schema information from model. params is a map with string keys or a map with atom keys containing potentially unsafe data.

During casting, all valid parameters will have their key name converted to an atom and stored as a change in the :changes field of the changeset. All parameters that are not listed in required or optional are ignored.

If casting of all fields is successful and all required fields are present either in the model or in the given params, the changeset is returned as valid.

Examples

iex> changeset = cast(post, params, ~w(title), ~w())
iex> if changeset.valid? do
...>   Repo.update!(changeset)
...> end

Passing a changeset as the first argument:

iex> changeset = cast(post, %{title: "Hello"}, ~w(), ~w(title))
iex> new_changeset = cast(changeset, %{title: "Foo", body: "Bar"}, ~w(title), ~w(body))
iex> new_changeset.params
%{title: "Foo", body: "Bar"}
iex> new_changeset.required
[:title]
iex> new_changeset.optional
[:body]

Empty parameters

The params argument can also be the atom :empty. In such cases, the changeset is automatically marked as invalid, with an empty :changes map. This is useful to run the changeset through all validation steps for introspection:

iex> changeset = cast(post, :empty, ~w(title), ~w())
iex> changeset = validate_length(post, :title, min: 3)
iex> changeset.validations
[title: [min: 3]]

Composing casts

cast/4 also accepts a changeset instead of a model as its first argument. In such cases, all the effects caused by the call to cast/4 (additional and optional fields, 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.

Note that if a field is marked both as required as well as optional (for example by being in the :required field of the argument changeset and also in the optional list passed to cast/4), then it will be marked as required and not optional. This represents the fact that required fields are “stronger” than optional fields.

Source
change(model_or_changeset, changes \\ %{})

Specs:

Wraps the given model 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 attribute in the model.

This function is useful for:

  • wrapping a model inside a changeset
  • directly changing the model without performing castings nor validations
  • directly bulk-adding changes to a changeset

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

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"
Source
delete_change(changeset, key)

Specs:

  • delete_change(t, atom) :: t

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
Source
fetch_change(changeset, key)

Specs:

  • fetch_change(t, atom) :: {:ok, term} | :error

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
Source
fetch_field(changeset, key)

Specs:

  • fetch_field(t, atom) :: {:changes, term} | {:model, term} | :error

Fetches the given field from changes or from the model.

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 model, finally returning :error if no value is available.

For relations this functions will return the models with changes applied, as if they were taken from model. 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)
{:model, "Bar baz bong"}
iex> fetch_field(changeset, :not_a_field)
:error
Source
force_change(changeset, key, value)

Specs:

  • force_change(t, atom, term) :: t

Puts 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"}
Source
foreign_key_constraint(changeset, field, opts \\ [])

Checks for foreign key constraint in the given field.

The foreign key constraint works by relying on the database to check if the associated model 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, ~w(post_id), ~w())
|> 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 inflected from the table + field. May be required explicitly for complex cases
Source
get_change(changeset, key, default \\ nil)

Specs:

  • get_change(t, atom, term) :: term

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
Source
get_field(changeset, key, default \\ nil)

Specs:

  • get_field(t, atom, term) :: term

Gets a field from changes or from the model.

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 model, finally returning default if no value is available.

For relations this functions will return the models with changes applied, as if they were taken from model. 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!"
Source
merge(changeset1, changeset2)

Specs:

  • merge(t, t) :: t

Merges two changesets.

This function merges two changesets provided they have been applied to the same model (their :model field is equal); if the models differ, 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 of changeset2 in case of a conflict. If both changesets has its :params field set to nil, the resulting changeset will have its params set to nil too.
  • changes - changes are merged giving precedence to the changeset2 changes.
  • errors and validations - they are simply concatenated.
  • required and optional - they are merged; all the fields that appear in the optional list of either changesets and also in the required list of the other changeset are moved to the required list of the resulting changeset.

Examples

iex> changeset1 = cast(%{title: "Title"}, %Post{}, ~w(title), ~w(body))
iex> changeset2 = cast(%{title: "New title", body: "Body"}, %Post{}, ~w(title body), ~w())
iex> changeset = merge(changeset1, changeset2)
iex> changeset.changes
%{body: "Body", title: "New title"}
iex> changeset.required
[:title, :body]
iex> changeset.optional
[]

iex> changeset1 = cast(%{title: "Title"}, %Post{body: "Body"}, ~w(title), ~w(body))
iex> changeset2 = cast(%{title: "New title"}, %Post{}, ~w(title), ~w())
iex> merge(changeset1, changeset2)
** (ArgumentError) different models when merging changesets
Source
no_assoc_constraint(changeset, assoc, opts \\ [])

Checks the associated model does not exist.

This is similar to foreign_key_constraint/3 except that the field is inflected 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 contraint 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 to this entry” (for has_one) and “are still associated to this entry” (for has_many)
  • :name - the constraint name. By default, the constraint name is inflected from the association table + association field. May be required explicitly for complex cases
Source
put_change(changeset, key, value)

Specs:

  • put_change(t, atom, term) :: t

Puts a change on the given key with value.

If the change is already present, it is overridden with the new value, also, if the change has the same value as the model, it is not added to the list of changes.

For embedded models if the produced changeset would result in update without changes, the change is skipped.

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"}
Source
unique_constraint(changeset, field, opts \\ [])

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, ~w(email), ~w())
|> 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.

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 inflected from the table + field. May be required explicitly for complex cases

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 constriant name to use:

cast(user, params, ~w(email), ~w())
|> unique_constraint(:email, name: :posts_email_company_id_index)

Alternatively, you can give both unique_index and unique_constraint a name:

# In the migration
create unique_index(:users, [:email, :company_id], name: :posts_special_email_index)

# In the model
cast(user, params, ~w(email), ~w())
|> 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.

If for some reason your database does not support case insensive columns, you can explicitly downcase values before inserting/updating them:

cast(model, params, ~w(email), ~w())
|> update_change(:email, &String.downcase/1)
|> unique_constraint(:email)
Source
update_change(changeset, key, function)

Specs:

  • update_change(t, atom, (term -> term)) :: t

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 cast/4).

Examples

iex> changeset = change(%Post{}, %{impressions: 1})
iex> changeset = update_change(changeset, :impressions, &(&1 + 1))
iex> changeset.changes.impressions
2
Source
validate_change(changeset, field, validator)

Specs:

  • validate_change(t, atom, (atom, term -> [error])) :: t

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
...>   # Value must not be "foo"!
...>   :title, "foo" -> [title: "is foo"]
...>   :title, _     -> []
...> end
iex> changeset.errors
[title: "is_foo"]
Source
validate_change(changeset, field, metadata, validator)

Specs:

  • validate_change(t, atom, any, (atom, term -> [error])) :: t

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]
Source
validate_confirmation(changeset, field, opts \\ [])

Specs:

  • validate_confirmation(t, atom, Enum.t) :: t

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 this does not add a validation error if the confirmation field is nil. 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”

Examples

validate_confirmation(changeset, :email)
validate_confirmation(changeset, :password, message: "passwords do not match")

cast(model, params, ~w(password), ~w())
|> validate_confirmation(:password, message: "passwords do not match")
Source
validate_exclusion(changeset, field, data, opts \\ [])

Validates a change is not included in given the enumerable.

Options

  • :message - the message on failure, defaults to “is reserved”

Examples

validate_exclusion(changeset, :name, ~w(admin superadmin))
Source
validate_format(changeset, field, format, opts \\ [])

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/@/)
Source
validate_inclusion(changeset, field, data, opts \\ [])

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)
Source
validate_length(changeset, field, opts)

Specs:

Validates a change is a string of the given length.

Options

  • :is - the string length must be exactly this value
  • :min - the string length must be greater than or equal to this value
  • :max - the string lenght must be less than or equal to this value
  • :message - the message on failure, depending on the validation, is one of:

    • “should be %{count} characters”
    • “should be at least %{count} characters”
    • “should be at most %{count} characters”

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)
Source
validate_number(changeset, field, opts)

Specs:

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 %{count}”
    • “must be greater than %{count}”
    • “must be less than or equal to %{count}”
    • “must be greater than or equal to %{count}”
    • “must be equal to %{count}”

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)
Source
validate_subset(changeset, field, data, opts \\ [])

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)
Source