Ecto v2.0.0-beta.2 Ecto.Changeset
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 change/2
and cast/3
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.Schema
import Ecto.Changeset
schema "users" do
field :name
field :email
field :age, :integer
end
def changeset(user, params \\ %{}) do
user
|> cast(params, ~w(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 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 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 validationsvalidations
- All validations performed in the changesetconstraints
- All constraints defined in the changesetrequired
- All required fields as a list of atomsfilters
- Filters (as a map%{field => value}
) to narrow the scope of update/delete queriesaction
- The action to be performed with the changesettypes
- Cache of the data’s field typesrepo
- The repository applying the changeset (only set after a Repo function is called)opts
- The options given to the repository
On replace
Using changesets you can work with associations as well as with embedded structs. Sometimes related data may be replaced by incoming data and by default Ecto won’t allow such. Such behaviour can be changed when defining the relation 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),:delete
- removes the association or related data from the database. This option has to be used carefully. You should consider adding a separate boolean virtual field to the changeset function that will alow to manually mark it 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
Summary
Functions
Adds an error to the changeset
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 keys. Returns a changeset
WARNING: This function is deprecated in favor of cast/3
+ validate_required/3
Casts the given association
Casts the given embed
Wraps the given data in a changeset or adds changes to a changeset
Checks for a check constraint in the given field
Deletes a change with the given key
Checks for a exclude 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 as change in the changeset
Puts a change on the given key
with value
Puts the given embed as change in the changeset
Traverses changeset errors and applies function to error messages
Checks for a unique constraint in the given field
Updates a change
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
Types
action :: nil | :insert | :update | :delete | :replace
constraint :: %{type: :unique, constraint: String.t, field: atom, message: error_message}
error :: {atom, error_message}
error_message :: String.t | {String.t, Keyword.t}
t :: %Ecto.Changeset{action: action, changes: %{atom => term}, constraints: [constraint], data: Ecto.Schema.t | nil, errors: [error], filters: %{atom => term}, params: %{String.t => term} | nil, prepare: [(t -> t)], repo: atom | nil, required: [atom], types: nil | %{atom => Ecto.Type.t}, valid?: boolean, validations: Keyword.t}
Functions
Specs
add_error(t, atom, error_message) :: t
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
Specs
apply_changes(t) :: Ecto.Schema.t
Applies the changeset changes to the changeset data.
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)
Checks the associated field 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 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, ~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
Specs
cast(Ecto.Schema.t | t, %{binary => term} | %{atom => term}, [String.t | atom]) ::
t |
no_return
Applies the given params
as changes for the given data
according to
the given set of keys. Returns a changeset.
The given data
may be either a changeset or a struct. The second argument
is a map of params
that are cast according to the schema information
from data
. 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 explicitly allowed are ignored.
If casting of all fields is successful, the changeset is returned as valid.
Examples
iex> changeset = cast(post, params, ~w(title))
iex> if changeset.valid? do
...> Repo.update!(changeset)
...> end
Passing a changeset as the first argument:
iex> changeset = cast(post, %{title: "Hello"}, ~w(title))
iex> new_changeset = cast(changeset, %{title: "Foo", body: "Bar"}, ~w(body))
iex> new_changeset.params
%{title: "Foo", body: "Bar"}
Composing casts
cast/3
also accepts a changeset as its first argument. In such cases, all
the effects caused by the call to cast/3
(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/3
take precedence over the ones already in the changeset.
Specs
cast(Ecto.Schema.t | t, %{binary => term} | %{atom => term}, [String.t | atom], [String.t | atom]) ::
t |
no_return
WARNING: This function is deprecated in favor of cast/3
+ validate_required/3
.
Converts the given params
into a changeset for data
keeping only the set of required
and optional
keys.
Casts the given association.
The parameters for the given association will be retrieved
from changeset.params
and the changeset function in the
association module will be invoked. The function to be
invoked may also be configured by using the :with
option.
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
Casts the given embed.
The parameters for the given embed will be retrieved
from changeset.params
and the changeset function in the
embed module will be invoked. The function to be
invoked may also be configured by using the :with
option.
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
Specs
change(Ecto.Schema.t | t, %{atom => term} | Keyword.t) ::
t |
no_return
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 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 struct. If changes
is an empty map, this
function is a no-op.
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 something like “violates check ‘products_price_check’”:name
- the name of the constraint. Required.
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 a exclude constraint in the given field.
The exclude constraint works by relying on the database to check if the exclude 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 inflected from the table + field. May be required explicitly for complex cases
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
Specs
fetch_field(t, atom) ::
{:changes, term} |
{:data, term} |
: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, this 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, ~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
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
Specs
get_field(t, atom, term) :: term
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 this 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
andoptional
- 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> 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 :data when merging changesets
Checks the associated field 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 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 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
Specs
optimistic_lock(Ecto.Schema.t | t, atom, (integer -> integer)) ::
t |
no_return
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(struct, params, ~w(: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)
Finally, keep in 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.
Puts the given association as change in the changeset.
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 are 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, it will raise.
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 in the changeset data, it is not added to the list of changes.
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 as 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 are 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, it will raise.
Specs
traverse_errors(t, (error_message -> String.t)) :: %{atom => String.t}
Traverses changeset errors and applies 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 a single argument matching either:
{message, opts}
- The string error message and options, for example{"should be at least %{count} characters", [count: 3]}
message
- The string error message
Examples
iex> traverse_errors(changeset, fn
{msg, opts} -> String.replace(msg, "%{count}", to_string(opts[:count]))
msg -> msg
end)
%{title: "should be at least 3 characters"}
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. 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 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 constraint 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 changeset function
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 insensitive columns, you can explicitly downcase values before inserting/updating them:
cast(data, params, ~w(email), ~w())
|> update_change(:email, &String.downcase/1)
|> unique_constraint(:email)
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/3
).
Examples
iex> changeset = change(%Post{}, %{impressions: 1})
iex> changeset = update_change(changeset, :impressions, &(&1 + 1))
iex> changeset.changes.impressions
2
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"]
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 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: "does not match password")
cast(data, params, ~w(password), ~w())
|> 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.
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: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 %{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)
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.
You can pass a single field name or a list of field names that are required.
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)