# DSL: Ash.Resource.Dsl ## attributes A section for declaring attributes on the resource. ### Nested DSLs * [attribute](#attributes-attribute) * [create_timestamp](#attributes-create_timestamp) * [update_timestamp](#attributes-update_timestamp) * [integer_primary_key](#attributes-integer_primary_key) * [uuid_primary_key](#attributes-uuid_primary_key) ### 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 ```elixir attribute name, type ``` Declares an attribute on the resource. ### Examples ``` attribute :name, :string do allow_nil? false end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the attribute.
type *	module		The type of the attribute. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
constraints	Keyword.t		Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md).
description	String.t		An optional description for the attribute.
sensitive?	boolean	false	Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more.
source	atom		If the field should be mapped to a different name in the data layer. Support varies by data layer.
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?	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?	boolean	true	Whether or not the attribute can be set to nil. If nil value is given error is raised.
generated?	boolean	false	Whether or not the value may be generated by the data layer.
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`.
private?	boolean	false	The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more.
default	(-> any) | mfa | any()		A value to be set on all creates, unless a value is being provided already.
update_default	(-> any) | mfa | any()		A value to be set on all updates, unless a value is being provided already.
filterable?	boolean | :simple_equality	true	Whether or not the attribute can be referenced in filters.
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 ```elixir 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 private? true 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 *	atom		The name of the attribute.

### Options

Name	Type	Default	Docs
type	module	Ash.Type.UtcDatetimeUsec	The type of the attribute. See `Ash.Type` for more.
constraints	Keyword.t		Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md).
description	String.t		An optional description for the attribute.
sensitive?	boolean	false	Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more.
source	atom		If the field should be mapped to a different name in the data layer. Support varies by data layer.
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?	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?	boolean	false	Whether or not the attribute can be set to nil. If nil value is given error is raised.
generated?	boolean	false	Whether or not the value may be generated by the data layer.
writable?	boolean	false	Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`.
private?	boolean	true	The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more.
default	(-> any) | mfa | any()	&DateTime.utc_now/0	A value to be set on all creates, unless a value is being provided already.
update_default	(-> any) | mfa | any()		A value to be set on all updates, unless a value is being provided already.
filterable?	boolean | :simple_equality	true	Whether or not the attribute can be referenced in filters.
match_other_defaults?	boolean	true	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.update_timestamp ```elixir 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 private? true 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 *	atom		The name of the attribute.

### Options

Name	Type	Default	Docs
type	module	Ash.Type.UtcDatetimeUsec	The type of the attribute. See `Ash.Type` for more.
constraints	Keyword.t		Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md).
description	String.t		An optional description for the attribute.
sensitive?	boolean	false	Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more.
source	atom		If the field should be mapped to a different name in the data layer. Support varies by data layer.
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?	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?	boolean	false	Whether or not the attribute can be set to nil. If nil value is given error is raised.
generated?	boolean	false	Whether or not the value may be generated by the data layer.
writable?	boolean	false	Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`.
private?	boolean	true	The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more.
default	(-> any) | mfa | any()	&DateTime.utc_now/0	A value to be set on all creates, unless a value is being provided already.
update_default	(-> any) | mfa | any()	&DateTime.utc_now/0	A value to be set on all updates, unless a value is being provided already.
filterable?	boolean | :simple_equality	true	Whether or not the attribute can be referenced in filters.
match_other_defaults?	boolean	true	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.integer_primary_key ```elixir 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: writable? false primary_key? true generated? true type :integer ### Examples ``` integer_primary_key :id ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the attribute.

### Options

Name	Type	Default	Docs
type	module	:integer	The type of the attribute. See `Ash.Type` for more.
constraints	Keyword.t		Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md).
description	String.t		An optional description for the attribute.
sensitive?	boolean	false	Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more.
source	atom		If the field should be mapped to a different name in the data layer. Support varies by data layer.
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?	boolean	true	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.
generated?	boolean	true	Whether or not the value may be generated by the data layer.
writable?	boolean	false	Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`.
private?	boolean	false	The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more.
default	(-> any) | mfa | any()		A value to be set on all creates, unless a value is being provided already.
update_default	(-> any) | mfa | any()		A value to be set on all updates, unless a value is being provided already.
filterable?	boolean | :simple_equality	true	Whether or not the attribute can be referenced in filters.
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.uuid_primary_key ```elixir 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 default &Ash.UUID.generate/0 primary_key? true generated? true type :uuid ### Examples ``` uuid_primary_key :id ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the attribute.

### Options

Name	Type	Default	Docs
type	module	:uuid	The type of the attribute. See `Ash.Type` for more.
constraints	Keyword.t		Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md).
description	String.t		An optional description for the attribute.
sensitive?	boolean	false	Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more.
source	atom		If the field should be mapped to a different name in the data layer. Support varies by data layer.
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?	boolean	true	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.
generated?	boolean	false	Whether or not the value may be generated by the data layer.
writable?	boolean	false	Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`.
private?	boolean	false	The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more.
default	(-> any) | mfa | any()	&Ash.UUID.generate/0	A value to be set on all creates, unless a value is being provided already.
update_default	(-> any) | mfa | any()		A value to be set on all updates, unless a value is being provided already.
filterable?	boolean | :simple_equality	true	Whether or not the attribute can be referenced in filters.
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` ## 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](/documentation/topics/relationships.md) for more. ### Nested DSLs * [has_one](#relationships-has_one) * [has_many](#relationships-has_many) * [many_to_many](#relationships-many_to_many) * [belongs_to](#relationships-belongs_to) ### 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 ```elixir 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](/documentation/topics/relationships.md) for more. ### 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	atom		The name of the relationship
destination	module		The destination resource

### Options

Name	Type	Default	Docs
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?	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](/documentation/topics/relationships.md) for more.
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?	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	String.t		An optional description for the relationship
destination_attribute	atom		The attribute on the related resource that should match the `source_attribute` configured on this resource.
validate_destination_attribute?	boolean	true	Whether or not to validate that the destination field exists on the destination resource
source_attribute	atom	:id	The field on this resource that should match the `destination_attribute` on the related resource.
relationship_context	`any`		Context to be set on any queries or changesets generated for managing or querying this relationship.
private?	boolean	false	Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more.
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?	boolean	true	Whether or not the relationship may be managed.
read_action	atom		The read action on the destination resource to use when loading data and filtering.
api	atom		The API module to use when working with the related entity.
filter	`any`		A filter to be applied when reading the relationship.
filterable?	boolean	true	If set to `false`, the relationship will not be usable in filters.
sort	`any`		A sort statement to be applied when loading the relationship.
could_be_related_at_creation?	boolean	false	Whether or not related values may exist for this relationship at creation.
violation_message	String.t		A message to show if there is a conflict with this relationship in the database on destroy.

### Introspection Target: `Ash.Resource.Relationships.HasOne` ## relationships.has_many ```elixir has_many name, destination ``` Declares a `has_many` relationship. There can be any number of related entities. See the [relationships guide](/documentation/topics/relationships.md) for more. ### 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	atom		The name of the relationship
destination	module		The destination resource

### Options

Name	Type	Default	Docs
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?	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](/documentation/topics/relationships.md) for more.
description	String.t		An optional description for the relationship
destination_attribute	atom		The attribute on the related resource that should match the `source_attribute` configured on this resource.
validate_destination_attribute?	boolean	true	Whether or not to validate that the destination field exists on the destination resource
source_attribute	atom	:id	The field on this resource that should match the `destination_attribute` on the related resource.
relationship_context	`any`		Context to be set on any queries or changesets generated for managing or querying this relationship.
private?	boolean	false	Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more.
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?	boolean	true	Whether or not the relationship may be managed.
read_action	atom		The read action on the destination resource to use when loading data and filtering.
api	atom		The API module to use when working with the related entity.
filter	`any`		A filter to be applied when reading the relationship.
filterable?	boolean	true	If set to `false`, the relationship will not be usable in filters.
sort	`any`		A sort statement to be applied when loading the relationship.
could_be_related_at_creation?	boolean	false	Whether or not related values may exist for this relationship at creation.
violation_message	String.t		A message to show if there is a conflict with this relationship in the database on destroy.

### Introspection Target: `Ash.Resource.Relationships.HasMany` ## relationships.many_to_many ```elixir 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](/documentation/topics/relationships.md) for more. ### 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	atom		The name of the relationship
destination	module		The destination resource

### Options

Name	Type	Default	Docs
source_attribute_on_join_resource *	atom		The attribute on the join resource that should line up with `source_attribute` on this resource.
destination_attribute_on_join_resource *	atom		The attribute on the join resource that should line up with `destination_attribute` on the related resource.
through *	module		The resource to use as the join resource.
join_relationship	atom		The has_many relationship to the join resource. Defaults to _join_assoc
description	String.t		An optional description for the relationship
destination_attribute	atom	:id	The attribute on the related resource that should match the `source_attribute` configured on this resource.
validate_destination_attribute?	boolean	true	Whether or not to validate that the destination field exists on the destination resource
source_attribute	atom	:id	The field on this resource that should match the `destination_attribute` on the related resource.
relationship_context	`any`		Context to be set on any queries or changesets generated for managing or querying this relationship.
private?	boolean	false	Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more.
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?	boolean	true	Whether or not the relationship may be managed.
read_action	atom		The read action on the destination resource to use when loading data and filtering.
api	atom		The API module to use when working with the related entity.
filter	`any`		A filter to be applied when reading the relationship.
filterable?	boolean	true	If set to `false`, the relationship will not be usable in filters.
sort	`any`		A sort statement to be applied when loading the relationship.
could_be_related_at_creation?	boolean	false	Whether or not related values may exist for this relationship at creation.
violation_message	String.t		A message to show if there is a conflict with this relationship in the database on destroy.

### Introspection Target: `Ash.Resource.Relationships.ManyToMany` ## relationships.belongs_to ```elixir 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](/documentation/topics/relationships.md) for more. ### 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	atom		The name of the relationship
destination	module		The destination resource

### Options

Name	Type	Default	Docs
primary_key?	boolean	false	Whether the generated attribute is, or is part of, the primary key of a resource.
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?	boolean	false	Whether the generated attribute will be marked as public & writable.
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	`any`	:uuid	The type of the generated created attribute. See `Ash.Type` for more.
description	String.t		An optional description for the relationship
destination_attribute	atom	:id	The attribute on the related resource that should match the `source_attribute` configured on this resource.
validate_destination_attribute?	boolean	true	Whether or not to validate that the destination field exists on the destination resource
source_attribute	atom		The field on this resource that should match the `destination_attribute` on the related resource. - Defaults to _id
relationship_context	`any`		Context to be set on any queries or changesets generated for managing or querying this relationship.
private?	boolean	false	Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more.
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?	boolean	true	Whether or not the relationship may be managed.
read_action	atom		The read action on the destination resource to use when loading data and filtering.
api	atom		The API module to use when working with the related entity.
filter	`any`		A filter to be applied when reading the relationship.
filterable?	boolean	true	If set to `false`, the relationship will not be usable in filters.
sort	`any`		A sort statement to be applied when loading the relationship.
violation_message	String.t		A message to show if there is a conflict with this relationship in the database on destroy.

### 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](#actions-action) * argument * [create](#actions-create) * change * validate * argument * metadata * [read](#actions-read) * argument * prepare * pagination * metadata * [update](#actions-update) * change * validate * metadata * argument * [destroy](#actions-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	list(:create | :read | :update | :destroy)		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	list(atom)		A default value for the `accept` option for each action. Defaults to all public attributes.

## actions.action ```elixir action name, returns ``` Declares a generic action. A combination of arguments, a return type and a run function. For calling this action, see the `Ash.Api` documentation. ### Nested DSLs * [argument](#actions-action-argument) ### 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.limit) do {:ok, Enum.map(top_users, &(&1.email))} end end end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the action
returns	module		The return type of the action. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
constraints	Keyword.t		Constraints for the return type. See the [constriants topic](/documentation/topics/constraints.md) for more.
allow_nil?	boolean	false	Wether or not the action can return nil. Unlike attributes & arguments, this defaults to `false`.
run	(any, any -> any) | module
primary?	boolean	false	Whether or not this action should be used when no action is specified by the caller.
description	String.t		An optional description for the 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	list(atom)		A list of resources that the action may touch, used when building transactions.

## actions.action.argument ```elixir argument name, type ``` Declares an argument on the action ### Examples ``` argument :password_confirmation, :string ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the argument
type *	module		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
description	String.t		An optional description for the argument.
constraints	Keyword.t	[]	Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md).
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.
private?	boolean	false	Whether or not the argument should be suppliable by the client.
sensitive?	boolean	false	Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more.
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 ```elixir create name ``` Declares a `create` action. For calling this action, see the `Ash.Api` documentation. ### Nested DSLs * [change](#actions-create-change) * [validate](#actions-create-validate) * [argument](#actions-create-argument) * [metadata](#actions-create-metadata) ### Examples ``` create :register do primary? true end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the action

### Options

Name	Type	Default	Docs
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 record is created.
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](/documentation/topics/manual-actions.md) for more.
upsert?	boolean	false	Forces all uses of this action to be treated as an upsert.
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	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.
primary?	boolean	false	Whether or not this action should be used when no action is specified by the caller.
description	String.t		An optional description for the 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	list(atom)		A list of resources that the action may touch, used when building transactions.
accept	:all | list(atom)		The list of attributes to accept. Defaults to all attributes on the resource
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?	boolean	false	If true, global validations will be skipped. Useful for manual actions.
reject	:all | list(atom)		A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list.
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?
error_handler	mfa		Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more
manual?	boolean		Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more.

## actions.create.change ```elixir 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 *	(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?	boolean	false	If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description	String.t		An optional description for the change
where	list((any -> any) | module)	[]	Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored.

### Introspection Target: `Ash.Resource.Change` ## actions.create.validate ```elixir validate validation ``` Declares a validation to be applied to the changeset. See `Ash.Resource.Validation` for more. ### Examples ``` validate changing(:email) ``` ### Arguments

Name	Type	Default	Docs
validation *	(any -> any) | module		The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset.

### Options

Name	Type	Default	Docs
where	list((any -> any) | module) | (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?	boolean	false	If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message	String.t		If provided, overrides any message set by the validation error
description	String.t		An optional description for the validation
before_action?	boolean	false	If set to `true`, the validation will be run in a before_action hook

### Introspection Target: `Ash.Resource.Validation` ## actions.create.argument ```elixir argument name, type ``` Declares an argument on the action ### Examples ``` argument :password_confirmation, :string ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the argument
type *	module		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
description	String.t		An optional description for the argument.
constraints	Keyword.t	[]	Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md).
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.
private?	boolean	false	Whether or not the argument should be suppliable by the client.
sensitive?	boolean	false	Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more.
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 ```elixir metadata name, type ``` A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via `Ash.Resource.Info.put_metadata/3`. ### Examples ``` metadata :api_token, :string, allow_nil?: false ``` ``` metadata :operation_id, :string, allow_nil?: false ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the metadata
type *	`any`		The type of the metadata. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
constraints	Keyword.t	[]	Type constraints on the metadata
description	String.t		An optional description for the metadata.
allow_nil?	boolean	true	Whether or not the metadata may return `nil`
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 ```elixir read name ``` Declares a `read` action. For calling this action, see the `Ash.Api` documentation. ### Nested DSLs * [argument](#actions-read-argument) * [prepare](#actions-read-prepare) * [pagination](#actions-read-pagination) * [metadata](#actions-read-metadata) ### Examples ``` read :read_all do primary? true end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the action

### Options

Name	Type	Default	Docs
filter	`any`		A filter template that will be applied whenever the action is used. See `Ash.Filter` for more on templates
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 changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more.
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](/documentation/topics/code-interface.md) for more.
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	list(atom) | 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.
primary?	boolean	false	Whether or not this action should be used when no action is specified by the caller.
description	String.t		An optional description for the 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	list(atom)		A list of resources that the action may touch, used when building transactions.

## actions.read.argument ```elixir argument name, type ``` Declares an argument on the action ### Examples ``` argument :password_confirmation, :string ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the argument
type *	module		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
description	String.t		An optional description for the argument.
constraints	Keyword.t	[]	Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md).
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.
private?	boolean	false	Whether or not the argument should be suppliable by the client.
sensitive?	boolean	false	Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more.
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 ```elixir 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 *	(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?	boolean	false	Whether or not keyset based pagination is supported
offset?	boolean	false	Whether or not offset based pagination is supported
default_limit	pos_integer		The default page size to apply, if one is not supplied
countable	true | false | :by_default	false	Whether not a returned page will have a full count of all records. Use `:by_default` to do it automatically.
max_page_size	pos_integer	250	The maximum amount of records that can be requested in a single page
required?	boolean	true	Whether or not pagination can be disabled. Only relevant if some pagination configuration is supplied.

### Introspection Target: `Ash.Resource.Actions.Read.Pagination` ## actions.read.metadata ```elixir metadata name, type ``` A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via `Ash.Resource.Info.put_metadata/3`. ### Examples ``` metadata :api_token, :string, allow_nil?: false ``` ``` metadata :operation_id, :string, allow_nil?: false ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the metadata
type *	`any`		The type of the metadata. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
constraints	Keyword.t	[]	Type constraints on the metadata
description	String.t		An optional description for the metadata.
allow_nil?	boolean	true	Whether or not the metadata may return `nil`
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.Read` ## actions.update ```elixir update name ``` Declares a `update` action. For calling this action, see the `Ash.Api` documentation. ### Nested DSLs * [change](#actions-update-change) * [validate](#actions-update-validate) * [metadata](#actions-update-metadata) * [argument](#actions-update-argument) ### Examples ``` update :flag_for_review, primary?: true ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the action

### Options

Name	Type	Default	Docs
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](/documentation/topics/manual-actions.md) for more.
primary?	boolean	false	Whether or not this action should be used when no action is specified by the caller.
description	String.t		An optional description for the 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	list(atom)		A list of resources that the action may touch, used when building transactions.
accept	:all | list(atom)		The list of attributes to accept. Defaults to all attributes on the resource
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?	boolean	false	If true, global validations will be skipped. Useful for manual actions.
reject	:all | list(atom)		A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list.
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?
error_handler	mfa		Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more
manual?	boolean		Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more.

## actions.update.change ```elixir 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 *	(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?	boolean	false	If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description	String.t		An optional description for the change
where	list((any -> any) | module)	[]	Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored.

### Introspection Target: `Ash.Resource.Change` ## actions.update.validate ```elixir validate validation ``` Declares a validation to be applied to the changeset. See `Ash.Resource.Validation` for more. ### Examples ``` validate changing(:email) ``` ### Arguments

Name	Type	Default	Docs
validation *	(any -> any) | module		The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset.

### Options

Name	Type	Default	Docs
where	list((any -> any) | module) | (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?	boolean	false	If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message	String.t		If provided, overrides any message set by the validation error
description	String.t		An optional description for the validation
before_action?	boolean	false	If set to `true`, the validation will be run in a before_action hook

### Introspection Target: `Ash.Resource.Validation` ## actions.update.metadata ```elixir metadata name, type ``` A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via `Ash.Resource.Info.put_metadata/3`. ### Examples ``` metadata :api_token, :string, allow_nil?: false ``` ``` metadata :operation_id, :string, allow_nil?: false ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the metadata
type *	`any`		The type of the metadata. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
constraints	Keyword.t	[]	Type constraints on the metadata
description	String.t		An optional description for the metadata.
allow_nil?	boolean	true	Whether or not the metadata may return `nil`
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 ```elixir argument name, type ``` Declares an argument on the action ### Examples ``` argument :password_confirmation, :string ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the argument
type *	module		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
description	String.t		An optional description for the argument.
constraints	Keyword.t	[]	Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md).
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.
private?	boolean	false	Whether or not the argument should be suppliable by the client.
sensitive?	boolean	false	Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more.
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 ```elixir destroy name ``` Declares a `destroy` action. For calling this action, see the `Ash.Api` documentation. ### Nested DSLs * [change](#actions-destroy-change) * [validate](#actions-destroy-validate) * [metadata](#actions-destroy-metadata) * [argument](#actions-destroy-argument) ### Examples ``` destroy :soft_delete do primary? true end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the action

### Options

Name	Type	Default	Docs
soft?	atom	false	If specified, the destroy action behaves as an update internally
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](/documentation/topics/manual-actions.md) for more.
primary?	boolean	false	Whether or not this action should be used when no action is specified by the caller.
description	String.t		An optional description for the 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	list(atom)		A list of resources that the action may touch, used when building transactions.
accept	:all | list(atom)		The list of attributes to accept. Defaults to all attributes on the resource
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?	boolean	false	If true, global validations will be skipped. Useful for manual actions.
reject	:all | list(atom)		A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list.
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?
error_handler	mfa		Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more
manual?	boolean		Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more.

## actions.destroy.change ```elixir 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 *	(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?	boolean	false	If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here.
description	String.t		An optional description for the change
where	list((any -> any) | module)	[]	Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored.

### Introspection Target: `Ash.Resource.Change` ## actions.destroy.validate ```elixir validate validation ``` Declares a validation to be applied to the changeset. See `Ash.Resource.Validation` for more. ### Examples ``` validate changing(:email) ``` ### Arguments

Name	Type	Default	Docs
validation *	(any -> any) | module		The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset.

### Options

Name	Type	Default	Docs
where	list((any -> any) | module) | (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?	boolean	false	If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message	String.t		If provided, overrides any message set by the validation error
description	String.t		An optional description for the validation
before_action?	boolean	false	If set to `true`, the validation will be run in a before_action hook

### Introspection Target: `Ash.Resource.Validation` ## actions.destroy.metadata ```elixir metadata name, type ``` A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom change via `Ash.Resource.Info.put_metadata/3`. ### Examples ``` metadata :api_token, :string, allow_nil?: false ``` ``` metadata :operation_id, :string, allow_nil?: false ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the metadata
type *	`any`		The type of the metadata. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
constraints	Keyword.t	[]	Type constraints on the metadata
description	String.t		An optional description for the metadata.
allow_nil?	boolean	true	Whether or not the metadata may return `nil`
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 ```elixir argument name, type ``` Declares an argument on the action ### Examples ``` argument :password_confirmation, :string ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the argument
type *	module		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
description	String.t		An optional description for the argument.
constraints	Keyword.t	[]	Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md).
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.
private?	boolean	false	Whether or not the argument should be suppliable by the client.
sensitive?	boolean	false	Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more.
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 Api module to interact with this resource. See the [code interface guide](/documentation/topics/code-interface.md) for more. ### Nested DSLs * [define](#code_interface-define) * [define_calculation](#code_interface-define_calculation) ### Examples ``` code_interface do define_for MyApp.Api define :create_user, action: :create define :get_user_by_id, action: :get_by_id, args: [:id], get?: true end ``` ### Options

Name	Type	Default	Docs
define_for	module	false	Defines the code interface on the resource module directly, using the provided Api.

## code_interface.define ```elixir define name ``` Defines a function with the corresponding name and arguments. See the [code interface guide](/documentation/topics/code-interface.md) for more. ### Examples ``` define :get_user_by_id, action: :get_by_id, args: [:id], get?: true ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the function that will be defined

### Options

Name	Type	Default	Docs
action	atom		The name of the action that will be called. Defaults to the same name as the function.
args	list(atom | {:optional, atom})		Map specific arguments to named inputs. Can provide any argument/attributes that the action allows.
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.
get?	boolean		Expects to only receive a single result from a read action, and returns a single result instead of a list. Ignored for other action types.
get_by	list(atom) | atom		Takes a list of fields and adds those fields as arguments, which will then be used to filter. Sets `get?` to true automatically. Ignored for non-read actions.
get_by_identity	atom		Only relevant for read actions. Takes an identity, and gets its field list, performing the same logic as `get_by` once it has the list of fields.

### Introspection Target: `Ash.Resource.Interface` ## code_interface.define_calculation ```elixir 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](/documentation/topics/code-interface.md) for more. ### Examples ``` define_calculation :referral_link, args: [:id] ``` ``` define_calculation :referral_link, args: [{:arg, :id}, {:ref, :id}] ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the function that will be defined

### Options

Name	Type	Default	Docs
calculation	atom		The name of the calculation that will be evaluated. Defaults to the same name as the function.
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](/documentation/topics/code-interface.md) 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	String.t		A human readable description of the resource, to be used in generated documentation
base_filter	`any`		A filter statement to be applied to any queries on the resource
default_context	`any`		Default context to apply to any queries/changesets generated for this resource.
trace_name	String.t		The name to use in traces. Defaults to the short_name stringified. See the [monitoring guide](/documentation/topics/monitoring.md) for more.
short_name	atom		A short identifier for the resource, which should be unique. See the [monitoring guide](/documentation/topics/monitoring.md) for more.
plural_name	atom		A pluralized version of the resource short_name. May be used by generators or automated tooling.
simple_notifiers	list(module)		A list of notifiers that require no DSL. Can be used to avoid compile time dependencies on notifiers
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 * [identity](#identities-identity) ### Examples ``` identities do identity :full_name, [:first_name, :last_name] identity :email, [:email] end ``` ## identities.identity ```elixir identity name, keys ``` Represents a unique constraint on the resource. See the [identities guide](/documentation/topics/identities.md) for more. ### Examples ``` identity :name, [:name] ``` ``` identity :full_name, [:first_name, :last_name] ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the identity.
keys *	list(atom) | atom		The names of the attributes that uniquely identify this resource.

### Options

Name	Type	Default	Docs
eager_check_with	module		Validates that the unique identity provided is unique at validation time, outside of any transactions, using the api module provided.
pre_check_with	module		Validates that the unique identity provided is unique in a before_action hook.
description	String.t		An optional description for the identity
message	String.t		An error message to use when the unique identity would be violated

### 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 * [change](#changes-change) ### Examples ``` changes do change {Mod, [foo: :bar]} change set_context(%{some: :context}) end ``` ## changes.change ```elixir 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 *	(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	list(:create | :update | :destroy) | :create | :update | :destroy	[:create, :update]	The action types the validation should run on. Destroy actions are omitted by default as most changes don't make sense for a destroy.
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	String.t		An optional description for the change
where	list((any -> any) | module)	[]	Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored.

### Introspection Target: `Ash.Resource.Change` ## preparations Declare preparations that occur on all read actions for a given resource ### Nested DSLs * [prepare](#preparations-prepare) ### Examples ``` preparations do prepare {Mod, [foo: :bar]} prepare set_context(%{some: :context}) end ``` ## preparations.prepare ```elixir 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 *	(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 * [validate](#validations-validate) ### Examples ``` validations do validate {Mod, [foo: :bar]} validate at_least_one_of_present([:first_name, :last_name]) end ``` ## validations.validate ```elixir validate validation ``` Declares a validation for creates and updates. See `Ash.Resource.Change` for more. ### Examples ``` validate {Mod, [foo: :bar]} ``` ``` validate at_least_one_of_present([:first_name, :last_name]) ``` ### Arguments

Name	Type	Default	Docs
validation *	(any -> any) | module		The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset.

### Options

Name	Type	Default	Docs
where	list((any -> any) | module) | (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	list(:create | :update | :destroy) | :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?	boolean	false	If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data.
message	String.t		If provided, overrides any message set by the validation error
description	String.t		An optional description for the validation
before_action?	boolean	false	If set to `true`, the validation will be run in a before_action hook

### 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](/documentation/topics/aggregates.md) for more. ### Nested DSLs * [count](#aggregates-count) * [exists](#aggregates-exists) * [first](#aggregates-first) * [sum](#aggregates-sum) * [list](#aggregates-list) * [max](#aggregates-max) * [min](#aggregates-min) * [avg](#aggregates-avg) * [custom](#aggregates-custom) ### Examples ``` aggregates do count :assigned_ticket_count, :reported_tickets do filter [active: true] end end ``` ## aggregates.count ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` count :assigned_ticket_count, :assigned_tickets do filter [active: true] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
uniq?	boolean	false	Wether or not to count unique values only
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	atom		The field to aggregate. Defaults to the first field in the primary key of the resource
filter	`any`	[]	A filter to apply to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.exists ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` exists :has_ticket, :assigned_tickets ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	`any`	[]	A filter to apply to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.first ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` first :first_assigned_ticket_subject, :assigned_tickets, :subject do filter [active: true] sort [:subject] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
field	atom		The field to aggregate. Defaults to the first field in the primary key of the resource

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	`any`	[]	A filter to apply to the aggregate
sort	`any`		A sort to be applied to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.sum ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` sum :assigned_ticket_price_sum, :assigned_tickets, :price do filter [active: true] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
field	atom		The field to aggregate. Defaults to the first field in the primary key of the resource

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	`any`	[]	A filter to apply to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.list ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` list :assigned_ticket_prices, :assigned_tickets, :price do filter [active: true] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
field	atom		The field to aggregate. Defaults to the first field in the primary key of the resource

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
uniq?	boolean	false	Wether or not to count unique values only
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	`any`	[]	A filter to apply to the aggregate
sort	`any`		A sort to be applied to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.max ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` max :first_assigned_ticket_subject, :assigned_tickets, :severity do filter [active: true] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
field	atom		The field to aggregate. Defaults to the first field in the primary key of the resource

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	`any`	[]	A filter to apply to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.min ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` min :first_assigned_ticket_subject, :assigned_tickets, :severity do filter [active: true] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
field	atom		The field to aggregate. Defaults to the first field in the primary key of the resource

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	`any`	[]	A filter to apply to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.avg ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` avg :assigned_ticket_price_sum, :assigned_tickets, :price do filter [active: true] end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
field	atom		The field to aggregate. Defaults to the first field in the primary key of the resource

### Options

Name	Type	Default	Docs
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	`any`	[]	A filter to apply to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### Introspection Target: `Ash.Resource.Aggregate` ## aggregates.custom ```elixir 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](/documentation/topics/aggregates.md) for more. ### Examples ``` custom :author_names, :authors, :string do implementation {StringAgg, delimiter: ","} end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field to place the aggregate in
relationship_path *	list(atom) | atom		The relationship or relationship path to use for the aggregate
type *	module		The type of the value returned by the aggregate

### Options

Name	Type	Default	Docs
implementation *	module		The module that implements the relevant data layer callbacks
kind *	:count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module}		The kind of the aggregate
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	atom		The field to aggregate. Defaults to the first field in the primary key of the resource
filter	`any`	[]	A filter to apply to the aggregate
sort	`any`		A sort to be applied to the aggregate
description	String.t		An optional description for the aggregate
default	`any`		A default value to use in cases where nil would be used. Count defaults to `0`.
private?	boolean	false	Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
filterable?	boolean | :simple_equality	true	Whether or not the aggregate should be usable in filters.
authorize?	boolean	true	Wether 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.

### 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](/documentation/topics/calculations.md) for more. ### Nested DSLs * [calculate](#calculations-calculate) * argument ### Examples ``` calculations do calculate :full_name, :string, MyApp.MyResource.FullName end ``` ## calculations.calculate ```elixir calculate name, type, calculation \ nil ``` Declares a named calculation on the resource. Takes a module that must adopt the `Ash.Calculation` behaviour. See that module for more information. To ensure that the necessary fields are selected: 1.) Specifying the `select` option on a calculation in the resource. 2.) Define a `select/2` callback in the calculation module 3.) Set `always_select?` on the attribute in question See the [calculations guide](/documentation/topics/calculations.md) for more. ### Nested DSLs * [argument](#calculations-calculate-argument) ### Examples `Ash.Calculation` implementation example: ``` calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}, select: [:first_name, :last_name] ``` `expr/1` example: ``` calculate :full_name, :string, expr(first_name <> " " <> last_name) ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The field name to use for the calculation value
type *	`any`		The type of the calculation. See `Ash.Type` for more.
calculation *	(any, any -> any) | module | `any`		The `module`, `{module, opts}` or `expr(...)` to use for the calculation. Also accepts a function that takes *a single record* and produces the result.

### Options

Name	Type	Default	Docs
constraints	Keyword.t	[]	Constraints to provide to the type. See `Ash.Type` for more.
description	String.t		An optional description for the calculation
private?	boolean	false	Whether or not the calculation will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more.
select	list(atom)	[]	A list of fields to ensure selected if the calculation is used.
load	`any`	[]	A load statement to be applied if the calculation is used.
allow_nil?	boolean	true	Whether or not the calculation can return nil.
filterable?	boolean | :simple_equality	true	Whether or not the calculation should be usable in filters.

## calculations.calculate.argument ```elixir argument name, type ``` An argument to be passed into the calculation's arguments map See the [calculations guide](/documentation/topics/calculations.md) for more. ### Examples ``` argument :params, :map do default %{} end ``` ``` argument :retries, :integer do allow_nil? false end ``` ### Arguments

Name	Type	Default	Docs
name *	atom		The name of the argument
type *	module		The type of the argument. See `Ash.Type` for more.

### Options

Name	Type	Default	Docs
default	(-> any) | mfa | any()		A default value to use for the argument if not provided
allow_nil?	boolean	true	Whether or not the argument value may be nil (or may be not provided)
allow_expr?	boolean	false	Allow passing expressions as argument values. Expressions cannot be type validated.
constraints	Keyword.t	[]	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](/documentation/topics/multitenancy.md) ### Examples ``` multitenancy do strategy :attribute attribute :organization_id global? true end ``` ### Options

Name	Type	Default	Docs
strategy	:context | :attribute	:context	Determine if multitenancy is performed with attribute filters or using data layer features.
attribute	atom		If using the `attribute` strategy, the attribute to use, e.g `org_id`
global?	boolean	false	Whether or not the data also exists outside of each tenant.
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