View Source Ecto.Enum (Ecto v3.10.3)
A custom type that maps atoms to strings or integers.
Ecto.Enum
must be used whenever you want to keep atom values in a field.
Since atoms cannot be persisted to the database, Ecto.Enum
converts them
to a string or an integer when writing to the database and converts them back
to atoms when loading data. It can be used in your schemas as follows:
# Stored as strings
field :status, Ecto.Enum, values: [:foo, :bar, :baz]
or
# Stored as integers
field :status, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
Therefore, the type to be used in your migrations for enum fields depend on the choice above. For the cases above, one would do, respectively:
add :status, :string
or
add :status, :integer
Some databases also support enum types, which you could use in combination with the above.
Composite types, such as :array
, are also supported which allow selecting
multiple values per record:
field :roles, {:array, Ecto.Enum}, values: [:author, :editor, :admin]
Overall, :values
must be a list of atoms or a keyword list. Values will be
cast to atoms safely and only if the atom exists in the list (otherwise an
error will be raised). Attempting to load any string/integer not represented
by an atom in the list will be invalid.
The helper function mappings/2
returns the mappings for a given schema and
field, which can be used in places like form drop-downs. For example, given
the following schema:
defmodule EnumSchema do
use Ecto.Schema
schema "my_schema" do
field :my_enum, Ecto.Enum, values: [:foo, :bar, :baz]
end
end
You can call mappings/2
like this:
Ecto.Enum.mappings(EnumSchema, :my_enum)
#=> [foo: "foo", bar: "bar", baz: "baz"]
If you want the values only, you can use Ecto.Enum.values/2
, and if you want
the dump values only, you can use Ecto.Enum.dump_values/2
.
Embeds
Ecto.Enum
allows to customize how fields are dumped within embeds through the
:embed_as
option. Two alternatives are supported: :values
, which will save
the enum keys (and not their respective mapping), and :dumped
, which will save
the dumped value. The default is :values
. For example, assuming the following
schema:
defmodule EnumSchema do
use Ecto.Schema
schema "my_schema" do
embeds_one :embed, Embed do
field :embed_as_values, Ecto.Enum, values: [foo: 1, bar: 2], embed_as: :values
field :embed_as_dump, Ecto.Enum, values: [foo: 1, bar: 2], embed_as: :dumped
end
end
end
The :embed_as_values
field value will save :foo
or :bar
, while the
:embed_as_dump
field value will save 1
or 2
.
Summary
Functions
Returns the possible dump values for a given schema or types map and field
Returns the possible values for a given schema or types map and field
Functions
Returns the possible dump values for a given schema or types map and field
Returns the possible values for a given schema or types map and field