Describes how to convert data to Ecto.Type and eventually into the database.

This behaviour is a superset of the Ecto.Type behaviour, that also contains API level information, like what kinds of filters are allowed.

Built in types

• :map - Ash.Type.Map
• :keyword - Ash.Type.Keyword
• :term - Ash.Type.Term
• :atom - Ash.Type.Atom
• :string - Ash.Type.String
• :integer - Ash.Type.Integer
• :float - Ash.Type.Float
• :duration_name - Ash.Type.DurationName
• :function - Ash.Type.Function
• :boolean - Ash.Type.Boolean
• :struct - Ash.Type.Struct
• :uuid - Ash.Type.UUID
• :binary - Ash.Type.Binary
• :date - Ash.Type.Date
• :time - Ash.Type.Time
• :decimal - Ash.Type.Decimal
• :ci_string - Ash.Type.CiString
• :naive_datetime - Ash.Type.NaiveDatetime
• :utc_datetime - Ash.Type.UtcDatetime
• :utc_datetime_usec - Ash.Type.UtcDatetimeUsec
• :datetime - Ash.Type.DateTime
• :url_encoded_binary - Ash.Type.UrlEncodedBinary
• :union - Ash.Type.Union
• :module - Ash.Type.Module
• :vector - Ash.Type.Vector

Lists/Arrays

To specify a list of values, use {:array, Type}. Arrays are special, and have special constraints:

• :items (term/0) - Constraints for the elements of the list. See the contained type's docs for more.

• :min_length (non_neg_integer/0) - A minimum length for the items

• :max_length (non_neg_integer/0) - A maximum length for the items

• :nil_items? (boolean/0) - Whether or not the list can contain nil items The default value is false.

• :empty_values (list of term/0) - A set of values that, if encountered, will be considered an empty list. The default value is [""].

Defining Custom Types

Generally you add use Ash.Type to your module (it is possible to add @behaviour Ash.Type and define everything yourself, but this is more work and error-prone).

Overriding the {:array, type} behaviour. By defining the *_array versions of cast_input, cast_stored, dump_to_native and apply_constraints, you can override how your type behaves as a collection. This is how the features of embedded resources are implemented. No need to implement them unless you wish to override the default behaviour. Your type is responsible for handling nil values in each callback as well.

Simple example of a float custom type

defmodule GenTracker.AshFloat do
  use Ash.Type

  @impl Ash.Type
  def storage_type(_), do: :float

  @impl Ash.Type
  def cast_input(nil, _), do: {:ok, nil}
  def cast_input(value, _) do
    Ecto.Type.cast(:float, value)
  end

  @impl Ash.Type
  def cast_stored(nil, _), do: {:ok, nil}
  def cast_stored(value, _) do
    Ecto.Type.load(:float, value)
  end

  @impl Ash.Type
  def dump_to_native(nil, _), do: {:ok, nil}
  def dump_to_native(value, _) do
    Ecto.Type.dump(:float, value)
  end
end

All the Ash built-in types are implemented with use Ash.Type so they are good examples to look at to create your own Ash.Type.

Short names

You can define short :atom_names for your custom types by adding them to your Ash configuration:

config :ash, :custom_types, [ash_float: GenTracker.AshFloat]

Doing this will require a recompilation of the :ash dependency which can be triggered by calling:

$ mix deps.compile ash --force

Composite Types

Composite types are composite in the data layer. Many data layers do not support this, but some (like AshPostgres), do. To define a composite type, the following things should be true:

1. A casted value should be a map or struct, for example for a point: %{x: 1, y: 2}
2. The data layer must support composite types, and the data layer representation will be a tuple, i.e {1, 2}
3. Define def composite?(_), do: true in your composite type
4. Define the type & constraints of each item in the tuple, and its name in the map representation: def composite_types(_), do: [{:x, :integer, []}, {:y, :integer, []}]. You can also define a storage key for each item in the tuple, if the underlying type implementation has a different reference for an item, i.e def composite_types(_), do: [{:x, :x_coord, :integer, []}, {:y, :y_coord, :integer, []}]

With the above implemented, your composite type can be used in expressions, for example:

Ash.Query.filter(expr(coordinates[:x] == 1))k

And you can also construct composite types in expressions, for example:

calculate :coordinates, :composite_point, expr(composite_type(%{x: some_value, y: some_other_value}, Point))