DSL-Ash.Resource.md

<!--
This file was generated by Spark. Do not edit it by hand.
-->
# Ash.Resource



## 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)
 * [uuid_v7_primary_key](#attributes-uuid_v7_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`](#attributes-attribute-name){: #attributes-attribute-name .spark-required} | `atom` |  | The name of the attribute. |
| [`type`](#attributes-attribute-type){: #attributes-attribute-type .spark-required} | `module` |  | The type of the attribute. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Attribute`

### attributes.create_timestamp
```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:

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




### Examples
```
create_timestamp :inserted_at
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#attributes-create_timestamp-name){: #attributes-create_timestamp-name .spark-required} | `atom` |  | The name of the attribute. |






### 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:

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




### Examples
```
update_timestamp :updated_at
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#attributes-update_timestamp-name){: #attributes-update_timestamp-name .spark-required} | `atom` |  | The name of the attribute. |






### 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:

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




### Examples
```
integer_primary_key :id
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#attributes-integer_primary_key-name){: #attributes-integer_primary_key-name .spark-required} | `atom` |  | The name of the attribute. |






### 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:

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




### Examples
```
uuid_primary_key :id
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#attributes-uuid_primary_key-name){: #attributes-uuid_primary_key-name .spark-required} | `atom` |  | The name of the attribute. |






### Introspection

Target: `Ash.Resource.Attribute`

### attributes.uuid_v7_primary_key
```elixir
uuid_v7_primary_key name
```


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

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

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




### Examples
```
uuid_v7_primary_key :id
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#attributes-uuid_v7_primary_key-name){: #attributes-uuid_v7_primary_key-name .spark-required} | `atom` |  | The name of the attribute. |






### Introspection

Target: `Ash.Resource.Attribute`




## relationships
A section for declaring relationships on the resource.

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

See the [relationships guide](/documentation/topics/resources/relationships.md) for more.


### Nested DSLs
 * [has_one](#relationships-has_one)
   * filter
 * [has_many](#relationships-has_many)
   * filter
 * [many_to_many](#relationships-many_to_many)
   * filter
 * [belongs_to](#relationships-belongs_to)
   * filter


### 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. To add a uniqueness constraint, you will need
to add an identity for the foreign key column on the resource which defines
the `belongs_to` side of the relationship. See the
[identities guide](/documentation/topics/resources/identities.md) to learn more.

See the [relationships guide](/documentation/topics/resources/relationships.md) for more.


### Nested DSLs
 * [filter](#relationships-has_one-filter)


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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-has_one-name){: #relationships-has_one-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-has_one-destination){: #relationships-has_one-destination } | `module` |  | The destination resource |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`manual`](#relationships-has_one-manual){: #relationships-has_one-manual } | `(any, any -> any) \| module` |  | A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. Setting this will automatically set `no_attributes?` to `true`. |
| [`no_attributes?`](#relationships-has_one-no_attributes?){: #relationships-has_one-no_attributes? } | `boolean` |  | All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/resources/relationships.md) for more. |
| [`through`](#relationships-has_one-through){: #relationships-has_one-through } | `atom \| list(atom)` |  | A list of relationship names to traverse. The result will be the first record reachable by following the relationships in order. |
| [`allow_nil?`](#relationships-has_one-allow_nil?){: #relationships-has_one-allow_nil? } | `boolean` | `true` | Marks the relationship as required. Has no effect on validations, but can inform extensions that there will always be a related entity. |
| [`from_many?`](#relationships-has_one-from_many?){: #relationships-has_one-from_many? } | `boolean` | `false` | Signal that this relationship is actually a `has_many` where the first record is given via the `sort`. This will allow data layers to properly deduplicate when necessary. |
| [`offset`](#relationships-has_one-offset){: #relationships-has_one-offset } | `non_neg_integer` |  | An offset to skip entries when loading the relationship. Implies `from_many?: true`. |
| [`description`](#relationships-has_one-description){: #relationships-has_one-description } | `String.t` |  | An optional description for the relationship |
| [`destination_attribute`](#relationships-has_one-destination_attribute){: #relationships-has_one-destination_attribute } | `atom` |  | The attribute on the related resource that should match the `source_attribute` configured on this resource. |
| [`validate_destination_attribute?`](#relationships-has_one-validate_destination_attribute?){: #relationships-has_one-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource |
| [`source_attribute`](#relationships-has_one-source_attribute){: #relationships-has_one-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. |
| [`relationship_context`](#relationships-has_one-relationship_context){: #relationships-has_one-relationship_context } | `any` |  | Context to be set on any queries or changesets generated for managing or querying this relationship. |
| [`public?`](#relationships-has_one-public?){: #relationships-has_one-public? } | `boolean` | `false` | Whether or not the relationship will appear in public interfaces |
| [`not_found_message`](#relationships-has_one-not_found_message){: #relationships-has_one-not_found_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. |
| [`writable?`](#relationships-has_one-writable?){: #relationships-has_one-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. |
| [`read_action`](#relationships-has_one-read_action){: #relationships-has_one-read_action } | `atom` |  | The read action on the destination resource to use when loading data and filtering. |
| [`domain`](#relationships-has_one-domain){: #relationships-has_one-domain } | `atom` |  | The domain module to use when working with the related entity. |
| [`filterable?`](#relationships-has_one-filterable?){: #relationships-has_one-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. |
| [`sortable?`](#relationships-has_one-sortable?){: #relationships-has_one-sortable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in sorts. |
| [`sort`](#relationships-has_one-sort){: #relationships-has_one-sort } | `any` |  | A sort statement to be applied when loading the relationship. |
| [`default_sort`](#relationships-has_one-default_sort){: #relationships-has_one-default_sort } | `any` |  | A default sort statement to be applied when loading the relationship. |
| [`could_be_related_at_creation?`](#relationships-has_one-could_be_related_at_creation?){: #relationships-has_one-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. |
| [`violation_message`](#relationships-has_one-violation_message){: #relationships-has_one-violation_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on destroy. |
| [`authorize_read_with`](#relationships-has_one-authorize_read_with){: #relationships-has_one-authorize_read_with } | `:error \| :filter` |  | If set to `:error`, any authorization filter added to the relationship will result in an error if any record matches the filter in the database. |
| [`allow_forbidden_field?`](#relationships-has_one-allow_forbidden_field?){: #relationships-has_one-allow_forbidden_field? } | `boolean` | `false` | If set to `true`, the relationship will be set to `%Ash.ForbiddenField{}` if its query produces a forbidden error. |


### relationships.has_one.filter
```elixir
filter filter
```


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



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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-has_one-filter-filter){: #relationships-has_one-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |






### Introspection

Target: `Ash.Resource.Dsl.Filter`




### 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/resources/relationships.md) for more.


### Nested DSLs
 * [filter](#relationships-has_many-filter)


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

```

```
# Through relationship - traverse a path of existing relationships
has_many :linked_posts, Post do
  through [:post_links, :destination]
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-has_many-name){: #relationships-has_many-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-has_many-destination){: #relationships-has_many-destination } | `module` |  | The destination resource |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`manual`](#relationships-has_many-manual){: #relationships-has_many-manual } | `(any, any -> any) \| module` |  | A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. Setting this will automatically set `no_attributes?` to `true`. |
| [`no_attributes?`](#relationships-has_many-no_attributes?){: #relationships-has_many-no_attributes? } | `boolean` |  | All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/resources/relationships.md) for more. |
| [`through`](#relationships-has_many-through){: #relationships-has_many-through } | `atom \| list(atom)` |  | A list of relationship names to traverse. The result will be all records reachable by following the relationships in order. For example, `through: [:classrooms, :teachers]` would load all teachers from all classrooms. |
| [`limit`](#relationships-has_many-limit){: #relationships-has_many-limit } | `integer` |  | An integer to limit entries from loaded relationship. |
| [`offset`](#relationships-has_many-offset){: #relationships-has_many-offset } | `non_neg_integer` |  | An offset to skip entries when loading the relationship. |
| [`description`](#relationships-has_many-description){: #relationships-has_many-description } | `String.t` |  | An optional description for the relationship |
| [`destination_attribute`](#relationships-has_many-destination_attribute){: #relationships-has_many-destination_attribute } | `atom` |  | The attribute on the related resource that should match the `source_attribute` configured on this resource. |
| [`validate_destination_attribute?`](#relationships-has_many-validate_destination_attribute?){: #relationships-has_many-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource |
| [`source_attribute`](#relationships-has_many-source_attribute){: #relationships-has_many-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. |
| [`relationship_context`](#relationships-has_many-relationship_context){: #relationships-has_many-relationship_context } | `any` |  | Context to be set on any queries or changesets generated for managing or querying this relationship. |
| [`public?`](#relationships-has_many-public?){: #relationships-has_many-public? } | `boolean` | `false` | Whether or not the relationship will appear in public interfaces |
| [`not_found_message`](#relationships-has_many-not_found_message){: #relationships-has_many-not_found_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. |
| [`writable?`](#relationships-has_many-writable?){: #relationships-has_many-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. |
| [`read_action`](#relationships-has_many-read_action){: #relationships-has_many-read_action } | `atom` |  | The read action on the destination resource to use when loading data and filtering. |
| [`domain`](#relationships-has_many-domain){: #relationships-has_many-domain } | `atom` |  | The domain module to use when working with the related entity. |
| [`filterable?`](#relationships-has_many-filterable?){: #relationships-has_many-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. |
| [`sortable?`](#relationships-has_many-sortable?){: #relationships-has_many-sortable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in sorts. |
| [`sort`](#relationships-has_many-sort){: #relationships-has_many-sort } | `any` |  | A sort statement to be applied when loading the relationship. |
| [`default_sort`](#relationships-has_many-default_sort){: #relationships-has_many-default_sort } | `any` |  | A default sort statement to be applied when loading the relationship. |
| [`could_be_related_at_creation?`](#relationships-has_many-could_be_related_at_creation?){: #relationships-has_many-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. |
| [`violation_message`](#relationships-has_many-violation_message){: #relationships-has_many-violation_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on destroy. |
| [`authorize_read_with`](#relationships-has_many-authorize_read_with){: #relationships-has_many-authorize_read_with } | `:error \| :filter` |  | If set to `:error`, any authorization filter added to the relationship will result in an error if any record matches the filter in the database. |
| [`allow_forbidden_field?`](#relationships-has_many-allow_forbidden_field?){: #relationships-has_many-allow_forbidden_field? } | `boolean` | `false` | If set to `true`, the relationship will be set to `%Ash.ForbiddenField{}` if its query produces a forbidden error. |


### relationships.has_many.filter
```elixir
filter filter
```


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



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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-has_many-filter-filter){: #relationships-has_many-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |






### Introspection

Target: `Ash.Resource.Dsl.Filter`




### 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/resources/relationships.md) for more.


### Nested DSLs
 * [filter](#relationships-many_to_many-filter)


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

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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-many_to_many-name){: #relationships-many_to_many-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-many_to_many-destination){: #relationships-many_to_many-destination } | `module` |  | The destination resource |
### Options

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


### relationships.many_to_many.filter
```elixir
filter filter
```


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



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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-many_to_many-filter-filter){: #relationships-many_to_many-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |






### Introspection

Target: `Ash.Resource.Dsl.Filter`




### 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/resources/relationships.md) for more.


### Nested DSLs
 * [filter](#relationships-belongs_to-filter)


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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-belongs_to-name){: #relationships-belongs_to-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-belongs_to-destination){: #relationships-belongs_to-destination } | `module` |  | The destination resource |
### Options

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


### relationships.belongs_to.filter
```elixir
filter filter
```


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



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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-belongs_to-filter-filter){: #relationships-belongs_to-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |






### Introspection

Target: `Ash.Resource.Dsl.Filter`




### Introspection

Target: `Ash.Resource.Relationships.BelongsTo`




## actions
A section for declaring resource actions.

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


### Nested DSLs
 * [action](#actions-action)
   * argument
   * prepare
   * validate
   * pipe_through
 * [create](#actions-create)
   * change
   * validate
   * pipe_through
   * argument
   * metadata
 * [read](#actions-read)
   * argument
   * prepare
   * validate
   * pipe_through
   * pagination
   * metadata
   * filter
 * [update](#actions-update)
   * change
   * validate
   * pipe_through
   * metadata
   * argument
 * [destroy](#actions-destroy)
   * change
   * validate
   * pipe_through
   * metadata
   * argument


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

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

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

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

```




### Options

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



### actions.action
```elixir
action name, returns \\ nil
```


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

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


### Nested DSLs
 * [argument](#actions-action-argument)
 * [prepare](#actions-action-prepare)
 * [validate](#actions-action-validate)
 * [pipe_through](#actions-action-pipe_through)


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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-action-name){: #actions-action-name .spark-required} | `atom` |  | The name of the action |
| [`returns`](#actions-action-returns){: #actions-action-returns } | `module` |  | The return type of the action. See `Ash.Type` for more. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`constraints`](#actions-action-constraints){: #actions-action-constraints } | `keyword` |  | Constraints for the return type. See `Ash.Type` for more. |
| [`allow_nil?`](#actions-action-allow_nil?){: #actions-action-allow_nil? } | `boolean` | `false` | Whether or not the action can return nil. Unlike attributes & arguments, this defaults to `false`. |
| [`run`](#actions-action-run){: #actions-action-run } | `(any, any -> any) \| module \| module` |  | Module may be an `Ash.Resource.Actions.Implementation` or `Reactor`. |
| [`primary?`](#actions-action-primary?){: #actions-action-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. |
| [`description`](#actions-action-description){: #actions-action-description } | `String.t` |  | An optional description for the action |
| [`transaction?`](#actions-action-transaction?){: #actions-action-transaction? } | `boolean` |  | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
| [`touches_resources`](#actions-action-touches_resources){: #actions-action-touches_resources } | `list(atom)` |  | A list of resources that the action may touch, used when building transactions. |
| [`skip_unknown_inputs`](#actions-action-skip_unknown_inputs){: #actions-action-skip_unknown_inputs } | `atom \| String.t \| list(atom \| String.t)` | `[]` | A list of unknown fields to skip, or `:*` to skip all unknown fields. |
| [`public?`](#actions-action-public?){: #actions-action-public? } | `boolean` | `true` | Whether the action is part of the resource's public API. When `false`, the action is internal-only and must not be exposed by API extensions (e.g. AshGraphql, AshJsonApi). Use `bypass private_action?() do authorize_if always() end` in policies to allow internal callers. Defaults to `true`. |


### actions.action.argument
```elixir
argument name, type
```


Declares an argument on the action




### Examples
```
argument :password_confirmation, :string
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-action-argument-name){: #actions-action-argument-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#actions-action-argument-type){: #actions-action-argument-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Argument`

### actions.action.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`](#actions-action-prepare-preparation){: #actions-action-prepare-preparation .spark-required} | `(any, any -> any) \| module` |  | The module and options for a preparation. Also accepts functions take the query and the context. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`on`](#actions-action-prepare-on){: #actions-action-prepare-on } | `:read \| :action \| :create \| :update \| :destroy \| list(:read \| :action \| :create \| :update \| :destroy)` | `[:read]` | The action types the preparation should run on. By default, preparations only run on read actions. Use `:action` to run on generic actions. |
| [`where`](#actions-action-prepare-where){: #actions-action-prepare-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that should pass in order for this preparation to apply. Any of these validations failing will result in this preparation being ignored. |
| [`only_when_valid?`](#actions-action-prepare-only_when_valid?){: #actions-action-prepare-only_when_valid? } | `boolean` | `false` | If the preparation should only run on valid queries. |





### Introspection

Target: `Ash.Resource.Preparation`

### actions.action.validate
```elixir
validate validation
```


Declares a validation for creates and updates.

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




### Examples
```
validate {Mod, [foo: :bar]}
```

```
validate present([:first_name, :last_name], at_least: 1)
```



### Arguments

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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-action-validate-where){: #actions-action-validate-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. |
| [`only_when_valid?`](#actions-action-validate-only_when_valid?){: #actions-action-validate-only_when_valid? } | `boolean` | `false` | If the validation should only run on valid changesets. Useful for expensive validations or validations that depend on valid data. |
| [`message`](#actions-action-validate-message){: #actions-action-validate-message } | `String.t` |  | If provided, overrides any message set by the validation error |
| [`description`](#actions-action-validate-description){: #actions-action-validate-description } | `String.t` |  | An optional description for the validation |
| [`before_action?`](#actions-action-validate-before_action?){: #actions-action-validate-before_action? } | `boolean` | `false` | If set to `true`, the validation will be run in a before_action hook |





### Introspection

Target: `Ash.Resource.Validation`

### actions.action.pipe_through
```elixir
pipe_through names
```


References one or more pipelines to apply to this action.
Pipeline entities are prepended before the action's own changes/preparations.




### Examples
```
pipe_through [:change_state]

```

```
pipe_through [:change_state], where: attribute_equals(:role, :super_user)

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`names`](#actions-action-pipe_through-names){: #actions-action-pipe_through-names .spark-required} | `atom \| list(atom)` |  | The pipeline name(s) to pipe through. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-action-pipe_through-where){: #actions-action-pipe_through-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that must pass for this pipeline to apply. If any fail, the pipeline's entities are skipped. |





### Introspection

Target: `Ash.Resource.Actions.PipeThrough`




### Introspection

Target: `Ash.Resource.Actions.Action`

### actions.create
```elixir
create name
```


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


### Nested DSLs
 * [change](#actions-create-change)
 * [validate](#actions-create-validate)
 * [pipe_through](#actions-create-pipe_through)
 * [argument](#actions-create-argument)
 * [metadata](#actions-create-metadata)


### Examples
```
create :register do
  primary? true
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-create-name){: #actions-create-name .spark-required} | `atom` |  | The name of the action |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`manual`](#actions-create-manual){: #actions-create-manual } | `(any, any -> any) \| module` |  | Override the creation behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
| [`upsert?`](#actions-create-upsert?){: #actions-create-upsert? } | `boolean` | `false` | Forces all uses of this action to be treated as an upsert. |
| [`upsert_identity`](#actions-create-upsert_identity){: #actions-create-upsert_identity } | `atom` |  | The identity to use for the upsert. Cannot be overridden by the caller. Ignored  if `upsert?` is not set to `true`. |
| [`upsert_fields`](#actions-create-upsert_fields){: #actions-create-upsert_fields } | `:replace_all \| {:replace, atom \| list(atom)} \| {:replace_all_except, atom \| list(atom)} \| atom \| list(atom)` |  | The fields to overwrite in the case of an upsert. If not provided, all fields except for fields set by defaults will be overwritten. |
| [`upsert_condition`](#actions-create-upsert_condition){: #actions-create-upsert_condition } | `any` |  | An expression to check if the record should be updated when there's a conflict. |
| [`return_skipped_upsert?`](#actions-create-return_skipped_upsert?){: #actions-create-return_skipped_upsert? } | `boolean` |  | Returns the record that would have been upserted against but was skipped due to a filter or no fields being changed. How this works depends on the data layer. Keep in mind that read policies *are not applied* to the read of the record in question. |
| [`multitenancy`](#actions-create-multitenancy){: #actions-create-multitenancy } | `:enforce \| :allow_global \| :bypass \| :bypass_all` | `:enforce` | This setting defines how this action handles multitenancy. `:enforce` requires a tenant to be set (the default behavior), `:allow_global` allows using this action both with and without a tenant, `:bypass` completely ignores the tenant even if it's set, `:bypass_all` like `:bypass` but also bypasses the tenancy requirement for the nested resources. |
| [`primary?`](#actions-create-primary?){: #actions-create-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. |
| [`description`](#actions-create-description){: #actions-create-description } | `String.t` |  | An optional description for the action |
| [`transaction?`](#actions-create-transaction?){: #actions-create-transaction? } | `boolean` |  | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
| [`touches_resources`](#actions-create-touches_resources){: #actions-create-touches_resources } | `list(atom)` |  | A list of resources that the action may touch, used when building transactions. |
| [`skip_unknown_inputs`](#actions-create-skip_unknown_inputs){: #actions-create-skip_unknown_inputs } | `atom \| String.t \| list(atom \| String.t)` | `[]` | A list of unknown fields to skip, or `:*` to skip all unknown fields. |
| [`public?`](#actions-create-public?){: #actions-create-public? } | `boolean` | `true` | Whether the action is part of the resource's public API. When `false`, the action is internal-only and must not be exposed by API extensions (e.g. AshGraphql, AshJsonApi). Use `bypass private_action?() do authorize_if always() end` in policies to allow internal callers. Defaults to `true`. |
| [`accept`](#actions-create-accept){: #actions-create-accept } | `atom \| list(atom) \| :*` |  | The list of attributes to accept. Use `:*` to accept all public attributes. |
| [`action_select`](#actions-create-action_select){: #actions-create-action_select } | `list(atom)` |  | A list of attributes to select from the data layer result. Controls which attributes are present (vs %Ash.NotLoaded{}) on the record passed to after_action hooks, notifiers, and returned to the caller. Defaults to all attributes with select_by_default? true. Does not affect what's available to changes or validations. |
| [`require_attributes`](#actions-create-require_attributes){: #actions-create-require_attributes } | `list(atom)` |  | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? |
| [`allow_nil_input`](#actions-create-allow_nil_input){: #actions-create-allow_nil_input } | `list(atom)` |  | A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the data layer step. |
| [`delay_global_validations?`](#actions-create-delay_global_validations?){: #actions-create-delay_global_validations? } | `boolean` | `false` | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. |
| [`skip_global_validations?`](#actions-create-skip_global_validations?){: #actions-create-skip_global_validations? } | `boolean` | `false` | If true, global validations will be skipped. Useful for manual actions. |
| [`error_handler`](#actions-create-error_handler){: #actions-create-error_handler } | `mfa \| (any, any -> any)` |  | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more |
| [`notifiers`](#actions-create-notifiers){: #actions-create-notifiers } | `list(module)` |  | Notifiers that will be called specifically for this action. |
| [`manual?`](#actions-create-manual?){: #actions-create-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`](#actions-create-change-change){: #actions-create-change-change .spark-required} | `(any, any -> any) \| module` |  | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
### Options

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





### Introspection

Target: `Ash.Resource.Change`

### actions.create.validate
```elixir
validate validation
```


Declares a validation to be applied to the changeset.

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




### Examples
```
validate changing(:email)
```



### Arguments

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

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





### Introspection

Target: `Ash.Resource.Validation`

### actions.create.pipe_through
```elixir
pipe_through names
```


References one or more pipelines to apply to this action.
Pipeline entities are prepended before the action's own changes/preparations.




### Examples
```
pipe_through [:change_state]

```

```
pipe_through [:change_state], where: attribute_equals(:role, :super_user)

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`names`](#actions-create-pipe_through-names){: #actions-create-pipe_through-names .spark-required} | `atom \| list(atom)` |  | The pipeline name(s) to pipe through. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-create-pipe_through-where){: #actions-create-pipe_through-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that must pass for this pipeline to apply. If any fail, the pipeline's entities are skipped. |





### Introspection

Target: `Ash.Resource.Actions.PipeThrough`

### actions.create.argument
```elixir
argument name, type
```


Declares an argument on the action




### Examples
```
argument :password_confirmation, :string
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-create-argument-name){: #actions-create-argument-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#actions-create-argument-type){: #actions-create-argument-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Argument`

### actions.create.metadata
```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 after_action hook via `Ash.Resource.put_metadata/3`.




### Examples
```
metadata :api_token, :string, allow_nil?: false

```

```
metadata :operation_id, :string, allow_nil?: false

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-create-metadata-name){: #actions-create-metadata-name .spark-required} | `atom` |  | The name of the metadata |
| [`type`](#actions-create-metadata-type){: #actions-create-metadata-type .spark-required} | `any` |  | The type of the metadata. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Metadata`




### Introspection

Target: `Ash.Resource.Actions.Create`

### actions.read
```elixir
read name
```


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


### Nested DSLs
 * [argument](#actions-read-argument)
 * [prepare](#actions-read-prepare)
 * [validate](#actions-read-validate)
 * [pipe_through](#actions-read-pipe_through)
 * [pagination](#actions-read-pagination)
 * [metadata](#actions-read-metadata)
 * [filter](#actions-read-filter)


### Examples
```
read :read_all do
  primary? true
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-read-name){: #actions-read-name .spark-required} | `atom` |  | The name of the action |
### Options

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


### actions.read.argument
```elixir
argument name, type
```


Declares an argument on the action




### Examples
```
argument :password_confirmation, :string
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-read-argument-name){: #actions-read-argument-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#actions-read-argument-type){: #actions-read-argument-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Argument`

### actions.read.prepare
```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`](#actions-read-prepare-preparation){: #actions-read-prepare-preparation .spark-required} | `(any, any -> any) \| module` |  | The module and options for a preparation. Also accepts functions take the query and the context. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`on`](#actions-read-prepare-on){: #actions-read-prepare-on } | `:read \| :action \| :create \| :update \| :destroy \| list(:read \| :action \| :create \| :update \| :destroy)` | `[:read]` | The action types the preparation should run on. By default, preparations only run on read actions. Use `:action` to run on generic actions. |
| [`where`](#actions-read-prepare-where){: #actions-read-prepare-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that should pass in order for this preparation to apply. Any of these validations failing will result in this preparation being ignored. |
| [`only_when_valid?`](#actions-read-prepare-only_when_valid?){: #actions-read-prepare-only_when_valid? } | `boolean` | `false` | If the preparation should only run on valid queries. |





### Introspection

Target: `Ash.Resource.Preparation`

### actions.read.validate
```elixir
validate validation
```


Declares a validation for creates and updates.

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




### Examples
```
validate {Mod, [foo: :bar]}
```

```
validate present([:first_name, :last_name], at_least: 1)
```



### Arguments

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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-read-validate-where){: #actions-read-validate-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. |
| [`only_when_valid?`](#actions-read-validate-only_when_valid?){: #actions-read-validate-only_when_valid? } | `boolean` | `false` | If the validation should only run on valid changesets. Useful for expensive validations or validations that depend on valid data. |
| [`message`](#actions-read-validate-message){: #actions-read-validate-message } | `String.t` |  | If provided, overrides any message set by the validation error |
| [`description`](#actions-read-validate-description){: #actions-read-validate-description } | `String.t` |  | An optional description for the validation |
| [`before_action?`](#actions-read-validate-before_action?){: #actions-read-validate-before_action? } | `boolean` | `false` | If set to `true`, the validation will be run in a before_action hook |





### Introspection

Target: `Ash.Resource.Validation`

### actions.read.pipe_through
```elixir
pipe_through names
```


References one or more pipelines to apply to this action.
Pipeline entities are prepended before the action's own changes/preparations.




### Examples
```
pipe_through [:change_state]

```

```
pipe_through [:change_state], where: attribute_equals(:role, :super_user)

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`names`](#actions-read-pipe_through-names){: #actions-read-pipe_through-names .spark-required} | `atom \| list(atom)` |  | The pipeline name(s) to pipe through. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-read-pipe_through-where){: #actions-read-pipe_through-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that must pass for this pipeline to apply. If any fail, the pipeline's entities are skipped. |





### Introspection

Target: `Ash.Resource.Actions.PipeThrough`

### actions.read.pagination


Adds pagination options to a resource







### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`keyset?`](#actions-read-pagination-keyset?){: #actions-read-pagination-keyset? } | `boolean` | `false` | Whether or not keyset based pagination is supported |
| [`offset?`](#actions-read-pagination-offset?){: #actions-read-pagination-offset? } | `boolean` | `false` | Whether or not offset based pagination is supported |
| [`default_limit`](#actions-read-pagination-default_limit){: #actions-read-pagination-default_limit } | `pos_integer` |  | The default page size to apply, if one is not supplied |
| [`countable`](#actions-read-pagination-countable){: #actions-read-pagination-countable } | `true \| false \| :by_default` | `true` | Whether not a returned page will have a full count of all records. Use `:by_default` to do it automatically. |
| [`max_page_size`](#actions-read-pagination-max_page_size){: #actions-read-pagination-max_page_size } | `pos_integer` | `250` | The maximum amount of records that can be requested in a single page |
| [`stable_sort`](#actions-read-pagination-stable_sort){: #actions-read-pagination-stable_sort } | `any` |  | A stable sort statement to add to a query (after any existing sorts). Only added if the sort does not already contain a stable sort (sorting on fields that uniquely identify a record). Defaults to the primary key. |
| [`required?`](#actions-read-pagination-required?){: #actions-read-pagination-required? } | `boolean` | `true` | Whether or not pagination can be disabled (by passing `page: false` to `Ash.Api.read!/2`, or by having `required?: false, default_limit: nil` set). Only relevant if some pagination configuration is supplied. |
| [`paginate_by_default?`](#actions-read-pagination-paginate_by_default?){: #actions-read-pagination-paginate_by_default? } | `boolean` | `false` | Whether or not to paginate by default when pagination is not required and no page parameters are provided. |





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




### Examples
```
metadata :api_token, :string, allow_nil?: false

```

```
metadata :operation_id, :string, allow_nil?: false

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-read-metadata-name){: #actions-read-metadata-name .spark-required} | `atom` |  | The name of the metadata |
| [`type`](#actions-read-metadata-type){: #actions-read-metadata-type .spark-required} | `any` |  | The type of the metadata. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Metadata`

### actions.read.filter
```elixir
filter filter
```


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



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

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#actions-read-filter-filter){: #actions-read-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |






### Introspection

Target: `Ash.Resource.Dsl.Filter`




### Introspection

Target: `Ash.Resource.Actions.Read`

### actions.update
```elixir
update name
```


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


### Nested DSLs
 * [change](#actions-update-change)
 * [validate](#actions-update-validate)
 * [pipe_through](#actions-update-pipe_through)
 * [metadata](#actions-update-metadata)
 * [argument](#actions-update-argument)


### Examples
```
update :flag_for_review, primary?: true
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-update-name){: #actions-update-name .spark-required} | `atom` |  | The name of the action |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`manual`](#actions-update-manual){: #actions-update-manual } | `(any, any -> any) \| module` |  | Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
| [`require_atomic?`](#actions-update-require_atomic?){: #actions-update-require_atomic? } | `boolean` | `true` | Require that the update be atomic. This means that all changes and validations implement the `atomic` callback. See the guide on atomic updates for more. |
| [`atomic_upgrade?`](#actions-update-atomic_upgrade?){: #actions-update-atomic_upgrade? } | `boolean` | `false` | If set to `true`, atomic upgrades will be performed. Ignored if `required_atomic?` is `true`. See the update actions guide for more. |
| [`atomic_upgrade_with`](#actions-update-atomic_upgrade_with){: #actions-update-atomic_upgrade_with } | `atom \| nil` |  | Configure the read action used when performing atomic upgrades. Defaults to the primary read action. |
| [`multitenancy`](#actions-update-multitenancy){: #actions-update-multitenancy } | `:enforce \| :allow_global \| :bypass \| :bypass_all` | `:enforce` | This setting defines how this action handles multitenancy. `:enforce` requires a tenant to be set (the default behavior), `:allow_global` allows using this action both with and without a tenant, `:bypass` completely ignores the tenant even if it's set, `:bypass_all` like `:bypass` but also bypasses the tenancy requirement for the nested resources. |
| [`primary?`](#actions-update-primary?){: #actions-update-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. |
| [`description`](#actions-update-description){: #actions-update-description } | `String.t` |  | An optional description for the action |
| [`transaction?`](#actions-update-transaction?){: #actions-update-transaction? } | `boolean` |  | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
| [`touches_resources`](#actions-update-touches_resources){: #actions-update-touches_resources } | `list(atom)` |  | A list of resources that the action may touch, used when building transactions. |
| [`skip_unknown_inputs`](#actions-update-skip_unknown_inputs){: #actions-update-skip_unknown_inputs } | `atom \| String.t \| list(atom \| String.t)` | `[]` | A list of unknown fields to skip, or `:*` to skip all unknown fields. |
| [`public?`](#actions-update-public?){: #actions-update-public? } | `boolean` | `true` | Whether the action is part of the resource's public API. When `false`, the action is internal-only and must not be exposed by API extensions (e.g. AshGraphql, AshJsonApi). Use `bypass private_action?() do authorize_if always() end` in policies to allow internal callers. Defaults to `true`. |
| [`accept`](#actions-update-accept){: #actions-update-accept } | `atom \| list(atom) \| :*` |  | The list of attributes to accept. Use `:*` to accept all public attributes. |
| [`action_select`](#actions-update-action_select){: #actions-update-action_select } | `list(atom)` |  | A list of attributes to select from the data layer result. Controls which attributes are present (vs %Ash.NotLoaded{}) on the record passed to after_action hooks, notifiers, and returned to the caller. Defaults to all attributes with select_by_default? true. Does not affect what's available to changes or validations. |
| [`require_attributes`](#actions-update-require_attributes){: #actions-update-require_attributes } | `list(atom)` |  | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? |
| [`allow_nil_input`](#actions-update-allow_nil_input){: #actions-update-allow_nil_input } | `list(atom)` |  | A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the data layer step. |
| [`delay_global_validations?`](#actions-update-delay_global_validations?){: #actions-update-delay_global_validations? } | `boolean` | `false` | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. |
| [`skip_global_validations?`](#actions-update-skip_global_validations?){: #actions-update-skip_global_validations? } | `boolean` | `false` | If true, global validations will be skipped. Useful for manual actions. |
| [`error_handler`](#actions-update-error_handler){: #actions-update-error_handler } | `mfa \| (any, any -> any)` |  | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more |
| [`notifiers`](#actions-update-notifiers){: #actions-update-notifiers } | `list(module)` |  | Notifiers that will be called specifically for this action. |
| [`manual?`](#actions-update-manual?){: #actions-update-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`](#actions-update-change-change){: #actions-update-change-change .spark-required} | `(any, any -> any) \| module` |  | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
### Options

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





### Introspection

Target: `Ash.Resource.Change`

### actions.update.validate
```elixir
validate validation
```


Declares a validation to be applied to the changeset.

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




### Examples
```
validate changing(:email)
```



### Arguments

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

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





### Introspection

Target: `Ash.Resource.Validation`

### actions.update.pipe_through
```elixir
pipe_through names
```


References one or more pipelines to apply to this action.
Pipeline entities are prepended before the action's own changes/preparations.




### Examples
```
pipe_through [:change_state]

```

```
pipe_through [:change_state], where: attribute_equals(:role, :super_user)

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`names`](#actions-update-pipe_through-names){: #actions-update-pipe_through-names .spark-required} | `atom \| list(atom)` |  | The pipeline name(s) to pipe through. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-update-pipe_through-where){: #actions-update-pipe_through-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that must pass for this pipeline to apply. If any fail, the pipeline's entities are skipped. |





### Introspection

Target: `Ash.Resource.Actions.PipeThrough`

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




### Examples
```
metadata :api_token, :string, allow_nil?: false

```

```
metadata :operation_id, :string, allow_nil?: false

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-update-metadata-name){: #actions-update-metadata-name .spark-required} | `atom` |  | The name of the metadata |
| [`type`](#actions-update-metadata-type){: #actions-update-metadata-type .spark-required} | `any` |  | The type of the metadata. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Metadata`

### actions.update.argument
```elixir
argument name, type
```


Declares an argument on the action




### Examples
```
argument :password_confirmation, :string
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-update-argument-name){: #actions-update-argument-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#actions-update-argument-type){: #actions-update-argument-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Argument`




### Introspection

Target: `Ash.Resource.Actions.Update`

### actions.destroy
```elixir
destroy name
```


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

See `Ash.Resource.Change.Builtins.cascade_destroy/2` for cascading destroy operations.


### Nested DSLs
 * [change](#actions-destroy-change)
 * [validate](#actions-destroy-validate)
 * [pipe_through](#actions-destroy-pipe_through)
 * [metadata](#actions-destroy-metadata)
 * [argument](#actions-destroy-argument)


### Examples
```
destroy :destroy do
  primary? true
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-destroy-name){: #actions-destroy-name .spark-required} | `atom` |  | The name of the action |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`soft?`](#actions-destroy-soft?){: #actions-destroy-soft? } | `boolean` | `false` | If specified, the destroy action behaves as an update internally |
| [`manual`](#actions-destroy-manual){: #actions-destroy-manual } | `(any, any -> any) \| module` |  | Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
| [`multitenancy`](#actions-destroy-multitenancy){: #actions-destroy-multitenancy } | `:enforce \| :allow_global \| :bypass \| :bypass_all` | `:enforce` | This setting defines how this action handles multitenancy. `:enforce` requires a tenant to be set (the default behavior), `:allow_global` allows using this action both with and without a tenant, `:bypass` completely ignores the tenant even if it's set, `:bypass_all` like `:bypass` but also bypasses the tenancy requirement for the nested resources. |
| [`require_atomic?`](#actions-destroy-require_atomic?){: #actions-destroy-require_atomic? } | `boolean` | `true` | Require that the update be atomic. Only relevant if `soft?` is set to `true`. This means that all changes and validations implement the `atomic` callback. See the guide on atomic updates for more. |
| [`atomic_upgrade?`](#actions-destroy-atomic_upgrade?){: #actions-destroy-atomic_upgrade? } | `boolean` | `false` | If set to `true`, atomic upgrades will be performed. See the update actions guide for more. |
| [`atomic_upgrade_with`](#actions-destroy-atomic_upgrade_with){: #actions-destroy-atomic_upgrade_with } | `atom \| nil` |  | Configure the read action used when performing atomic upgrades. Defaults to the primary read action. |
| [`primary?`](#actions-destroy-primary?){: #actions-destroy-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. |
| [`description`](#actions-destroy-description){: #actions-destroy-description } | `String.t` |  | An optional description for the action |
| [`transaction?`](#actions-destroy-transaction?){: #actions-destroy-transaction? } | `boolean` |  | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
| [`touches_resources`](#actions-destroy-touches_resources){: #actions-destroy-touches_resources } | `list(atom)` |  | A list of resources that the action may touch, used when building transactions. |
| [`skip_unknown_inputs`](#actions-destroy-skip_unknown_inputs){: #actions-destroy-skip_unknown_inputs } | `atom \| String.t \| list(atom \| String.t)` | `[]` | A list of unknown fields to skip, or `:*` to skip all unknown fields. |
| [`public?`](#actions-destroy-public?){: #actions-destroy-public? } | `boolean` | `true` | Whether the action is part of the resource's public API. When `false`, the action is internal-only and must not be exposed by API extensions (e.g. AshGraphql, AshJsonApi). Use `bypass private_action?() do authorize_if always() end` in policies to allow internal callers. Defaults to `true`. |
| [`accept`](#actions-destroy-accept){: #actions-destroy-accept } | `atom \| list(atom) \| :*` |  | The list of attributes to accept. Use `:*` to accept all public attributes. |
| [`action_select`](#actions-destroy-action_select){: #actions-destroy-action_select } | `list(atom)` |  | A list of attributes to select from the data layer result. Controls which attributes are present (vs %Ash.NotLoaded{}) on the record passed to after_action hooks, notifiers, and returned to the caller. Defaults to all attributes with select_by_default? true. Does not affect what's available to changes or validations. |
| [`require_attributes`](#actions-destroy-require_attributes){: #actions-destroy-require_attributes } | `list(atom)` |  | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? |
| [`allow_nil_input`](#actions-destroy-allow_nil_input){: #actions-destroy-allow_nil_input } | `list(atom)` |  | A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the data layer step. |
| [`delay_global_validations?`](#actions-destroy-delay_global_validations?){: #actions-destroy-delay_global_validations? } | `boolean` | `false` | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. |
| [`skip_global_validations?`](#actions-destroy-skip_global_validations?){: #actions-destroy-skip_global_validations? } | `boolean` | `false` | If true, global validations will be skipped. Useful for manual actions. |
| [`error_handler`](#actions-destroy-error_handler){: #actions-destroy-error_handler } | `mfa \| (any, any -> any)` |  | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more |
| [`notifiers`](#actions-destroy-notifiers){: #actions-destroy-notifiers } | `list(module)` |  | Notifiers that will be called specifically for this action. |
| [`manual?`](#actions-destroy-manual?){: #actions-destroy-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`](#actions-destroy-change-change){: #actions-destroy-change-change .spark-required} | `(any, any -> any) \| module` |  | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
### Options

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





### Introspection

Target: `Ash.Resource.Change`

### actions.destroy.validate
```elixir
validate validation
```


Declares a validation to be applied to the changeset.

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




### Examples
```
validate changing(:email)
```



### Arguments

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

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





### Introspection

Target: `Ash.Resource.Validation`

### actions.destroy.pipe_through
```elixir
pipe_through names
```


References one or more pipelines to apply to this action.
Pipeline entities are prepended before the action's own changes/preparations.




### Examples
```
pipe_through [:change_state]

```

```
pipe_through [:change_state], where: attribute_equals(:role, :super_user)

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`names`](#actions-destroy-pipe_through-names){: #actions-destroy-pipe_through-names .spark-required} | `atom \| list(atom)` |  | The pipeline name(s) to pipe through. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`where`](#actions-destroy-pipe_through-where){: #actions-destroy-pipe_through-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that must pass for this pipeline to apply. If any fail, the pipeline's entities are skipped. |





### Introspection

Target: `Ash.Resource.Actions.PipeThrough`

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




### Examples
```
metadata :api_token, :string, allow_nil?: false

```

```
metadata :operation_id, :string, allow_nil?: false

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-destroy-metadata-name){: #actions-destroy-metadata-name .spark-required} | `atom` |  | The name of the metadata |
| [`type`](#actions-destroy-metadata-type){: #actions-destroy-metadata-type .spark-required} | `any` |  | The type of the metadata. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Metadata`

### actions.destroy.argument
```elixir
argument name, type
```


Declares an argument on the action




### Examples
```
argument :password_confirmation, :string
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#actions-destroy-argument-name){: #actions-destroy-argument-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#actions-destroy-argument-type){: #actions-destroy-argument-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Actions.Argument`




### Introspection

Target: `Ash.Resource.Actions.Destroy`




## code_interface
Functions that will be defined on the resource. See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.


### Nested DSLs
 * [define](#code_interface-define)
   * custom_input
     * transform
 * [define_calculation](#code_interface-define_calculation)
   * custom_input
     * transform


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

```




### Options

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



### code_interface.define
```elixir
define name
```


Defines a function with the corresponding name and arguments. See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.


### Nested DSLs
 * [custom_input](#code_interface-define-custom_input)
   * transform


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



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#code_interface-define-name){: #code_interface-define-name .spark-required} | `atom` |  | The name of the function that will be defined |
### Options

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


### code_interface.define.custom_input
```elixir
custom_input name, type
```


Define or customize an input to the action.

See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.


### Nested DSLs
 * [transform](#code_interface-define-custom_input-transform)


### Examples
```
custom_input :artist, :struct do
  transform to: :artist_id, using: &(&1.id)

  constraints instance_of: Artist
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#code_interface-define-custom_input-name){: #code_interface-define-custom_input-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#code_interface-define-custom_input-type){: #code_interface-define-custom_input-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`description`](#code_interface-define-custom_input-description){: #code_interface-define-custom_input-description } | `String.t` |  | An optional description for the argument. |
| [`constraints`](#code_interface-define-custom_input-constraints){: #code_interface-define-custom_input-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see `Ash.Type`. |
| [`allow_nil?`](#code_interface-define-custom_input-allow_nil?){: #code_interface-define-custom_input-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. |
| [`sensitive?`](#code_interface-define-custom_input-sensitive?){: #code_interface-define-custom_input-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#code_interface-define-custom_input-default){: #code_interface-define-custom_input-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 |


### code_interface.define.custom_input.transform


A transformation to be applied to the custom input.




### Examples
```
transform do
  to :artist_id
  using &(&1.id)
end

```

```
transform do
  to :points
  using &try_parse_integer/1
end

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`to`](#code_interface-define-custom_input-transform-to){: #code_interface-define-custom_input-transform-to } | `atom` |  | A key to rewrite the argument to. If the custom input is also a required positional argument, then the `to` is automatically added to the `exclude_inputs` list. |
| [`using`](#code_interface-define-custom_input-transform-using){: #code_interface-define-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `value` or `nil` |





### Introspection

Target: `Ash.Resource.Interface.CustomInput.Transform`




### Introspection

Target: `Ash.Resource.Interface.CustomInput`




### 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/resources/code-interfaces.md) for more.


### Nested DSLs
 * [custom_input](#code_interface-define_calculation-custom_input)
   * transform


### Examples
```
define_calculation :referral_link, args: [:id]
```

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



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#code_interface-define_calculation-name){: #code_interface-define_calculation-name .spark-required} | `atom` |  | The name of the function that will be defined |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`calculation`](#code_interface-define_calculation-calculation){: #code_interface-define_calculation-calculation } | `atom` |  | The name of the calculation that will be evaluated. Defaults to the same name as the function. |
| [`exclude_inputs`](#code_interface-define_calculation-exclude_inputs){: #code_interface-define_calculation-exclude_inputs } | `list(atom)` | `[]` | A list of calculation inputs to not accept in the defined interface |
| [`args`](#code_interface-define_calculation-args){: #code_interface-define_calculation-args } | `any` | `[]` | Supply field or argument values referenced by the calculation, in the form of :name, `{:arg, :name}` and/or `{:ref, :name}`. See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more. |


### code_interface.define_calculation.custom_input
```elixir
custom_input name, type
```


Define or customize an input to the action.

See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.


### Nested DSLs
 * [transform](#code_interface-define_calculation-custom_input-transform)


### Examples
```
custom_input :artist, :struct do
  transform to: :artist_id, using: &(&1.id)

  constraints instance_of: Artist
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#code_interface-define_calculation-custom_input-name){: #code_interface-define_calculation-custom_input-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#code_interface-define_calculation-custom_input-type){: #code_interface-define_calculation-custom_input-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`description`](#code_interface-define_calculation-custom_input-description){: #code_interface-define_calculation-custom_input-description } | `String.t` |  | An optional description for the argument. |
| [`constraints`](#code_interface-define_calculation-custom_input-constraints){: #code_interface-define_calculation-custom_input-constraints } | `keyword` | `[]` | Constraints to provide to the type when casting the value. For more information, see `Ash.Type`. |
| [`allow_nil?`](#code_interface-define_calculation-custom_input-allow_nil?){: #code_interface-define_calculation-custom_input-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. |
| [`sensitive?`](#code_interface-define_calculation-custom_input-sensitive?){: #code_interface-define_calculation-custom_input-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII(Personally Identifiable Information). See the [security guide](/documentation/topics/security/sensitive-data.md) for more. |
| [`default`](#code_interface-define_calculation-custom_input-default){: #code_interface-define_calculation-custom_input-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 |


### code_interface.define_calculation.custom_input.transform


A transformation to be applied to the custom input.




### Examples
```
transform do
  to :artist_id
  using &(&1.id)
end

```

```
transform do
  to :points
  using &try_parse_integer/1
end

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`to`](#code_interface-define_calculation-custom_input-transform-to){: #code_interface-define_calculation-custom_input-transform-to } | `atom` |  | A key to rewrite the argument to. If the custom input is also a required positional argument, then the `to` is automatically added to the `exclude_inputs` list. |
| [`using`](#code_interface-define_calculation-custom_input-transform-using){: #code_interface-define_calculation-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `value` or `nil` |





### Introspection

Target: `Ash.Resource.Interface.CustomInput.Transform`




### Introspection

Target: `Ash.Resource.Interface.CustomInput`




### Introspection

Target: `Ash.Resource.CalculationInterface`




## resource
General resource configuration




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

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`description`](#resource-description){: #resource-description } | `String.t` |  | A human readable description of the resource, to be used in generated documentation |
| [`base_filter`](#resource-base_filter){: #resource-base_filter } | `any` |  | A filter statement to be applied to any queries on the resource |
| [`default_context`](#resource-default_context){: #resource-default_context } | `any` |  | Default context to apply to any queries/changesets generated for this resource. |
| [`trace_name`](#resource-trace_name){: #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`](#resource-short_name){: #resource-short_name } | `atom` |  | A short identifier for the resource, which should be unique. See the [monitoring guide](/documentation/topics/monitoring.md) for more. |
| [`inspect_private_fields?`](#resource-inspect_private_fields?){: #resource-inspect_private_fields? } | `boolean` | `true` | Whether to include private fields in the inspect output. `show_inspect_fields` takes precedence over this option. |
| [`hide_inspect_fields`](#resource-hide_inspect_fields){: #resource-hide_inspect_fields } | `list(atom)` | `[]` | A deny-list of fields to hide from the inspect output. Takes precedence over `show_inspect_fields`. |
| [`show_inspect_fields`](#resource-show_inspect_fields){: #resource-show_inspect_fields } | `list(atom)` |  | An allow-list of fields to show in the inspect output. Sensitive fields are _always_ hidden. |
| [`plural_name`](#resource-plural_name){: #resource-plural_name } | `atom` |  | A pluralized version of the resource short_name. May be used by generators or automated tooling. |
| [`atomic_validation_default_target_attribute`](#resource-atomic_validation_default_target_attribute){: #resource-atomic_validation_default_target_attribute } | `atom` |  | Overrides the attribute used when building atomic validation filters. Defaults to the first primary key attribute when not specified. |
| [`require_primary_key?`](#resource-require_primary_key?){: #resource-require_primary_key? } | `boolean` | `true` | Allow the resource to be used without any primary key fields. Warning: this option is experimental, and should not be used unless you know what you're doing. |






## identities
Unique identifiers for the resource


### Nested DSLs
 * [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/resources/identities.md) for more.




### Examples
```
identity :name, [:name]
```

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



### Arguments

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

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





### Introspection

Target: `Ash.Resource.Identity`




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

See `Ash.Resource.Change` for more.


### Nested DSLs
 * [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`](#changes-change-change){: #changes-change-change .spark-required} | `(any, any -> any) \| module` |  | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
### Options

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





### Introspection

Target: `Ash.Resource.Change`




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


### Nested DSLs
 * [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`](#preparations-prepare-preparation){: #preparations-prepare-preparation .spark-required} | `(any, any -> any) \| module` |  | The module and options for a preparation. Also accepts functions take the query and the context. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`on`](#preparations-prepare-on){: #preparations-prepare-on } | `:read \| :action \| :create \| :update \| :destroy \| list(:read \| :action \| :create \| :update \| :destroy)` | `[:read]` | The action types the preparation should run on. By default, preparations only run on read actions. Use `:action` to run on generic actions. |
| [`where`](#preparations-prepare-where){: #preparations-prepare-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that should pass in order for this preparation to apply. Any of these validations failing will result in this preparation being ignored. |
| [`only_when_valid?`](#preparations-prepare-only_when_valid?){: #preparations-prepare-only_when_valid? } | `boolean` | `false` | If the preparation should only run on valid queries. |





### 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 present([:first_name, :last_name], at_least: 1)
end

```




### validations.validate
```elixir
validate validation
```


Declares a validation for creates and updates.

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




### Examples
```
validate {Mod, [foo: :bar]}
```

```
validate present([:first_name, :last_name], at_least: 1)
```



### Arguments

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

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





### Introspection

Target: `Ash.Resource.Validation`




## pipelines
Declare reusable pipelines of changes, validations, and preparations
that can be referenced from multiple actions via `pipe_through`.


### Nested DSLs
 * [pipeline](#pipelines-pipeline)
   * change
   * validate
   * prepare


### Examples
```
pipelines do
  pipeline :change_state do
    validate changing(:state)
    change set_attribute(:score, 0)
  end
end

```




### pipelines.pipeline
```elixir
pipeline name
```


Declares a reusable pipeline of changes, validations, and preparations
that can be referenced from multiple actions via `pipe_through`.


### Nested DSLs
 * [change](#pipelines-pipeline-change)
 * [validate](#pipelines-pipeline-validate)
 * [prepare](#pipelines-pipeline-prepare)


### Examples
```
pipeline :change_state do
  validate changing(:state)
  change set_attribute(:score, 0)
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#pipelines-pipeline-name){: #pipelines-pipeline-name .spark-required} | `atom` |  | The name of the pipeline |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`description`](#pipelines-pipeline-description){: #pipelines-pipeline-description } | `String.t` |  | An optional description for the pipeline |


### pipelines.pipeline.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`](#pipelines-pipeline-change-change){: #pipelines-pipeline-change-change .spark-required} | `(any, any -> any) \| module` |  | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
### Options

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





### Introspection

Target: `Ash.Resource.Change`

### pipelines.pipeline.validate
```elixir
validate validation
```


Declares a validation to be applied to the changeset.

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




### Examples
```
validate changing(:email)
```



### Arguments

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

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





### Introspection

Target: `Ash.Resource.Validation`

### pipelines.pipeline.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`](#pipelines-pipeline-prepare-preparation){: #pipelines-pipeline-prepare-preparation .spark-required} | `(any, any -> any) \| module` |  | The module and options for a preparation. Also accepts functions take the query and the context. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`on`](#pipelines-pipeline-prepare-on){: #pipelines-pipeline-prepare-on } | `:read \| :action \| :create \| :update \| :destroy \| list(:read \| :action \| :create \| :update \| :destroy)` | `[:read]` | The action types the preparation should run on. By default, preparations only run on read actions. Use `:action` to run on generic actions. |
| [`where`](#pipelines-pipeline-prepare-where){: #pipelines-pipeline-prepare-where } | `(any, any -> any) \| module \| list((any, any -> any) \| module)` | `[]` | Validations that should pass in order for this preparation to apply. Any of these validations failing will result in this preparation being ignored. |
| [`only_when_valid?`](#pipelines-pipeline-prepare-only_when_valid?){: #pipelines-pipeline-prepare-only_when_valid? } | `boolean` | `false` | If the preparation should only run on valid queries. |





### Introspection

Target: `Ash.Resource.Preparation`




### Introspection

Target: `Ash.Resource.Pipeline`




## 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/resources/aggregates.md) for more.


### Nested DSLs
 * [count](#aggregates-count)
   * join_filter
 * [exists](#aggregates-exists)
   * join_filter
 * [first](#aggregates-first)
   * join_filter
 * [sum](#aggregates-sum)
   * join_filter
 * [list](#aggregates-list)
   * join_filter
 * [max](#aggregates-max)
   * join_filter
 * [min](#aggregates-min)
   * join_filter
 * [avg](#aggregates-avg)
   * join_filter
 * [custom](#aggregates-custom)
   * join_filter


### 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)

Can aggregate over relationships using a relationship path, or directly over another resource.

See the [aggregates guide](/documentation/topics/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-count-join_filter)


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

```

```
count :matching_profiles_count, Profile do
  filter expr(name == parent(name))
end

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#aggregates-count-name){: #aggregates-count-name .spark-required} | `atom` |  | The field to place the aggregate in |
| [`relationship_path`](#aggregates-count-relationship_path){: #aggregates-count-relationship_path .spark-required} | `list(atom) \| atom` |  | The relationship or relationship path to use for the aggregate, or a resource module for resource-based aggregates |
### Options

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


### aggregates.count.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.exists
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-exists-join_filter)


### Examples
```
exists :has_ticket, :assigned_tickets

```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#aggregates-exists-name){: #aggregates-exists-name .spark-required} | `atom` |  | The field to place the aggregate in |
| [`relationship_path`](#aggregates-exists-relationship_path){: #aggregates-exists-relationship_path .spark-required} | `list(atom) \| atom` |  | The relationship or relationship path to use for the aggregate, or a resource module for resource-based aggregates |
### Options

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


### aggregates.exists.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.first
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-first-join_filter)


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

```



### Arguments

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

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


### aggregates.first.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.sum
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-sum-join_filter)


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

```



### Arguments

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

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


### aggregates.sum.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.list
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-list-join_filter)


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

```



### Arguments

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

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


### aggregates.list.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.max
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-max-join_filter)


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

```



### Arguments

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

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


### aggregates.max.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.min
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-min-join_filter)


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

```



### Arguments

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

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


### aggregates.min.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.avg
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-avg-join_filter)


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

```



### Arguments

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

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


### aggregates.avg.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`

### aggregates.custom
```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/resources/aggregates.md) for more.


### Nested DSLs
 * [join_filter](#aggregates-custom-join_filter)


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

```



### Arguments

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

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


### aggregates.custom.join_filter
```elixir
join_filter relationship_path, filter
```


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




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

```



### Arguments

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






### Introspection

Target: `Ash.Resource.Aggregate.JoinFilter`




### Introspection

Target: `Ash.Resource.Aggregate`




## calculations
Declare named calculations on the resource.

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

See the [calculations guide](/documentation/topics/resources/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.Resource.Calculation` behaviour. See that module
for more information.

To ensure that the necessary fields are loaded:

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

See the [calculations guide](/documentation/topics/resources/calculations.md) for more.


### Nested DSLs
 * [argument](#calculations-calculate-argument)


### Examples
`Ash.Resource.Calculation` implementation example:
```
calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}, load: [:first_name, :last_name]
```

`expr/1` example:
```
calculate :full_name, :string, expr(first_name <> " " <> last_name)
```

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

Example with options in `do` block:
```
calculate :full_name, :string, expr(first_name <> " " <> last_name) do
  allow_nil? false
  public? true
end

```



### Arguments

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

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`async?`](#calculations-calculate-async?){: #calculations-calculate-async? } | `boolean` | `false` |  |
| [`constraints`](#calculations-calculate-constraints){: #calculations-calculate-constraints } | `keyword` | `[]` | Constraints to provide to the type. See `Ash.Type` for more. |
| [`description`](#calculations-calculate-description){: #calculations-calculate-description } | `String.t` |  | An optional description for the calculation |
| [`public?`](#calculations-calculate-public?){: #calculations-calculate-public? } | `boolean` | `false` | Whether or not the calculation will appear in public interfaces. |
| [`sensitive?`](#calculations-calculate-sensitive?){: #calculations-calculate-sensitive? } | `boolean` | `false` | Whether or not references to the calculation will be considered sensitive. |
| [`load`](#calculations-calculate-load){: #calculations-calculate-load } | `any` | `[]` | A load statement to be applied if the calculation is used. Only works with module-based or function-based calculations, not expression calculations. |
| [`allow_nil?`](#calculations-calculate-allow_nil?){: #calculations-calculate-allow_nil? } | `boolean` | `true` | Whether or not the calculation can return nil. |
| [`filterable?`](#calculations-calculate-filterable?){: #calculations-calculate-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the calculation should be usable in filters. |
| [`sortable?`](#calculations-calculate-sortable?){: #calculations-calculate-sortable? } | `boolean` | `true` | Whether or not the calculation can be referenced in sorts. |
| [`field?`](#calculations-calculate-field?){: #calculations-calculate-field? } | `boolean` | `true` | Whether or not the calculation should create a field on the resource struct. When `false`, the calculation's value will always be stored in the `calculations` map on the record, and will not add a key to the resource struct. The calculation can still be loaded normally. |
| [`multitenancy`](#calculations-calculate-multitenancy){: #calculations-calculate-multitenancy } | `:enforce \| :allow_global \| :bypass \| :bypass_all` |  | Configures multitenancy behavior for the calculation. `:enforce` requires a tenant to be set (the default behavior), `:allow_global` allows using this calculation both with and without a tenant, `:bypass` completely ignores the tenant even if it's set, `:bypass_all` like `:bypass` but also bypasses the tenancy requirement for nested resources. |


### calculations.calculate.argument
```elixir
argument name, type
```


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

See the [calculations guide](/documentation/topics/resources/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`](#calculations-calculate-argument-name){: #calculations-calculate-argument-name .spark-required} | `atom` |  | The name of the argument |
| [`type`](#calculations-calculate-argument-type){: #calculations-calculate-argument-type .spark-required} | `module` |  | The type of the argument. See `Ash.Type` for more. |
### Options

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





### Introspection

Target: `Ash.Resource.Calculation.Argument`




### Introspection

Target: `Ash.Resource.Calculation`




## multitenancy
Options for configuring the multitenancy behavior of a resource.

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

See the [multitenancy guide](/documentation/topics/advanced/multitenancy.md)




### Examples
```
multitenancy do
  strategy :attribute
  attribute :organization_id
  global? true
end

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`strategy`](#multitenancy-strategy){: #multitenancy-strategy } | `:context \| :attribute` | `:context` | Determine if multitenancy is performed with attribute filters or using data layer features. |
| [`attribute`](#multitenancy-attribute){: #multitenancy-attribute } | `atom` |  | If using the `attribute` strategy, the attribute to use, e.g `org_id` |
| [`global?`](#multitenancy-global?){: #multitenancy-global? } | `boolean` | `false` | Whether or not the data may be accessed without setting a tenant. For example, with attribute multitenancy, this allows accessing without filtering by the tenant attribute. |
| [`parse_attribute`](#multitenancy-parse_attribute){: #multitenancy-parse_attribute } | `mfa` | `{Ash.Resource.Dsl, :identity, []}` | An mfa ({module, function, args}) pointing to a function that takes a tenant and returns the attribute value |
| [`tenant_from_attribute`](#multitenancy-tenant_from_attribute){: #multitenancy-tenant_from_attribute } | `mfa` | `{Ash.Resource.Dsl, :identity, []}` | An mfa ({module, function, args}) pointing to a function that takes an attribute value and returns the tenant. This is the inverse of `parse_attribute`. |







<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>