| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
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. |
| `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. |
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. |
| `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. |
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 <relationship_name>_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. |
| `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. |
| `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. |
| `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 <name>_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. |
# 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. |
| `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. |
| `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. |
| `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_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. |
| `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. |
| `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. |
| `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. |
| `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. |
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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
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. |
| `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. |
| `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.
| `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. |
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.
| `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. |
| `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. |
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`* | ``any`` | | 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 |
| `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. |
| `on` | ``any`` | `[: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. |
| `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. |
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. |
| `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. |
| `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` | ``any`` | `[: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. |
| `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 |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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 |