Embedded Resources

Embedded resources are stored as maps in attributes of other resources. They are great for storing structured data, and support a whole range of useful features that resources support. For example, you can have calculations, validations, policies and even relationships on embedded resources.

Consider Simpler Alternatives

Before creating a full embedded resource, consider if one of these simpler options might meet your needs:

Ash.TypedStruct

For simple structured data with type validation but without the need for calculations, validations, or policies:

elixir

defmodule MyApp.Address do
  use Ash.TypedStruct

  typed_struct do
    field :street, :string, allow_nil?: false
    field :city, :string, allow_nil?: false
    field :state, :string, constraints: [max_length: 2]
    field :zip, :string, constraints: [match: ~r/^\d{5}$/]
  end
end

Ash.Type.Struct

For when you need a generic struct type with field specifications:

elixir

attribute :address, :struct do
  constraints fields: [
    street: [type: :string, allow_nil?: false],
    city: [type: :string, allow_nil?: false],
    state: [type: :string, constraints: [max_length: 2]],
    zip: [type: :string, constraints: [match: ~r/^\d{5}$/]]
  ]
end

Use embedded resources when you need the full power of Ash resources, including actions, calculations, validations, and policies.

Example Embedded Resource

Here is an example of a simple embedded resource:

elixir

defmodule MyApp.Profile do
  use Ash.Resource,
    data_layer: :embedded # Use the atom `:embedded` as the data layer.

  attributes do
    attribute :first_name, :string, public?: true
    attribute :last_name, :string, public?: true
  end
end

Embedded resources can't do everything {: .info}

Embedded resources cannot have aggregates, or expression calculations that rely on data-layer-specific capabilities.

Adding embedded resource attributes

Embedded resources define an Ash.Type under the hood, meaning you can use them anywhere you would use an Ash type.

elixir

defmodule MyApp.User do
  use Ash.Resource, ...

  attributes do
    ...

    attribute :profile, MyApp.Profile, public?: true
    attribute :profiles, {:array, MyApp.Profile}, public?: true # You can also have an array of embeds
  end
end

Handling nil values

By default, all fields on an embedded resource will be included in the data layer, including keys with nil values. To prevent this, add the embed_nil_values? option to use Ash.Resource. For example:

elixir

defmodule YourEmbed do
  use Ash.Resource,
    data_layer: :embedded,
    embed_nil_values?: false
end

Editing embedded attributes

If you manually supply instances of the embedded structs, the structs you provide are used with no validation. For example:

elixir

Ash.Changeset.for_update(user, :update, %{profile: %MyApp.Profile{first_name: "first_name", last_name: "last_name"}})

However, you can also treat embedded resources like regular resources that can be "created", "updated", and "destroyed". To do this, provide maps as the input, instead of structs. In the example above, if you just wanted to change the first_name, you'd provide:

elixir

Ash.Changeset.for_update(user, :update, %{profile: %{first_name: "first_name"}})

This will call the primary update action on the resource. This allows you to define an action on the embed, and add validations to it. For example, you might have something like this:

elixir

defmodule MyApp.Profile do
  use Ash.Resource,
    data_layer: :embedded # Use the atom `:embedded` as the data layer.

  attributes do
    attribute :first_name, :string, public?: true
    attribute :last_name, :string, public?: true
  end

  validations do
    validate present([:first_name, :last_name], at_least: 1)
  end
end

Calculations

Calculations can be added to embedded resources. When you use an embedded resource, you declare what calculations to load via a constraint. For example:

elixir

defmodule MyApp.Profile do
  use Ash.Resource,
    data_layer: :embedded # Use the atom `:embedded` as the data layer.

  attributes do
    attribute :first_name, :string, public?: true
    attribute :last_name, :string, public?: true
  end

  calculations do
    calculate :full_name, :string, concat([:first_name, :last_name], " ")
  end
end

defmodule MyApp.User do
  use Ash.Resource,
    ...

  attributes do
    attribute :profile, MyApp.Profile do
      public? true
      constraints [load: [:full_name]]
    end
  end
end

Determining what action(s) will be called:

Remember: default actions are already implemented for a resource, with no need to add them. They are called :create, :update, :destroy, and :read. You can use those without defining them. You only need to define them if you wish to override their configuration.

Single Embeds

If the current value is nil - a create with the provided values
If the current value is not nil - an update with the provided values
If the current value is not nil and the new value is nil - a destroy with the original value

Array Embeds

All values in the original array are destroyed, and all maps in the new array are used to create new records.

Adding a primary key

Adding a primary key to your embedded resources is especially useful when managing lists of data. Specifically, it allows you to consider changes to elements with matching primary key values as updates.

For example:

elixir

defmodule MyApp.Tag do
  use Ash.Resource,
    data_layer: :embedded

  attributes do
    uuid_primary_key :id
    attribute :name, :string, public?: true
    attribute :counter, :integer, public?: true
  end

  validations do
    validate {Increasing, field: :counter}, on: :update
  end
end

Now, you can accept input meant to update individual list items. The entire list must still be provided, but any items with a matching id will be considered an update instead of a destroy + create.

Determining what action(s) will be called with a primary key:

Single Embeds with primary keys

If you provide a struct, instead of a map, the value provided is used as the new relationship value directly.
If the current value is nil - a create with the provided values
If the current value is not nil and the primary keys match - an update with the provided values
If the current value is not nil and the primary keys don't match - a destroy of the original value and a create of the new value
If the current value is not nil and the new value is nil - a destroy with the original value

Array Embeds with primary keys

If you provide structs, instead of maps, the value provided is used as the new relationship value directly.
Any values in the original list with no primary key matching in the new list are destroyed.
Any values in the new list with no primary key matching in the original list are created.
Any values with a primary key match in the original list and the new list are updated

Identities

Identities can be added on an embedded resource, which will ensure that for any given list, they are unique on that identity. For example, if you had an embedded resource called Tag, you could add an identity on name to ensure that nothing has duplicate tag names.

Usage in Extensions

The AshJsonApi extension exposes these attributes as maps. However, the AshGraphql extension allows you to specify a type (but not queries/mutations) for an embedded resource. If you do, instead of being treated as a :json type it will get its own named input object type and field type.

Accessing the source changeset

When building changesets for embedded resources, the source changeset will be available in action changes under changeset.context.__source__. This allows you to customize the action based on the details of the parent changeset.