Skip to content

Latest commit

 

History

History
3475 lines (2044 loc) · 143 KB

DSL-Ash.Resource.md

File metadata and controls

3475 lines (2044 loc) · 143 KB
Raw

DSL: Ash.Resource.Dsl

attributes

A section for declaring attributes on the resource.

Nested DSLs

Examples

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.

Examples

attribute :name, :string do
  allow_nil? false
end

Arguments

Name Type Default Docs
name{: #attributes-attribute-name .spark-required} atom The name of the attribute.
type{: #attributes-attribute-type .spark-required} module The type of the attribute. See Ash.Type for more.

Options

Name Type Default Docs
constraints{: #attributes-attribute-constraints } keyword Constraints to provide to the type when casting the value. For more, see Ash.Type.
description{: #attributes-attribute-description } String.t An optional description for the attribute.
sensitive?{: #attributes-attribute-sensitive? } boolean false Whether or not the attribute value contains sensitive information, like PII(Personally Identifiable Information). See the Sensitive Data guide for more.
source{: #attributes-attribute-source } atom If the field should be mapped to a different name in the data layer. Support varies by data layer.
select_by_default?{: #attributes-attribute-select_by_default? } boolean true Whether or not the attribute is selected by default.
always_select?{: #attributes-attribute-always_select? } boolean false Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements.
primary_key?{: #attributes-attribute-primary_key? } boolean false Whether the attribute is the primary key. Composite primary key is also possible by using primary_key? true in more than one attribute. If primary_key? is true, allow_nil? must be false.
allow_nil?{: #attributes-attribute-allow_nil? } boolean true Whether or not the attribute can be set to nil. If nil value is given error is raised.
generated?{: #attributes-attribute-generated? } boolean false Whether or not the value may be generated by the data layer.
writable?{: #attributes-attribute-writable? } boolean true Whether or not the value can be written to. Non-writable attributes can still be written with Ash.Changeset.force_change_attribute/3.
public?{: #attributes-attribute-public? } boolean false Whether or not the attribute should be shown over public interfaces. See the sensitive data guide for more.
default{: #attributes-attribute-default } (-> any) | mfa | any A value to be set on all creates, unless a value is being provided already. Note: The default value is casted according to the type's Ash.Type.* module, before it is saved. For :string, for example, if constraints: [allow_empty?: _] is false, the value "" will be cast to nil. See the :constraints option, the :allow_nil? option, and the relevant Ash.Type.* documentation.
update_default{: #attributes-attribute-update_default } (-> any) | mfa | any A value to be set on all updates, unless a value is being provided already.
filterable?{: #attributes-attribute-filterable? } boolean | :simple_equality true Whether or not the attribute can be referenced in filters.
sortable?{: #attributes-attribute-sortable? } boolean true Whether or not the attribute can be referenced in sorts.
match_other_defaults?{: #attributes-attribute-match_other_defaults? } boolean false Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless default is a zero argument function.

Introspection

Target: Ash.Resource.Attribute

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 d:Ash.Resource.Dsl.attributes.attribute, except it sets the following different defaults:

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

Examples

create_timestamp :inserted_at

Arguments

Name Type Default Docs
name{: #attributes-create_timestamp-name .spark-required} atom The name of the attribute.

Introspection

Target: Ash.Resource.Attribute

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 d:Ash.Resource.Dsl.attributes.attribute, except it sets the following different defaults:

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

Examples

update_timestamp :updated_at

Arguments

Name Type Default Docs
name{: #attributes-update_timestamp-name .spark-required} atom The name of the attribute.

Introspection

Target: Ash.Resource.Attribute

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 d:Ash.Resource.Dsl.attributes.attribute, except for allow_nil?, but it sets the following different defaults:

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

Examples

integer_primary_key :id

Arguments

Name Type Default Docs
name{: #attributes-integer_primary_key-name .spark-required} atom The name of the attribute.

Introspection

Target: Ash.Resource.Attribute

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 d:Ash.Resource.Dsl.attributes.attribute, except for allow_nil?, but it sets the following different defaults:

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

Examples

uuid_primary_key :id

Arguments

Name Type Default Docs
name{: #attributes-uuid_primary_key-name .spark-required} atom The name of the attribute.

Introspection

Target: Ash.Resource.Attribute

attributes.uuid_v7_primary_key

uuid_v7_primary_key name

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

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

writable? false
public? true
default &Ash.UUIDv7.generate/0
primary_key? true
type :uuid_v7

Examples

uuid_v7_primary_key :id

Arguments

Name Type Default Docs
name{: #attributes-uuid_v7_primary_key-name .spark-required} atom The name of the attribute.

Introspection

Target: Ash.Resource.Attribute

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.

Nested DSLs

Examples

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #relationships-has_one-name } atom The name of the relationship
destination{: #relationships-has_one-destination } module The destination resource

Options

Name Type Default Docs
manual{: #relationships-has_one-manual } (any, any -> any) | module A module that implements Ash.Resource.ManualRelationship. Also accepts a 2 argument function that takes the source records and the context.
no_attributes?{: #relationships-has_one-no_attributes? } boolean All existing entities are considered related, i.e this relationship is not based on any fields, and source_attribute and destination_attribute are ignored. See the See the relationships guide for more.
allow_nil?{: #relationships-has_one-allow_nil? } boolean true Marks the relationship as required. Has no effect on validations, but can inform extensions that there will always be a related entity.
from_many?{: #relationships-has_one-from_many? } boolean false Signal that this relationship is actually a has_many where the first record is given via the sort. This will allow data layers to properly deduplicate when necessary.
description{: #relationships-has_one-description } String.t An optional description for the relationship
destination_attribute{: #relationships-has_one-destination_attribute } atom The attribute on the related resource that should match the source_attribute configured on this resource.
validate_destination_attribute?{: #relationships-has_one-validate_destination_attribute? } boolean true Whether or not to validate that the destination field exists on the destination resource
source_attribute{: #relationships-has_one-source_attribute } atom :id The field on this resource that should match the destination_attribute on the related resource.
relationship_context{: #relationships-has_one-relationship_context } any Context to be set on any queries or changesets generated for managing or querying this relationship.
public?{: #relationships-has_one-public? } boolean false Whether or not the relationship will appear in public interfaces
not_found_message{: #relationships-has_one-not_found_message } String.t A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships.
writable?{: #relationships-has_one-writable? } boolean true Whether or not the relationship may be managed.
read_action{: #relationships-has_one-read_action } atom The read action on the destination resource to use when loading data and filtering.
domain{: #relationships-has_one-domain } atom The domain module to use when working with the related entity.
filterable?{: #relationships-has_one-filterable? } boolean true If set to false, the relationship will not be usable in filters.
sortable?{: #relationships-has_one-sortable? } boolean true If set to false, the relationship will not be usable in filters.
sort{: #relationships-has_one-sort } any A sort statement to be applied when loading the relationship.
could_be_related_at_creation?{: #relationships-has_one-could_be_related_at_creation? } boolean false Whether or not related values may exist for this relationship at creation.
violation_message{: #relationships-has_one-violation_message } String.t A message to show if there is a conflict with this relationship in the database on destroy.

relationships.has_one.filter

filter filter

Applies a filter. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Examples

filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

Arguments

Name Type Default Docs
filter{: #relationships-has_one-filter-filter .spark-required} any The filter to apply. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Introspection

Target: Ash.Resource.Dsl.Filter

Introspection

Target: Ash.Resource.Relationships.HasOne

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #relationships-has_many-name } atom The name of the relationship
destination{: #relationships-has_many-destination } module The destination resource

Options

Name Type Default Docs
manual{: #relationships-has_many-manual } (any, any -> any) | module A module that implements Ash.Resource.ManualRelationship. Also accepts a 2 argument function that takes the source records and the context.
no_attributes?{: #relationships-has_many-no_attributes? } boolean All existing entities are considered related, i.e this relationship is not based on any fields, and source_attribute and destination_attribute are ignored. See the See the relationships guide for more.
description{: #relationships-has_many-description } String.t An optional description for the relationship
destination_attribute{: #relationships-has_many-destination_attribute } atom The attribute on the related resource that should match the source_attribute configured on this resource.
validate_destination_attribute?{: #relationships-has_many-validate_destination_attribute? } boolean true Whether or not to validate that the destination field exists on the destination resource
source_attribute{: #relationships-has_many-source_attribute } atom :id The field on this resource that should match the destination_attribute on the related resource.
relationship_context{: #relationships-has_many-relationship_context } any Context to be set on any queries or changesets generated for managing or querying this relationship.
public?{: #relationships-has_many-public? } boolean false Whether or not the relationship will appear in public interfaces
not_found_message{: #relationships-has_many-not_found_message } String.t A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships.
writable?{: #relationships-has_many-writable? } boolean true Whether or not the relationship may be managed.
read_action{: #relationships-has_many-read_action } atom The read action on the destination resource to use when loading data and filtering.
domain{: #relationships-has_many-domain } atom The domain module to use when working with the related entity.
filterable?{: #relationships-has_many-filterable? } boolean true If set to false, the relationship will not be usable in filters.
sortable?{: #relationships-has_many-sortable? } boolean true If set to false, the relationship will not be usable in filters.
sort{: #relationships-has_many-sort } any A sort statement to be applied when loading the relationship.
could_be_related_at_creation?{: #relationships-has_many-could_be_related_at_creation? } boolean false Whether or not related values may exist for this relationship at creation.
violation_message{: #relationships-has_many-violation_message } String.t A message to show if there is a conflict with this relationship in the database on destroy.

relationships.has_many.filter

filter filter

Applies a filter. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Examples

filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

Arguments

Name Type Default Docs
filter{: #relationships-has_many-filter-filter .spark-required} any The filter to apply. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Introspection

Target: Ash.Resource.Dsl.Filter

Introspection

Target: Ash.Resource.Relationships.HasMany

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.

Nested DSLs

Examples

# 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

Arguments

Name Type Default Docs
name{: #relationships-many_to_many-name } atom The name of the relationship
destination{: #relationships-many_to_many-destination } module The destination resource

Options

Name Type Default Docs
source_attribute_on_join_resource{: #relationships-many_to_many-source_attribute_on_join_resource } atom The attribute on the join resource that should line up with source_attribute on this resource. Defaults to <snake_cased_last_part_of_source_module_name>_id.
destination_attribute_on_join_resource{: #relationships-many_to_many-destination_attribute_on_join_resource } atom The attribute on the join resource that should line up with destination_attribute on the related resource. Defaults to <snake_cased_last_part_of_destination_module_name>_id.
through{: #relationships-many_to_many-through } module The resource to use as the join resource.
join_relationship{: #relationships-many_to_many-join_relationship } atom The has_many relationship to the join resource. Defaults to <relationship_name>_join_assoc.
description{: #relationships-many_to_many-description } String.t An optional description for the relationship
destination_attribute{: #relationships-many_to_many-destination_attribute } atom :id The attribute on the related resource that should match the source_attribute configured on this resource.
validate_destination_attribute?{: #relationships-many_to_many-validate_destination_attribute? } boolean true Whether or not to validate that the destination field exists on the destination resource
source_attribute{: #relationships-many_to_many-source_attribute } atom :id The field on this resource that should match the destination_attribute on the related resource.
relationship_context{: #relationships-many_to_many-relationship_context } any Context to be set on any queries or changesets generated for managing or querying this relationship.
public?{: #relationships-many_to_many-public? } boolean false Whether or not the relationship will appear in public interfaces
not_found_message{: #relationships-many_to_many-not_found_message } String.t A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships.
writable?{: #relationships-many_to_many-writable? } boolean true Whether or not the relationship may be managed.
read_action{: #relationships-many_to_many-read_action } atom The read action on the destination resource to use when loading data and filtering.
domain{: #relationships-many_to_many-domain } atom The domain module to use when working with the related entity.
filterable?{: #relationships-many_to_many-filterable? } boolean true If set to false, the relationship will not be usable in filters.
sortable?{: #relationships-many_to_many-sortable? } boolean true If set to false, the relationship will not be usable in filters.
sort{: #relationships-many_to_many-sort } any A sort statement to be applied when loading the relationship.
could_be_related_at_creation?{: #relationships-many_to_many-could_be_related_at_creation? } boolean false Whether or not related values may exist for this relationship at creation.
violation_message{: #relationships-many_to_many-violation_message } String.t A message to show if there is a conflict with this relationship in the database on destroy.

relationships.many_to_many.filter

filter filter

Applies a filter. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Examples

filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

Arguments

Name Type Default Docs
filter{: #relationships-many_to_many-filter-filter .spark-required} any The filter to apply. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Introspection

Target: Ash.Resource.Dsl.Filter

Introspection

Target: Ash.Resource.Relationships.ManyToMany

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #relationships-belongs_to-name } atom The name of the relationship
destination{: #relationships-belongs_to-destination } module The destination resource

Options

Name Type Default Docs
primary_key?{: #relationships-belongs_to-primary_key? } boolean false Whether the generated attribute is, or is part of, the primary key of a resource.
allow_nil?{: #relationships-belongs_to-allow_nil? } boolean true Whether this relationship must always be present, e.g: must be included on creation, and never removed (it may be modified). The generated attribute will not allow nil values.
attribute_writable?{: #relationships-belongs_to-attribute_writable? } boolean Whether the generated attribute will be marked as writable. If not set, it will default to the relationship's writable? setting.
attribute_public?{: #relationships-belongs_to-attribute_public? } boolean Whether or not the generated attribute will be public. If not set, it will default to the relationship's public? setting.
define_attribute?{: #relationships-belongs_to-define_attribute? } boolean true If set to false an attribute is not created on the resource for this relationship, and one must be manually added in attributes, invalidating many other options.
attribute_type{: #relationships-belongs_to-attribute_type } any :uuid The type of the generated created attribute. See Ash.Type for more.
description{: #relationships-belongs_to-description } String.t An optional description for the relationship
destination_attribute{: #relationships-belongs_to-destination_attribute } atom :id The attribute on the related resource that should match the source_attribute configured on this resource.
validate_destination_attribute?{: #relationships-belongs_to-validate_destination_attribute? } boolean true Whether or not to validate that the destination field exists on the destination resource
source_attribute{: #relationships-belongs_to-source_attribute } atom The field on this resource that should match the destination_attribute on the related resource. - Defaults to _id
relationship_context{: #relationships-belongs_to-relationship_context } any Context to be set on any queries or changesets generated for managing or querying this relationship.
public?{: #relationships-belongs_to-public? } boolean false Whether or not the relationship will appear in public interfaces
not_found_message{: #relationships-belongs_to-not_found_message } String.t A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships.
writable?{: #relationships-belongs_to-writable? } boolean true Whether or not the relationship may be managed.
read_action{: #relationships-belongs_to-read_action } atom The read action on the destination resource to use when loading data and filtering.
domain{: #relationships-belongs_to-domain } atom The domain module to use when working with the related entity.
filterable?{: #relationships-belongs_to-filterable? } boolean true If set to false, the relationship will not be usable in filters.
sortable?{: #relationships-belongs_to-sortable? } boolean true If set to false, the relationship will not be usable in filters.
sort{: #relationships-belongs_to-sort } any A sort statement to be applied when loading the relationship.
violation_message{: #relationships-belongs_to-violation_message } String.t A message to show if there is a conflict with this relationship in the database on destroy.

relationships.belongs_to.filter

filter filter

Applies a filter. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Examples

filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

Arguments

Name Type Default Docs
filter{: #relationships-belongs_to-filter-filter .spark-required} any The filter to apply. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Introspection

Target: Ash.Resource.Dsl.Filter

Introspection

Target: Ash.Resource.Relationships.BelongsTo

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.

Nested DSLs

  • action
    • argument
  • create
    • change
    • validate
    • argument
    • metadata
  • read
    • argument
    • prepare
    • pagination
    • metadata
    • filter
  • update
    • change
    • validate
    • metadata
    • argument
  • destroy
    • change
    • validate
    • metadata
    • argument

Examples

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

Options

Name Type Default Docs
defaults{: #actions-defaults } list(:create | :read | :update | :destroy | {atom, atom | list(atom)}) Creates a simple action of each specified type, with the same name as the type. These will be primary? unless one already exists for that type. Embedded resources, however, have a default of all resource types.
default_accept{: #actions-default_accept } list(atom) | :* A default value for the accept option for each action. Use :* to accept all public attributes.

actions.action

action name, returns \\ nil

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

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

Nested DSLs

Examples

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.arguments.limit) do
      {:ok, Enum.map(top_users, &(&1.email))}
    end
  end
end

Arguments

Name Type Default Docs
name{: #actions-action-name .spark-required} atom The name of the action
returns{: #actions-action-returns } module The return type of the action. See Ash.Type for more.

Options

Name Type Default Docs
constraints{: #actions-action-constraints } keyword Constraints for the return type. See Ash.Type for more.
allow_nil?{: #actions-action-allow_nil? } boolean false Whether or not the action can return nil. Unlike attributes & arguments, this defaults to false.
run{: #actions-action-run } (any, any -> any) | module | module
primary?{: #actions-action-primary? } boolean false Whether or not this action should be used when no action is specified by the caller.
description{: #actions-action-description } String.t An optional description for the action
transaction?{: #actions-action-transaction? } boolean Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to true.
touches_resources{: #actions-action-touches_resources } list(atom) A list of resources that the action may touch, used when building transactions.
skip_unknown_inputs{: #actions-action-skip_unknown_inputs } atom | String.t | list(atom | String.t) [] A list of unknown fields to skip, or :* to skip all unknown fields.

actions.action.argument

argument name, type

Declares an argument on the action

Examples

argument :password_confirmation, :string

Arguments

Name Type Default Docs
name{: #actions-action-argument-name .spark-required} atom The name of the argument
type{: #actions-action-argument-type .spark-required} module The type of the argument. See Ash.Type for more.

Options

Name Type Default Docs
description{: #actions-action-argument-description } String.t An optional description for the argument.
constraints{: #actions-action-argument-constraints } keyword [] Constraints to provide to the type when casting the value. For more information, see Ash.Type.
allow_nil?{: #actions-action-argument-allow_nil? } boolean true Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised.
public?{: #actions-action-argument-public? } boolean true Whether or not the argument should appear in public interfaces
sensitive?{: #actions-action-argument-sensitive? } boolean false Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the security guide for more.
default{: #actions-action-argument-default } any The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Argument

Introspection

Target: Ash.Resource.Actions.Action

actions.create

create name

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

Nested DSLs

Examples

create :register do
  primary? true
end

Arguments

Name Type Default Docs
name{: #actions-create-name .spark-required} atom The name of the action

Options

Name Type Default Docs
manual{: #actions-create-manual } (any, any -> any) | module Override the creation behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the manual actions guide for more.
upsert?{: #actions-create-upsert? } boolean false Forces all uses of this action to be treated as an upsert.
upsert_identity{: #actions-create-upsert_identity } atom The identity to use for the upsert. Cannot be overriden by the caller. Ignored if upsert? is not set to true.
upsert_fields{: #actions-create-upsert_fields } :replace_all | {:replace, atom | list(atom)} | {:replace_all_except, atom | list(atom)} | atom | list(atom) The fields to overwrite in the case of an upsert. If not provided, all fields except for fields set by defaults will be overwritten.
upsert_condition{: #actions-create-upsert_condition } any An expression to check if the record should be updated when there's a conflict.
return_skipped_upsert?{: #actions-create-return_skipped_upsert? } boolean Returns the record that would have been upserted against but was skipped due to a filter or no fields being changed. How this works depends on the data layer. Keep in mind that read policies are not applied to the read of the record in question.
primary?{: #actions-create-primary? } boolean false Whether or not this action should be used when no action is specified by the caller.
description{: #actions-create-description } String.t An optional description for the action
transaction?{: #actions-create-transaction? } boolean Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to true.
touches_resources{: #actions-create-touches_resources } list(atom) A list of resources that the action may touch, used when building transactions.
skip_unknown_inputs{: #actions-create-skip_unknown_inputs } atom | String.t | list(atom | String.t) [] A list of unknown fields to skip, or :* to skip all unknown fields.
accept{: #actions-create-accept } atom | list(atom) | :* The list of attributes to accept. Use :* to accept all public attributes.
action_select{: #actions-create-action_select } list(atom) A list of attributes that the action requires to do its work. Defaults to all attributes except those with select_by_default? false. On actions with no changes/notifiers, it defaults to the externally selected attributes. Keep in mind that action_select is applied before notifiers.
require_attributes{: #actions-create-require_attributes } list(atom) A list of attributes that would normally allow_nil?, to require for this action. No need to include attributes that already do not allow nil?
allow_nil_input{: #actions-create-allow_nil_input } list(atom) A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the data layer step.
delay_global_validations?{: #actions-create-delay_global_validations? } boolean false If true, global validations will be done in a before_action hook, regardless of their configuration on the resource.
skip_global_validations?{: #actions-create-skip_global_validations? } boolean false If true, global validations will be skipped. Useful for manual actions.
error_handler{: #actions-create-error_handler } mfa Sets the error handler on the changeset. See Ash.Changeset.handle_errors/2 for more
notifiers{: #actions-create-notifiers } list(module) Notifiers that will be called specifically for this action.
manual?{: #actions-create-manual? } boolean Instructs Ash to skip the actual update/create/destroy step at the data layer. See the manual actions guide for more.

actions.create.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

Examples

change relate_actor(:reporter)
change {MyCustomChange, :foo}

Arguments

Name Type Default Docs
change{: #actions-create-change-change .spark-required} (any, any -> any) | module The module and options for a change. Also accepts a function that takes the changeset and the context. See Ash.Resource.Change.Builtins for builtin changes.

Options

Name Type Default Docs
only_when_valid?{: #actions-create-change-only_when_valid? } boolean false If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description{: #actions-create-change-description } String.t An optional description for the change
where{: #actions-create-change-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this change to apply. These validations failing will result in this change being ignored.
always_atomic?{: #actions-create-change-always_atomic? } boolean false By default, changes are only run atomically if all changes will be run atomically or if there is no change/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Change

actions.create.validate

validate validation

Declares a validation to be applied to the changeset.

See Ash.Resource.Validation.Builtins or Ash.Resource.Validation for more.

Examples

validate changing(:email)

Arguments

Name Type Default Docs
validation{: #actions-create-validate-validation .spark-required} (any, any -> any) | module The module (or module and opts) that implements the Ash.Resource.Validation behaviour. Also accepts a function that receives the changeset and its context.

Options

Name Type Default Docs
where{: #actions-create-validate-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored.
only_when_valid?{: #actions-create-validate-only_when_valid? } boolean false If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message{: #actions-create-validate-message } String.t If provided, overrides any message set by the validation error
description{: #actions-create-validate-description } String.t An optional description for the validation
before_action?{: #actions-create-validate-before_action? } boolean false If set to true, the validation will be run in a before_action hook
always_atomic?{: #actions-create-validate-always_atomic? } boolean false By default, validations are only run atomically if all changes will be run atomically or if there is no validate/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Validation

actions.create.argument

argument name, type

Declares an argument on the action

Examples

argument :password_confirmation, :string

Arguments

Name Type Default Docs
name{: #actions-create-argument-name .spark-required} atom The name of the argument
type{: #actions-create-argument-type .spark-required} module The type of the argument. See Ash.Type for more.

Options

Name Type Default Docs
description{: #actions-create-argument-description } String.t An optional description for the argument.
constraints{: #actions-create-argument-constraints } keyword [] Constraints to provide to the type when casting the value. For more information, see Ash.Type.
allow_nil?{: #actions-create-argument-allow_nil? } boolean true Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised.
public?{: #actions-create-argument-public? } boolean true Whether or not the argument should appear in public interfaces
sensitive?{: #actions-create-argument-sensitive? } boolean false Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the security guide for more.
default{: #actions-create-argument-default } any The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Argument

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 after_action hook via Ash.Resource.put_metadata/3.

Examples

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

Arguments

Name Type Default Docs
name{: #actions-create-metadata-name .spark-required} atom The name of the metadata
type{: #actions-create-metadata-type .spark-required} any The type of the metadata. See Ash.Type for more.

Options

Name Type Default Docs
constraints{: #actions-create-metadata-constraints } keyword [] Type constraints on the metadata
description{: #actions-create-metadata-description } String.t An optional description for the metadata.
allow_nil?{: #actions-create-metadata-allow_nil? } boolean true Whether or not the metadata may return nil
default{: #actions-create-metadata-default } any The default value for the metadata to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Metadata

Introspection

Target: Ash.Resource.Actions.Create

actions.read

read name

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

Nested DSLs

Examples

read :read_all do
  primary? true
end

Arguments

Name Type Default Docs
name{: #actions-read-name .spark-required} atom The name of the action

Options

Name Type Default Docs
manual{: #actions-read-manual } (any, any, any -> any) | module Delegates running of the query to the provided module. Accepts a module or module and opts, or a function that takes the ash query, the data layer query, and context. See the manual actions guide for more.
get?{: #actions-read-get? } boolean false Expresses that this action innately only returns a single result. Used by extensions to validate and/or modify behavior. Causes code interfaces to return a single value instead of a list. See the code interface guide for more.
modify_query{: #actions-read-modify_query } mfa | (any, any -> any) Allows direct manipulation of the data layer query via an MFA. The ash query and the data layer query will be provided as additional arguments. The result must be {:ok, new_data_layer_query} | {:error, error}.
get_by{: #actions-read-get_by } atom | list(atom) A helper to automatically generate a "get by X" action. Sets get? to true, add args for each of the specified fields, and adds a filter for each of the arguments.
timeout{: #actions-read-timeout } pos_integer The maximum amount of time, in milliseconds, that the action is allowed to run for. Ignored if the data layer doesn't support transactions and async is disabled.
multitenancy{: #actions-read-multitenancy } :enforce | :allow_global | :bypass :enforce This setting defines how this action handles multitenancy. :enforce requires a tenant to be set (the default behavior), :allow_global allows using this action both with and without a tenant, :bypass completely ignores the tenant even if it's set. This is useful to change the behaviour of selected read action without the need of marking the whole resource with global? true.
primary?{: #actions-read-primary? } boolean false Whether or not this action should be used when no action is specified by the caller.
description{: #actions-read-description } String.t An optional description for the action
transaction?{: #actions-read-transaction? } boolean Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to true.
touches_resources{: #actions-read-touches_resources } list(atom) A list of resources that the action may touch, used when building transactions.
skip_unknown_inputs{: #actions-read-skip_unknown_inputs } atom | String.t | list(atom | String.t) [] A list of unknown fields to skip, or :* to skip all unknown fields.

actions.read.argument

argument name, type

Declares an argument on the action

Examples

argument :password_confirmation, :string

Arguments

Name Type Default Docs
name{: #actions-read-argument-name .spark-required} atom The name of the argument
type{: #actions-read-argument-type .spark-required} module The type of the argument. See Ash.Type for more.

Options

Name Type Default Docs
description{: #actions-read-argument-description } String.t An optional description for the argument.
constraints{: #actions-read-argument-constraints } keyword [] Constraints to provide to the type when casting the value. For more information, see Ash.Type.
allow_nil?{: #actions-read-argument-allow_nil? } boolean true Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised.
public?{: #actions-read-argument-public? } boolean true Whether or not the argument should appear in public interfaces
sensitive?{: #actions-read-argument-sensitive? } boolean false Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the security guide for more.
default{: #actions-read-argument-default } any The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Argument

actions.read.prepare

prepare preparation

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

Examples

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

Arguments

Name Type Default Docs
preparation{: #actions-read-prepare-preparation .spark-required} (any, any -> any) | module The module and options for a preparation. Also accepts functions take the query and the context.

Introspection

Target: Ash.Resource.Preparation

actions.read.pagination

Adds pagination options to a resource

Options

Name Type Default Docs
keyset?{: #actions-read-pagination-keyset? } boolean false Whether or not keyset based pagination is supported
offset?{: #actions-read-pagination-offset? } boolean false Whether or not offset based pagination is supported
default_limit{: #actions-read-pagination-default_limit } pos_integer The default page size to apply, if one is not supplied
countable{: #actions-read-pagination-countable } true | false | :by_default true Whether not a returned page will have a full count of all records. Use :by_default to do it automatically.
max_page_size{: #actions-read-pagination-max_page_size } pos_integer 250 The maximum amount of records that can be requested in a single page
required?{: #actions-read-pagination-required? } boolean true Whether or not pagination can be disabled (by passing page: false to Ash.Api.read!/2, or by having required?: false, default_limit: nil set). Only relevant if some pagination configuration is supplied.

Introspection

Target: Ash.Resource.Actions.Read.Pagination

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 after_action hook via Ash.Resource.put_metadata/3.

Examples

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

Arguments

Name Type Default Docs
name{: #actions-read-metadata-name .spark-required} atom The name of the metadata
type{: #actions-read-metadata-type .spark-required} any The type of the metadata. See Ash.Type for more.

Options

Name Type Default Docs
constraints{: #actions-read-metadata-constraints } keyword [] Type constraints on the metadata
description{: #actions-read-metadata-description } String.t An optional description for the metadata.
allow_nil?{: #actions-read-metadata-allow_nil? } boolean true Whether or not the metadata may return nil
default{: #actions-read-metadata-default } any The default value for the metadata to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Metadata

actions.read.filter

filter filter

Applies a filter. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Examples

filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

Arguments

Name Type Default Docs
filter{: #actions-read-filter-filter .spark-required} any The filter to apply. Can use ^arg/1, ^context/1 and ^actor/1 teplates. Multiple filters are combined with and.

Introspection

Target: Ash.Resource.Dsl.Filter

Introspection

Target: Ash.Resource.Actions.Read

actions.update

update name

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

Nested DSLs

Examples

update :flag_for_review, primary?: true

Arguments

Name Type Default Docs
name{: #actions-update-name .spark-required} atom The name of the action

Options

Name Type Default Docs
manual{: #actions-update-manual } (any, any -> any) | module Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the manual actions guide for more.
require_atomic?{: #actions-update-require_atomic? } boolean true Require that the update be atomic. This means that all changes and validations implement the atomic callback. See the guide on atomic updates for more.
atomic_upgrade?{: #actions-update-atomic_upgrade? } boolean false If set to true, atomic upgrades will be performed. Ignored if required_atomic? is true. See the update actions guide for more.
atomic_upgrade_with{: #actions-update-atomic_upgrade_with } atom | nil Configure the read action used when performing atomic upgrades. Defaults to the primary read action.
primary?{: #actions-update-primary? } boolean false Whether or not this action should be used when no action is specified by the caller.
description{: #actions-update-description } String.t An optional description for the action
transaction?{: #actions-update-transaction? } boolean Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to true.
touches_resources{: #actions-update-touches_resources } list(atom) A list of resources that the action may touch, used when building transactions.
skip_unknown_inputs{: #actions-update-skip_unknown_inputs } atom | String.t | list(atom | String.t) [] A list of unknown fields to skip, or :* to skip all unknown fields.
accept{: #actions-update-accept } atom | list(atom) | :* The list of attributes to accept. Use :* to accept all public attributes.
action_select{: #actions-update-action_select } list(atom) A list of attributes that the action requires to do its work. Defaults to all attributes except those with select_by_default? false. On actions with no changes/notifiers, it defaults to the externally selected attributes. Keep in mind that action_select is applied before notifiers.
require_attributes{: #actions-update-require_attributes } list(atom) A list of attributes that would normally allow_nil?, to require for this action. No need to include attributes that already do not allow nil?
allow_nil_input{: #actions-update-allow_nil_input } list(atom) A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the data layer step.
delay_global_validations?{: #actions-update-delay_global_validations? } boolean false If true, global validations will be done in a before_action hook, regardless of their configuration on the resource.
skip_global_validations?{: #actions-update-skip_global_validations? } boolean false If true, global validations will be skipped. Useful for manual actions.
error_handler{: #actions-update-error_handler } mfa Sets the error handler on the changeset. See Ash.Changeset.handle_errors/2 for more
notifiers{: #actions-update-notifiers } list(module) Notifiers that will be called specifically for this action.
manual?{: #actions-update-manual? } boolean Instructs Ash to skip the actual update/create/destroy step at the data layer. See the manual actions guide for more.

actions.update.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

Examples

change relate_actor(:reporter)
change {MyCustomChange, :foo}

Arguments

Name Type Default Docs
change{: #actions-update-change-change .spark-required} (any, any -> any) | module The module and options for a change. Also accepts a function that takes the changeset and the context. See Ash.Resource.Change.Builtins for builtin changes.

Options

Name Type Default Docs
only_when_valid?{: #actions-update-change-only_when_valid? } boolean false If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description{: #actions-update-change-description } String.t An optional description for the change
where{: #actions-update-change-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this change to apply. These validations failing will result in this change being ignored.
always_atomic?{: #actions-update-change-always_atomic? } boolean false By default, changes are only run atomically if all changes will be run atomically or if there is no change/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Change

actions.update.validate

validate validation

Declares a validation to be applied to the changeset.

See Ash.Resource.Validation.Builtins or Ash.Resource.Validation for more.

Examples

validate changing(:email)

Arguments

Name Type Default Docs
validation{: #actions-update-validate-validation .spark-required} (any, any -> any) | module The module (or module and opts) that implements the Ash.Resource.Validation behaviour. Also accepts a function that receives the changeset and its context.

Options

Name Type Default Docs
where{: #actions-update-validate-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored.
only_when_valid?{: #actions-update-validate-only_when_valid? } boolean false If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message{: #actions-update-validate-message } String.t If provided, overrides any message set by the validation error
description{: #actions-update-validate-description } String.t An optional description for the validation
before_action?{: #actions-update-validate-before_action? } boolean false If set to true, the validation will be run in a before_action hook
always_atomic?{: #actions-update-validate-always_atomic? } boolean false By default, validations are only run atomically if all changes will be run atomically or if there is no validate/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Validation

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 after_action hook via Ash.Resource.put_metadata/3.

Examples

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

Arguments

Name Type Default Docs
name{: #actions-update-metadata-name .spark-required} atom The name of the metadata
type{: #actions-update-metadata-type .spark-required} any The type of the metadata. See Ash.Type for more.

Options

Name Type Default Docs
constraints{: #actions-update-metadata-constraints } keyword [] Type constraints on the metadata
description{: #actions-update-metadata-description } String.t An optional description for the metadata.
allow_nil?{: #actions-update-metadata-allow_nil? } boolean true Whether or not the metadata may return nil
default{: #actions-update-metadata-default } any The default value for the metadata to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Metadata

actions.update.argument

argument name, type

Declares an argument on the action

Examples

argument :password_confirmation, :string

Arguments

Name Type Default Docs
name{: #actions-update-argument-name .spark-required} atom The name of the argument
type{: #actions-update-argument-type .spark-required} module The type of the argument. See Ash.Type for more.

Options

Name Type Default Docs
description{: #actions-update-argument-description } String.t An optional description for the argument.
constraints{: #actions-update-argument-constraints } keyword [] Constraints to provide to the type when casting the value. For more information, see Ash.Type.
allow_nil?{: #actions-update-argument-allow_nil? } boolean true Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised.
public?{: #actions-update-argument-public? } boolean true Whether or not the argument should appear in public interfaces
sensitive?{: #actions-update-argument-sensitive? } boolean false Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the security guide for more.
default{: #actions-update-argument-default } any The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Argument

Introspection

Target: Ash.Resource.Actions.Update

actions.destroy

destroy name

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

Nested DSLs

Examples

destroy :destroy do
  primary? true
end

Arguments

Name Type Default Docs
name{: #actions-destroy-name .spark-required} atom The name of the action

Options

Name Type Default Docs
soft?{: #actions-destroy-soft? } boolean false If specified, the destroy action behaves as an update internally
manual{: #actions-destroy-manual } (any, any -> any) | module Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the manual actions guide for more.
require_atomic?{: #actions-destroy-require_atomic? } boolean true Require that the update be atomic. Only relevant if soft? is set to true. This means that all changes and validations implement the atomic callback. See the guide on atomic updates for more.
atomic_upgrade?{: #actions-destroy-atomic_upgrade? } boolean false If set to true, atomic upgrades will be performed. See the update actions guide for more.
atomic_upgrade_with{: #actions-destroy-atomic_upgrade_with } atom | nil Configure the read action used when performing atomic upgrades. Defaults to the primary read action.
primary?{: #actions-destroy-primary? } boolean false Whether or not this action should be used when no action is specified by the caller.
description{: #actions-destroy-description } String.t An optional description for the action
transaction?{: #actions-destroy-transaction? } boolean Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to true.
touches_resources{: #actions-destroy-touches_resources } list(atom) A list of resources that the action may touch, used when building transactions.
skip_unknown_inputs{: #actions-destroy-skip_unknown_inputs } atom | String.t | list(atom | String.t) [] A list of unknown fields to skip, or :* to skip all unknown fields.
accept{: #actions-destroy-accept } atom | list(atom) | :* The list of attributes to accept. Use :* to accept all public attributes.
action_select{: #actions-destroy-action_select } list(atom) A list of attributes that the action requires to do its work. Defaults to all attributes except those with select_by_default? false. On actions with no changes/notifiers, it defaults to the externally selected attributes. Keep in mind that action_select is applied before notifiers.
require_attributes{: #actions-destroy-require_attributes } list(atom) A list of attributes that would normally allow_nil?, to require for this action. No need to include attributes that already do not allow nil?
allow_nil_input{: #actions-destroy-allow_nil_input } list(atom) A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the data layer step.
delay_global_validations?{: #actions-destroy-delay_global_validations? } boolean false If true, global validations will be done in a before_action hook, regardless of their configuration on the resource.
skip_global_validations?{: #actions-destroy-skip_global_validations? } boolean false If true, global validations will be skipped. Useful for manual actions.
error_handler{: #actions-destroy-error_handler } mfa Sets the error handler on the changeset. See Ash.Changeset.handle_errors/2 for more
notifiers{: #actions-destroy-notifiers } list(module) Notifiers that will be called specifically for this action.
manual?{: #actions-destroy-manual? } boolean Instructs Ash to skip the actual update/create/destroy step at the data layer. See the manual actions guide for more.

actions.destroy.change

change change

A change to be applied to the changeset.

See Ash.Resource.Change for more.

Examples

change relate_actor(:reporter)
change {MyCustomChange, :foo}

Arguments

Name Type Default Docs
change{: #actions-destroy-change-change .spark-required} (any, any -> any) | module The module and options for a change. Also accepts a function that takes the changeset and the context. See Ash.Resource.Change.Builtins for builtin changes.

Options

Name Type Default Docs
only_when_valid?{: #actions-destroy-change-only_when_valid? } boolean false If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description{: #actions-destroy-change-description } String.t An optional description for the change
where{: #actions-destroy-change-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this change to apply. These validations failing will result in this change being ignored.
always_atomic?{: #actions-destroy-change-always_atomic? } boolean false By default, changes are only run atomically if all changes will be run atomically or if there is no change/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Change

actions.destroy.validate

validate validation

Declares a validation to be applied to the changeset.

See Ash.Resource.Validation.Builtins or Ash.Resource.Validation for more.

Examples

validate changing(:email)

Arguments

Name Type Default Docs
validation{: #actions-destroy-validate-validation .spark-required} (any, any -> any) | module The module (or module and opts) that implements the Ash.Resource.Validation behaviour. Also accepts a function that receives the changeset and its context.

Options

Name Type Default Docs
where{: #actions-destroy-validate-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored.
only_when_valid?{: #actions-destroy-validate-only_when_valid? } boolean false If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message{: #actions-destroy-validate-message } String.t If provided, overrides any message set by the validation error
description{: #actions-destroy-validate-description } String.t An optional description for the validation
before_action?{: #actions-destroy-validate-before_action? } boolean false If set to true, the validation will be run in a before_action hook
always_atomic?{: #actions-destroy-validate-always_atomic? } boolean false By default, validations are only run atomically if all changes will be run atomically or if there is no validate/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Validation

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 after_action hook via Ash.Resource.put_metadata/3.

Examples

metadata :api_token, :string, allow_nil?: false

metadata :operation_id, :string, allow_nil?: false

Arguments

Name Type Default Docs
name{: #actions-destroy-metadata-name .spark-required} atom The name of the metadata
type{: #actions-destroy-metadata-type .spark-required} any The type of the metadata. See Ash.Type for more.

Options

Name Type Default Docs
constraints{: #actions-destroy-metadata-constraints } keyword [] Type constraints on the metadata
description{: #actions-destroy-metadata-description } String.t An optional description for the metadata.
allow_nil?{: #actions-destroy-metadata-allow_nil? } boolean true Whether or not the metadata may return nil
default{: #actions-destroy-metadata-default } any The default value for the metadata to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Metadata

actions.destroy.argument

argument name, type

Declares an argument on the action

Examples

argument :password_confirmation, :string

Arguments

Name Type Default Docs
name{: #actions-destroy-argument-name .spark-required} atom The name of the argument
type{: #actions-destroy-argument-type .spark-required} module The type of the argument. See Ash.Type for more.

Options

Name Type Default Docs
description{: #actions-destroy-argument-description } String.t An optional description for the argument.
constraints{: #actions-destroy-argument-constraints } keyword [] Constraints to provide to the type when casting the value. For more information, see Ash.Type.
allow_nil?{: #actions-destroy-argument-allow_nil? } boolean true Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised.
public?{: #actions-destroy-argument-public? } boolean true Whether or not the argument should appear in public interfaces
sensitive?{: #actions-destroy-argument-sensitive? } boolean false Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the security guide for more.
default{: #actions-destroy-argument-default } any The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value

Introspection

Target: Ash.Resource.Actions.Argument

Introspection

Target: Ash.Resource.Actions.Destroy

code_interface

Functions that will be defined on the resource. See the code interface guide for more.

Nested DSLs

Examples

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

Options

Name Type Default Docs
domain{: #code_interface-domain } module false Use the provided Domain instead of the resources configured domain when calling actions.
define?{: #code_interface-define? } boolean Whether or not to define the code interface in the resource.

code_interface.define

define name

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

Examples

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

Arguments

Name Type Default Docs
name{: #code_interface-define-name .spark-required} atom The name of the function that will be defined

Options

Name Type Default Docs
action{: #code_interface-define-action } atom The name of the action that will be called. Defaults to the same name as the function.
args{: #code_interface-define-args } list(atom | {:optional, atom}) Map specific arguments to named inputs. Can provide any argument/attributes that the action allows.
not_found_error?{: #code_interface-define-not_found_error? } boolean true If the action or interface is configured with get?: true, this determines whether or not an error is raised or nil is returned.
require_reference?{: #code_interface-define-require_reference? } boolean true For update and destroy actions, require a resource or identifier to be passed in as the first argument. Not relevant for other action types.
get?{: #code_interface-define-get? } boolean false Expects to only receive a single result from a read action or a bulk update/destroy, and returns a single result instead of a list. Sets require_reference? to false automatically.
get_by{: #code_interface-define-get_by } atom | list(atom) Takes a list of fields and adds those fields as arguments, which will then be used to filter. Sets get? to true and require_reference? to false automatically. Adds filters for read, update and destroy actions, replacing the record first argument.
get_by_identity{: #code_interface-define-get_by_identity } atom Takes an identity, gets its field list, and performs the same logic as get_by with those fields. Adds filters for read, update and destroy actions, replacing the record first argument.

Introspection

Target: Ash.Resource.Interface

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.

Examples

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

Arguments

Name Type Default Docs
name{: #code_interface-define_calculation-name .spark-required} atom The name of the function that will be defined

Options

Name Type Default Docs
calculation{: #code_interface-define_calculation-calculation } atom The name of the calculation that will be evaluated. Defaults to the same name as the function.
args{: #code_interface-define_calculation-args } any [] Supply field or argument values referenced by the calculation, in the form of :name, {:arg, :name} and/or {:ref, :name}. See the code interface guide for more.

Introspection

Target: Ash.Resource.CalculationInterface

resource

General resource configuration

Examples

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

Options

Name Type Default Docs
description{: #resource-description } String.t A human readable description of the resource, to be used in generated documentation
base_filter{: #resource-base_filter } any A filter statement to be applied to any queries on the resource
default_context{: #resource-default_context } any Default context to apply to any queries/changesets generated for this resource.
trace_name{: #resource-trace_name } String.t The name to use in traces. Defaults to the short_name stringified. See the monitoring guide for more.
short_name{: #resource-short_name } atom A short identifier for the resource, which should be unique. See the monitoring guide for more.
plural_name{: #resource-plural_name } atom A pluralized version of the resource short_name. May be used by generators or automated tooling.
require_primary_key?{: #resource-require_primary_key? } boolean true Allow the resource to be used without any primary key fields. Warning: this option is experimental, and should not be used unless you know what you're doing.

identities

Unique identifiers for the resource

Nested DSLs

Examples

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.

Examples

identity :name, [:name]
identity :full_name, [:first_name, :last_name]

Arguments

Name Type Default Docs
name{: #identities-identity-name .spark-required} atom The name of the identity.
keys{: #identities-identity-keys .spark-required} atom | list(atom) The names of the attributes that uniquely identify this resource.

Options

Name Type Default Docs
where{: #identities-identity-where } any A filter that expresses only matching records are unique on the provided keys. Ignored on embedded resources.
nils_distinct?{: #identities-identity-nils_distinct? } boolean true Whether or not nil values are considered always distinct from eachother. nil values won't conflict with eachother unless you set this option to false.
eager_check?{: #identities-identity-eager_check? } boolean false Whether or not this identity is validated to be unique at validation time.
eager_check_with{: #identities-identity-eager_check_with } module Validates that the unique identity provided is unique at validation time, outside of any transactions, using the domain module provided. Will default to resource's domain.
pre_check?{: #identities-identity-pre_check? } boolean false Whether or not this identity is validated to be unique in a before_action hook.
pre_check_with{: #identities-identity-pre_check_with } module Validates that the unique identity provided is unique in a before_action hook.
description{: #identities-identity-description } String.t An optional description for the identity
message{: #identities-identity-message } String.t An error message to use when the unique identity would be violated
all_tenants?{: #identities-identity-all_tenants? } boolean false Whether or not this identity is unique across all tenants. If the resource is not multitenant, has no effect.

Introspection

Target: Ash.Resource.Identity

changes

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

See Ash.Resource.Change for more.

Nested DSLs

Examples

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.

Examples

change relate_actor(:reporter)
change {MyCustomChange, :foo}

Arguments

Name Type Default Docs
change{: #changes-change-change .spark-required} (any, any -> any) | module The module and options for a change. Also accepts a function that takes the changeset and the context. See Ash.Resource.Change.Builtins for builtin changes.

Options

Name Type Default Docs
on{: #changes-change-on } :create | :update | :destroy | list(:create | :update | :destroy) [:create, :update] The action types the change should run on. Destroy actions are omitted by default as most changes don't make sense for a destroy.
only_when_valid?{: #changes-change-only_when_valid? } boolean false If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description{: #changes-change-description } String.t An optional description for the change
where{: #changes-change-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this change to apply. These validations failing will result in this change being ignored.
always_atomic?{: #changes-change-always_atomic? } boolean false By default, changes are only run atomically if all changes will be run atomically or if there is no change/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Change

preparations

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

Nested DSLs

Examples

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.

Examples

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

Arguments

Name Type Default Docs
preparation{: #preparations-prepare-preparation .spark-required} (any, any -> any) | module The module and options for a preparation. Also accepts functions take the query and the context.

Introspection

Target: Ash.Resource.Preparation

validations

Declare validations prior to performing actions against the resource

Nested DSLs

Examples

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.Validation.Builtins or Ash.Resource.Validation for more.

Examples

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

Arguments

Name Type Default Docs
validation{: #validations-validate-validation .spark-required} (any, any -> any) | module The module (or module and opts) that implements the Ash.Resource.Validation behaviour. Also accepts a function that receives the changeset and its context.

Options

Name Type Default Docs
where{: #validations-validate-where } (any, any -> any) | module | list((any, any -> any) | module) [] Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored.
on{: #validations-validate-on } :create | :update | :destroy | list(:create | :update | :destroy) [:create, :update] The action types the validation should run on. Many validations don't make sense in the context of deletion, so by default it is not included.
only_when_valid?{: #validations-validate-only_when_valid? } boolean false If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message{: #validations-validate-message } String.t If provided, overrides any message set by the validation error
description{: #validations-validate-description } String.t An optional description for the validation
before_action?{: #validations-validate-before_action? } boolean false If set to true, the validation will be run in a before_action hook
always_atomic?{: #validations-validate-always_atomic? } boolean false By default, validations are only run atomically if all changes will be run atomically or if there is no validate/3 callback defined. Set this to true to run it atomically always.

Introspection

Target: Ash.Resource.Validation

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.

Nested DSLs

Examples

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-count-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-count-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate

Options

Name Type Default Docs
uniq?{: #aggregates-count-uniq? } boolean false Whether or not to count unique values only
read_action{: #aggregates-count-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
field{: #aggregates-count-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource
filter{: #aggregates-count-filter } any [] A filter to apply to the aggregate
description{: #aggregates-count-description } String.t An optional description for the aggregate
default{: #aggregates-count-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-count-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-count-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-count-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-count-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-count-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.count.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-count-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-count-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

exists :has_ticket, :assigned_tickets

Arguments

Name Type Default Docs
name{: #aggregates-exists-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-exists-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate

Options

Name Type Default Docs
read_action{: #aggregates-exists-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-exists-filter } any [] A filter to apply to the aggregate
description{: #aggregates-exists-description } String.t An optional description for the aggregate
default{: #aggregates-exists-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-exists-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-exists-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-exists-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-exists-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-exists-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.exists.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-exists-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-exists-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-first-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-first-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
field{: #aggregates-first-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource

Options

Name Type Default Docs
include_nil?{: #aggregates-first-include_nil? } boolean false Whether or not to include nil values in the aggregate. Only relevant for list and first aggregates.
read_action{: #aggregates-first-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-first-filter } any [] A filter to apply to the aggregate
sort{: #aggregates-first-sort } any A sort to be applied to the aggregate
description{: #aggregates-first-description } String.t An optional description for the aggregate
default{: #aggregates-first-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-first-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-first-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-first-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-first-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-first-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.first.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-first-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-first-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-sum-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-sum-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
field{: #aggregates-sum-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource

Options

Name Type Default Docs
read_action{: #aggregates-sum-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-sum-filter } any [] A filter to apply to the aggregate
description{: #aggregates-sum-description } String.t An optional description for the aggregate
default{: #aggregates-sum-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-sum-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-sum-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-sum-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-sum-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-sum-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.sum.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-sum-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-sum-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-list-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-list-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
field{: #aggregates-list-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource

Options

Name Type Default Docs
include_nil?{: #aggregates-list-include_nil? } boolean false Whether or not to include nil values in the aggregate. Only relevant for list and first aggregates.
uniq?{: #aggregates-list-uniq? } boolean false Whether or not to count unique values only
read_action{: #aggregates-list-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-list-filter } any [] A filter to apply to the aggregate
sort{: #aggregates-list-sort } any A sort to be applied to the aggregate
description{: #aggregates-list-description } String.t An optional description for the aggregate
default{: #aggregates-list-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-list-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-list-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-list-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-list-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-list-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.list.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-list-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-list-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-max-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-max-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
field{: #aggregates-max-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource

Options

Name Type Default Docs
read_action{: #aggregates-max-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-max-filter } any [] A filter to apply to the aggregate
description{: #aggregates-max-description } String.t An optional description for the aggregate
default{: #aggregates-max-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-max-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-max-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-max-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-max-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-max-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.max.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-max-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-max-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-min-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-min-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
field{: #aggregates-min-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource

Options

Name Type Default Docs
read_action{: #aggregates-min-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-min-filter } any [] A filter to apply to the aggregate
description{: #aggregates-min-description } String.t An optional description for the aggregate
default{: #aggregates-min-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-min-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-min-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-min-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-min-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-min-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.min.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-min-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-min-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-avg-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-avg-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
field{: #aggregates-avg-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource

Options

Name Type Default Docs
read_action{: #aggregates-avg-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
filter{: #aggregates-avg-filter } any [] A filter to apply to the aggregate
description{: #aggregates-avg-description } String.t An optional description for the aggregate
default{: #aggregates-avg-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-avg-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-avg-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-avg-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-avg-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-avg-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.avg.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-avg-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-avg-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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

Arguments

Name Type Default Docs
name{: #aggregates-custom-name .spark-required} atom The field to place the aggregate in
relationship_path{: #aggregates-custom-relationship_path .spark-required} atom | list(atom) The relationship or relationship path to use for the aggregate
type{: #aggregates-custom-type .spark-required} module The type of the value returned by the aggregate

Options

Name Type Default Docs
implementation{: #aggregates-custom-implementation .spark-required} module The module that implements the relevant data layer callbacks
read_action{: #aggregates-custom-read_action } atom The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments.
field{: #aggregates-custom-field } atom The field to aggregate. Defaults to the first field in the primary key of the resource
filter{: #aggregates-custom-filter } any [] A filter to apply to the aggregate
sort{: #aggregates-custom-sort } any A sort to be applied to the aggregate
description{: #aggregates-custom-description } String.t An optional description for the aggregate
default{: #aggregates-custom-default } any A default value to use in cases where nil would be used. Count defaults to 0.
public?{: #aggregates-custom-public? } boolean false Whether or not the aggregate will appear in public interfaces
filterable?{: #aggregates-custom-filterable? } boolean | :simple_equality true Whether or not the aggregate should be usable in filters.
sortable?{: #aggregates-custom-sortable? } boolean true Whether or not the aggregate should be usable in sorts.
sensitive?{: #aggregates-custom-sensitive? } boolean false Whether or not the aggregate should be considered sensitive.
authorize?{: #aggregates-custom-authorize? } boolean true Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action.

aggregates.custom.join_filter

join_filter relationship_path, filter

Declares a join filter on an aggregate. See the aggregates guide for more.

Examples

join_filter [:comments, :author], expr(active == true)

Arguments

Name Type Default Docs
relationship_path{: #aggregates-custom-join_filter-relationship_path } atom | list(atom) The relationship path on which to apply the join filter
filter{: #aggregates-custom-join_filter-filter } any The filter to apply. Can be an expression or a filter template.

Introspection

Target: Ash.Resource.Aggregate.JoinFilter

Introspection

Target: Ash.Resource.Aggregate

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.

Nested DSLs

Examples

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.Resource.Calculation behaviour. See that module for more information.

To ensure that the necessary fields are loaded:

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

See the calculations guide for more.

Nested DSLs

Examples

Ash.Resource.Calculation implementation example:

calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}, load: [:first_name, :last_name]

expr/1 example:

calculate :full_name, :string, expr(first_name <> " " <> last_name)

Example with options:

calculate :full_name, :string, expr(first_name <> " " <> last_name), allow_nil?: false

Example with options in do block:

calculate :full_name, :string, expr(first_name <> " " <> last_name) do
  allow_nil? false
  public? true
end

Arguments

Name Type Default Docs
name{: #calculations-calculate-name .spark-required} atom The field name to use for the calculation value
type{: #calculations-calculate-type .spark-required} any The type of the calculation. See Ash.Type for more.
calculation{: #calculations-calculate-calculation .spark-required} (any, any -> any) | module | any The module, {module, opts} or expr(...) to use for the calculation. Also accepts a function that takes a list of records and produces a result for each record.

Options

Name Type Default Docs
async?{: #calculations-calculate-async? } boolean false
constraints{: #calculations-calculate-constraints } keyword [] Constraints to provide to the type. See Ash.Type for more.
description{: #calculations-calculate-description } String.t An optional description for the calculation
public?{: #calculations-calculate-public? } boolean false Whether or not the calculation will appear in public interfaces.
sensitive?{: #calculations-calculate-sensitive? } boolean false Whether or not references to the calculation will be considered sensitive.
load{: #calculations-calculate-load } any [] A load statement to be applied if the calculation is used.
allow_nil?{: #calculations-calculate-allow_nil? } boolean true Whether or not the calculation can return nil.
filterable?{: #calculations-calculate-filterable? } boolean | :simple_equality true Whether or not the calculation should be usable in filters.
sortable?{: #calculations-calculate-sortable? } boolean true Whether or not the calculation can be referenced in sorts.

calculations.calculate.argument

argument name, type

An argument to be passed into the calculation's arguments map

See the calculations guide for more.

Examples

argument :params, :map do
  default %{}
end

argument :retries, :integer do
  allow_nil? false
end

Arguments

Name Type Default Docs
name{: #calculations-calculate-argument-name .spark-required} atom The name of the argument
type{: #calculations-calculate-argument-type .spark-required} module The type of the argument. See Ash.Type for more.

Options

Name Type Default Docs
default{: #calculations-calculate-argument-default } (-> any) | mfa | any A default value to use for the argument if not provided
allow_nil?{: #calculations-calculate-argument-allow_nil? } boolean true Whether or not the argument value may be nil (or may be not provided)
allow_expr?{: #calculations-calculate-argument-allow_expr? } boolean false Allow passing expressions as argument values. Expressions cannot be type validated.
constraints{: #calculations-calculate-argument-constraints } keyword [] Constraints to provide to the type when casting the value. See the type's documentation and Ash.Type for more.

Introspection

Target: Ash.Resource.Calculation.Argument

Introspection

Target: Ash.Resource.Calculation

multitenancy

Options for configuring the multitenancy behavior of a resource.

To specify a tenant, use Ash.Query.set_tenant/2 or Ash.Changeset.set_tenant/2 before passing it to an operation.

See the multitenancy guide

Examples

multitenancy do
  strategy :attribute
  attribute :organization_id
  global? true
end

Options

Name Type Default Docs
strategy{: #multitenancy-strategy } :context | :attribute :context Determine if multitenancy is performed with attribute filters or using data layer features.
attribute{: #multitenancy-attribute } atom If using the attribute strategy, the attribute to use, e.g org_id
global?{: #multitenancy-global? } boolean false Whether or not the data may be accessed without setting a tenant. For example, with attribute multitenancy, this allows accessing without filtering by the tenant attribute.
parse_attribute{: #multitenancy-parse_attribute } mfa {Ash.Resource.Dsl, :identity, []} An mfa ({module, function, args}) pointing to a function that takes a tenant and returns the attribute value
<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>