Ecto v0.5.0 → Overview → Ecto → Changeset

Ecto.Changeset

Summary
Types
Functions

Changesets allow filtering, casting and validation of model changes.

There is an example of working with changesets in the introductory documentation in the Ecto module.

The Ecto.Changeset struct

The fields are:

valid? - Stores if the changeset is valid
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
required - All required fields as a list of atoms
optional - All optional fields as a list of atoms

Source

Summary↑

add_error(changeset, key, error)	Adds an error to the changeset
cast(params, model, required, optional)	Converts the given `params` into a changeset for `model` keeping only the set of `required` and `optional` keys
delete_change(changeset, key)	Deletes a change with the given key
fetch_change(arg1, key)	Fetches a change
get_change(arg1, key, default \\ nil)	Gets a change or returns default value
put_change(changeset, key, value)	Puts a change on the given key with value
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_exclusion(changeset, field, data)	Validates a change is not in the enumerable
validate_format(changeset, field, format)	Validates a change has the given format
validate_inclusion(changeset, field, data)	Validates a change is included in the enumerable
validate_length(changeset, field, opts)	Validates a change is a string of the given length

Types ↑

t :: %Ecto.Changeset{valid?: boolean, model: Ecto.Model.t | nil, params: %{String.t => term} | nil, changes: %{atom => term}, required: [atom], optional: [atom], errors: [{atom, atom | {atom, [term]}}], validations: [{atom, atom | {atom, [term]}}]}

Functions

add_error(changeset, key, error)

(function) # ↑

Adds an error to the changeset.

Examples

add_error(changeset, :name, :invalid)

Source

cast(params, model, required, optional)

(function) # ↑

Specs:

cast(%{} | nil, Ecto.Model.t, [String.t | atom], [String.t | atom]) :: t

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

This functions receives the params and cast them according to the schema information from model. params are a map with strings as key of potentially unsafe data.

During casting, all valid parameters will have their key name converted to atoms and stored as a change in the changeset. All other 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.

No parameters

The params argument can also be nil. 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.

Source

delete_change(changeset, key)

(function) # ↑

Deletes a change with the given key.

Source

fetch_change(arg1, key)

(function) # ↑

Specs:

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

Fetches a change.

Source

get_change(arg1, key, default \\ nil)

(function) # ↑

Gets a change or returns default value.

Source

put_change(changeset, key, value)

(function) # ↑

Puts a change on the given key with value.

Source

update_change(changeset, key, function)

(function) # ↑

Updates a change.

The function is invoked with the change value only if there is a change for the given key. Notice the value of the change can still be nil (unless the field was marked as required on cast/4).

Source

validate_change(changeset, field, validator)

(function) # ↑

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 a list of errors (empty meaning no errors).

In case of at least one error, they will be stored in the errors field of the changeset and the valid? flag will be set to false.

Source

validate_change(changeset, field, metadata, validator)

(function) # ↑

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.

Source

validate_exclusion(changeset, field, data)

(function) # ↑

Validates a change is not in the enumerable.

Examples

validate_exclusion(changeset, :name, ~w(admin superadmin))

Source

validate_format(changeset, field, format)

(function) # ↑

Validates a change has the given format.

Examples

validate_format(changeset, :email, ~r/@/)

Source

validate_inclusion(changeset, field, data)

(function) # ↑

Validates a change is included in the enumerable.

Examples

validate_inclusion(changeset, :gender, ["male", "female", "who cares?"])
validate_inclusion(changeset, :age, 0..99)

Source

validate_length(changeset, field, opts)

(function) # ↑

Validates a change is a string of the given length.

Examples

validate_length(changeset, :title, 3..100)
validate_length(changeset, :title, min: 3)
validate_length(changeset, :title, max: 100)
validate_length(changeset, :code, is: 9)

Source