Ecto.Enum

Пользовательский тип, который сопоставляет атомы со строками или целыми числами.

Ecto.Enum следует использовать, когда вы хотите хранить значения-атомы в поле. Поскольку атомы нельзя сохранить в базе данных, Ecto.Enum преобразует их в строки или целые числа при записи в базу данных и преобразует обратно в атомы при загрузке данных. Его можно использовать в схемах следующим образом:

# Stored as strings
field :status, Ecto.Enum, values: [:foo, :bar, :baz]

или

# Stored as integers
field :status, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]

Поэтому тип, используемый в миграциях для полей перечисления, зависит от сделанного выше выбора. Для приведённых выше случаев нужно соответственно сделать следующее:

add :status, :string

или

add :status, :integer

Некоторые базы данных также поддерживают типы перечислений, которые можно использовать вместе с описанным выше.

Поддерживаются также составные типы, такие как :array, которые позволяют выбирать несколько значений для каждой записи:

field :roles, {:array, Ecto.Enum}, values: [:author, :editor, :admin]

В целом, :values должен быть списком атомов или ключевым списком. Значения будут безопасно преобразованы в атомы, только если атом присутствует в списке (в противном случае будет выдана ошибка). Попытка загрузить любую строку или целое число, которому не соответствует атом в списке, завершится ошибкой.

Вспомогательная функция mappings/2 возвращает сопоставления для заданной схемы и поля. Их можно использовать, например, в выпадающих списках форм. Примеры см. в разделе mappings/2.

Если вам нужны только значения, используйте values/2, а если нужны только значения, которые можно выгрузить в базу данных, используйте dump_values/2.

Встраиваемые структуры

Ecto.Enum позволяет настраивать способ выгрузки полей во встраиваемых структурах с помощью параметра :embed_as. Поддерживаются два варианта: :values, при котором сохраняются ключи перечисления (а не соответствующие им значения из сопоставления), и :dumped, при котором сохраняется выгруженное значение. По умолчанию используется :values. Например, предположим, что имеется следующая схема:

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

В поле :embed_as_values будут сохранены значения :foo или :bar, а в поле :embed_as_dump — значения 1 или 2.

Краткое описание

cast_value(schema_or_types, field, value): Преобразует значение из заданной schema и field.
dump_values(schema_or_types, field): Возвращает возможные значения для выгрузки в базу данных для заданной схемы или карты типов и поля
mappings(schema_or_types, field): Возвращает сопоставления между значениями и значениями для выгрузки в базу данных.
values(schema_or_types, field): Возвращает возможные значения для заданной схемы или карты типов и поля.

Функции

cast_value(schema_or_types, field, value)Исходный код

@spec cast_value(module() | map(), atom(), binary() | atom() | integer()) ::
  {:ok, atom()} | :error

Преобразует значение из заданной schema и field.

Примеры

Предположим, имеется следующая схема:

defmodule MySchema do
  use Ecto.Schema

  schema "my_schema" do
    field :my_string_enum, Ecto.Enum, values: [:foo, :bar, :baz]
    field :my_integer_enum, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
  end
end

Тогда:

Ecto.Enum.cast_value(MySchema, :my_string_enum, "foo")
#=> {:ok, :foo}

Ecto.Enum.cast_value(MySchema, :my_string_enum, :foo)
#=> {:ok, :foo}

Ecto.Enum.cast_value(MySchema, :my_string_enum, "qux")
#=> :error

Ecto.Enum.cast_value(MySchema, :my_integer_enum, 1)
#=> {:ok, :foo}

Ecto.Enum.cast_value(MySchema, :my_integer_enum, :foo)
#=> {:ok, :foo}

Ecto.Enum.cast_value(MySchema, :my_integer_enum, 6)
#=> :error

schema_or_types также может быть картой типов. Дополнительные сведения см. в разделе mappings/2.

dump_values(schema_or_types, field)Исходный код

@spec dump_values(module() | map(), atom()) :: [String.t()] | [integer()]

Возвращает возможные значения для выгрузки в базу данных для заданной схемы или карты типов и поля

«Значения для выгрузки» — это значения, которые можно выгрузить в базу данных. Для перечислений, хранящихся в виде строк, это строки, которые будут сохранены в базе данных. Для перечислений, хранящихся в виде целых чисел, это целые числа, которые будут сохранены в базе данных.

Примеры

Предположим, имеется следующая схема:

defmodule MySchema do
  use Ecto.Schema

  schema "my_schema" do
    field :my_string_enum, Ecto.Enum, values: [:foo, :bar, :baz]
    field :my_integer_enum, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
  end
end

Тогда:

Ecto.Enum.dump_values(MySchema, :my_string_enum)
#=> ["foo", "bar", "baz"]

Ecto.Enum.dump_values(MySchema, :my_integer_enum)
#=> [1, 2, 5]

schema_or_types также может быть картой типов. Дополнительные сведения см. в разделе mappings/2.

mappings(schema_or_types, field)Исходный код

@spec mappings(module() | map(), atom()) :: keyword(String.t() | integer())

Возвращает сопоставления между значениями и значениями для выгрузки в базу данных.

Примеры

Предположим, имеется следующая схема:

defmodule MySchema do
  use Ecto.Schema

  schema "my_schema" do
    field :my_string_enum, Ecto.Enum, values: [:foo, :bar, :baz]
    field :my_integer_enum, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
  end
end

Вот несколько примеров использования mappings/2 с этой схемой:

Ecto.Enum.mappings(MySchema, :my_string_enum)
#=> [foo: "foo", bar: "bar", baz: "baz"]

Ecto.Enum.mappings(MySchema, :my_integer_enum)
#=> [foo: 1, bar: 2, baz: 5]

Примеры вызова mappings/2 с картой типов:

schemaless_types = %{
  my_enum: Ecto.ParameterizedType.init(Ecto.Enum, values: [:foo, :bar, :baz]),
  my_integer_enum: Ecto.ParameterizedType.init(Ecto.Enum, values: [foo: 1, bar: 2, baz: 5])
}

Ecto.Enum.mappings(schemaless_types, :my_enum)
#=> [foo: "foo", bar: "bar", baz: "baz"]
Ecto.Enum.mappings(schemaless_types, :my_integer_enum)
#=> [foo: 1, bar: 2, baz: 5]

values(schema_or_types, field)Исходный код

@spec values(module() | map(), atom()) :: [atom()]

Возвращает возможные значения для заданной схемы или карты типов и поля.

Эти значения представляют собой атомы, обозначающие различные допустимые значения поля.

Примеры

Предположим, имеется следующая схема:

defmodule MySchema do
  use Ecto.Schema

  schema "my_schema" do
    field :my_string_enum, Ecto.Enum, values: [:foo, :bar, :baz]
    field :my_integer_enum, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
  end
end

Тогда:

Ecto.Enum.values(MySchema, :my_string_enum)
#=> [:foo, :bar, :baz]

Ecto.Enum.values(MySchema, :my_integer_enum)
#=> [:foo, :bar, :baz]