Settings View Source Print cheatsheet DSL: Ash.Resource.Dsl

attributes

A section for declaring attributes on the resource.

attributes do
  uuid_primary_key :id

  attribute :first_name, :string do
    allow_nil? false
  end

  attribute :last_name, :string do
    allow_nil? false
  end

  attribute :email, :string do
    allow_nil? false

    constraints [
      match: ~r/^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/
    ]
  end

  attribute :type, :atom do
    constraints [
      one_of: [:admin, :teacher, :student]
    ]
  end

  create_timestamp :inserted_at
  update_timestamp :updated_at
end

attributes.attribute

attribute name, type

Declares an attribute on the resource.

attribute :name, :string do
  allow_nil? false
end

attributes.create_timestamp

create_timestamp name

Declares a non-writable attribute with a create default of &DateTime.utc_now/0

Accepts all the same options as Ash.Resource.Dsl.attributes.attribute, except it sets the following different defaults:

writable? false private? true default &DateTime.utc_now/0 match_other_defaults? true type Ash.Type.UTCDatetimeUsec allow_nil? false

create_timestamp :inserted_at

attributes.update_timestamp

update_timestamp name

Declares a non-writable attribute with a create and update default of &DateTime.utc_now/0

Accepts all the same options as Ash.Resource.Dsl.attributes.attribute, except it sets the following different defaults:

writable? false private? true default &DateTime.utc_now/0 match_other_defaults? true update_default &DateTime.utc_now/0 type Ash.Type.UTCDatetimeUsec allow_nil? false

update_timestamp :updated_at

attributes.integer_primary_key

integer_primary_key name

Declares a generated, non writable, non-nil, primary key column of type integer.

Generated integer primary keys must be supported by the data layer.

Accepts all the same options as Ash.Resource.Dsl.attributes.attribute, except for allow_nil?, but it sets the following different defaults:

writable? false primary_key? true generated? true type :integer

integer_primary_key :id

attributes.uuid_primary_key

uuid_primary_key name

Declares a non writable, non-nil, primary key column of type uuid, which defaults to Ash.UUID.generate/0.

Accepts all the same options as Ash.Resource.Dsl.attributes.attribute, except for allow_nil?, but it sets the following different defaults:

writable? false default &Ash.UUID.generate/0 primary_key? true generated? true type :uuid

uuid_primary_key :id

relationships

A section for declaring relationships on the resource.

Relationships are a core component of resource oriented design. Many components of Ash will use these relationships. A simple use case is loading relationships (done via the Ash.Query.load/2).

See the relationships guide for more.

relationships do
  belongs_to :post, MyApp.Post do
    primary_key? true
  end

  belongs_to :category, MyApp.Category do
    primary_key? true
  end
end

relationships do
  belongs_to :author, MyApp.Author

  many_to_many :categories, MyApp.Category do
    through MyApp.PostCategory
    destination_attribute_on_join_resource :category_id
    source_attribute_on_join_resource :post_id
  end
end

relationships do
  has_many :posts, MyApp.Post do
    destination_attribute :author_id
  end

  has_many :composite_key_posts, MyApp.CompositeKeyPost do
    destination_attribute :author_id
  end
end

relationships.has_one

has_one name, destination

Declares a has_one relationship. In a relational database, the foreign key would be on the other table.

Generally speaking, a has_one also implies that the destination table is unique on that foreign key.

See the relationships guide for more.

# In a resource called `Word`
has_one :dictionary_entry, DictionaryEntry do
  source_attribute :text
  destination_attribute :word_text
end

relationships.has_many

has_many name, destination

Declares a has_many relationship. There can be any number of related entities.

See the relationships guide for more.

# In a resource called `Word`
has_many :definitions, DictionaryDefinition do
  source_attribute :text
  destination_attribute :word_text
end

relationships.many_to_many

many_to_many name, destination

Declares a many_to_many relationship. Many to many relationships require a join resource.

A join resource is a resource that consists of a relationship to the source and destination of the many to many.

See the relationships guide for more.

# In a resource called `Word`
many_to_many :books, Book do
  through BookWord
  source_attribute :text
  source_attribute_on_join_resource :word_text
  destination_attribute :id
  destination_attribute_on_join_resource :book_id
end

# And in `BookWord` (the join resource)
belongs_to :book, Book, primary_key?: true, allow_nil?: false
belongs_to :word, Word, primary_key?: true, allow_nil?: false

relationships.belongs_to

belongs_to name, destination

Declares a belongs_to relationship. In a relational database, the foreign key would be on the source table.

This creates a field on the resource with the corresponding name and type, unless define_attribute?: false is provided.

See the relationships guide for more.

# In a resource called `Word`
belongs_to :dictionary_entry, DictionaryEntry do
  source_attribute :text,
  destination_attribute :word_text
end

actions

A section for declaring resource actions.

All manipulation of data through the underlying data layer happens through actions. There are four types of action: create, read, update, and destroy. You may recognize these from the acronym CRUD. You can have multiple actions of the same type, as long as they have different names. This is the primary mechanism for customizing your resources to conform to your business logic. It is normal and expected to have multiple actions of each type in a large application.

actions do
  create :signup do
    argument :password, :string
    argument :password_confirmation, :string
    validate confirm(:password, :password_confirmation)
    change {MyApp.HashPassword, []} # A custom implemented Change
  end

  read :me do
    # An action that auto filters to only return the user for the current user
    filter [id: actor(:id)]
  end

  update :update do
    accept [:first_name, :last_name]
  end

  destroy do
    change set_attribute(:deleted_at, &DateTime.utc_now/0)
    # This tells it that even though this is a delete action, it
    # should be treated like an update because `deleted_at` is set.
    # This should be coupled with a `base_filter` on the resource
    # or with the read actions having a `filter` for `is_nil: :deleted_at`
    soft? true
  end
end

actions.action

action name, returns

Declares a generic action. A combination of arguments, a return type and a run function.

For calling this action, see the Ash.Api documentation.

action :top_user_emails, {:array, :string} do
  argument :limit, :integer, default: 10, allow_nil?: false
  run fn input, context ->
    with {:ok, top_users} <- top_users(input.limit) do
      {:ok, Enum.map(top_users, &(&1.email))}
    end
  end
end

actions.action.argument

argument name, type

Declares an argument on the action

argument :password_confirmation, :string

actions.create

create name

Declares a create action. For calling this action, see the Ash.Api documentation.

create :register do
  primary? true
end

actions.create.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

change relate_actor(:reporter)

change {MyCustomChange, :foo}

actions.create.validate

validate validation

Declares a validation to be applied to the changeset.

See Ash.Resource.Validation for more.

validate changing(:email)

actions.create.argument

argument name, type

Declares an argument on the action

argument :password_confirmation, :string

actions.create.metadata

metadata name, type

A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via Ash.Resource.Info.put_metadata/3.

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

actions.read

read name

Declares a read action. For calling this action, see the Ash.Api documentation.

read :read_all do
  primary? true
end

actions.read.argument

argument name, type

Declares an argument on the action

argument :password_confirmation, :string

actions.read.prepare

prepare preparation

Declares a preparation, which can be used to prepare a query for a read action.

prepare build(sort: [:foo, :bar])

actions.read.pagination

Adds pagination options to a resource

actions.read.metadata

metadata name, type

A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via Ash.Resource.Info.put_metadata/3.

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

actions.update

update name

Declares a update action. For calling this action, see the Ash.Api documentation.

update :flag_for_review, primary?: true

actions.update.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

change relate_actor(:reporter)

change {MyCustomChange, :foo}

actions.update.validate

validate validation

Declares a validation to be applied to the changeset.

See Ash.Resource.Validation for more.

validate changing(:email)

actions.update.metadata

metadata name, type

A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via Ash.Resource.Info.put_metadata/3.

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

actions.update.argument

argument name, type

Declares an argument on the action

argument :password_confirmation, :string

actions.destroy

destroy name

Declares a destroy action. For calling this action, see the Ash.Api documentation.

destroy :soft_delete do
  primary? true
end

actions.destroy.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

change relate_actor(:reporter)

change {MyCustomChange, :foo}

actions.destroy.validate

validate validation

Declares a validation to be applied to the changeset.

See Ash.Resource.Validation for more.

validate changing(:email)

actions.destroy.metadata

metadata name, type

A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via Ash.Resource.Info.put_metadata/3.

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

actions.destroy.argument

argument name, type

Declares an argument on the action

argument :password_confirmation, :string

code_interface

Functions that will be defined on the Api module to interact with this resource. See the code interface guide for more.

code_interface do
  define_for MyApp.Api
  define :create_user, action: :create
  define :get_user_by_id, action: :get_by_id, args: [:id], get?: true
end

code_interface.define

define name

Defines a function with the corresponding name and arguments. See the code interface guide for more.

define :get_user_by_id, action: :get_by_id, args: [:id], get?: true

code_interface.define_calculation

define_calculation name

Defines a function with the corresponding name and arguments, that evaluates a calculation. Use :_record to take an instance of a record. See the code interface guide for more.

define_calculation :referral_link, args: [:id]

define_calculation :referral_link, args: [{:arg, :id}, {:ref, :id}]

resource

General resource configuration

resource do
  description "A description of this resource"
  base_filter [is_nil: :deleted_at]
end

identities

Unique identifiers for the resource

identities do
  identity :full_name, [:first_name, :last_name]
  identity :email, [:email]
end

identities.identity

identity name, keys

Represents a unique constraint on the resource.

See the identities guide for more.

identity :name, [:name]

identity :full_name, [:first_name, :last_name]

changes

Declare changes that occur on create/update/destroy actions against the resource

See Ash.Resource.Change for more.

changes do
  change {Mod, [foo: :bar]}
  change set_context(%{some: :context})
end

changes.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

change relate_actor(:reporter)

change {MyCustomChange, :foo}

preparations

Declare preparations that occur on all read actions for a given resource

preparations do
  prepare {Mod, [foo: :bar]}
  prepare set_context(%{some: :context})
end

preparations.prepare

prepare preparation

Declares a preparation, which can be used to prepare a query for a read action.

prepare build(sort: [:foo, :bar])

validations

Declare validations prior to performing actions against the resource

validations do
  validate {Mod, [foo: :bar]}
  validate at_least_one_of_present([:first_name, :last_name])
end

validations.validate

validate validation

Declares a validation for creates and updates.

See Ash.Resource.Change for more.

validate {Mod, [foo: :bar]}

validate at_least_one_of_present([:first_name, :last_name])

aggregates

Declare named aggregates on the resource.

These are aggregates that can be loaded only by name using Ash.Query.load/2. They are also available as top level fields on the resource.

See the aggregates guide for more.

aggregates do
  count :assigned_ticket_count, :reported_tickets do
    filter [active: true]
  end
end

aggregates.count

count name, relationship_path

Declares a named count aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the count)

See the aggregates guide for more.

count :assigned_ticket_count, :assigned_tickets do
  filter [active: true]
end

aggregates.exists

exists name, relationship_path

Declares a named exists aggregate on the resource

Supports filter, but not sort (because that wouldn't affect if something exists)

See the aggregates guide for more.

exists :has_ticket, :assigned_tickets

aggregates.first

first name, relationship_path, field

Declares a named first aggregate on the resource

First aggregates return the first value of the related record that matches. Supports both filter and sort.

See the aggregates guide for more.

first :first_assigned_ticket_subject, :assigned_tickets, :subject do
  filter [active: true]
  sort [:subject]
end

aggregates.sum

sum name, relationship_path, field

Declares a named sum aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the sum)

See the aggregates guide for more.

sum :assigned_ticket_price_sum, :assigned_tickets, :price do
  filter [active: true]
end

aggregates.list

list name, relationship_path, field

Declares a named list aggregate on the resource.

A list aggregate selects the list of all values for the given field and relationship combination.

See the aggregates guide for more.

list :assigned_ticket_prices, :assigned_tickets, :price do
  filter [active: true]
end

aggregates.max

max name, relationship_path, field

Declares a named max aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the max)

See the aggregates guide for more.

max :first_assigned_ticket_subject, :assigned_tickets, :severity do
  filter [active: true]
end

aggregates.min

min name, relationship_path, field

Declares a named min aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the min)

See the aggregates guide for more.

min :first_assigned_ticket_subject, :assigned_tickets, :severity do
  filter [active: true]
end

aggregates.avg

avg name, relationship_path, field

Declares a named avg aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the avg)

See the aggregates guide for more.

avg :assigned_ticket_price_sum, :assigned_tickets, :price do
  filter [active: true]
end

aggregates.custom

custom name, relationship_path, type

Declares a named custom aggregate on the resource

Supports filter and sort.

Custom aggregates provide an implementation which must implement data layer specific callbacks.

See the relevant data layer documentation and the aggregates guide for more.

custom :author_names, :authors, :string do
  implementation {StringAgg, delimiter: ","}
end

calculations

Declare named calculations on the resource.

These are calculations that can be loaded only by name using Ash.Query.load/2. They are also available as top level fields on the resource.

See the calculations guide for more.

calculations do
  calculate :full_name, :string, MyApp.MyResource.FullName
end

calculations.calculate

calculate name, type, calculation \ nil

Declares a named calculation on the resource.

Takes a module that must adopt the Ash.Calculation behaviour. See that module for more information.

To ensure that the necessary fields are selected:

1.) Specifying the select option on a calculation in the resource. 2.) Define a select/2 callback in the calculation module 3.) Set always_select? on the attribute in question

See the calculations guide for more.