mirror of
https://github.com/ash-project/ash.git
synced 2024-09-20 13:33:20 +12:00
2601 lines
93 KiB
Text
2601 lines
93 KiB
Text
|
# DSL: Ash.Resource.Dsl
|
||
|
|
||
|
|
||
|
|
||
|
## attributes
|
||
|
|
||
|
* [attribute](#attributes-attribute)
|
||
|
* [create_timestamp](#attributes-create_timestamp)
|
||
|
* [update_timestamp](#attributes-update_timestamp)
|
||
|
* [integer_primary_key](#attributes-integer_primary_key)
|
||
|
* [uuid_primary_key](#attributes-uuid_primary_key)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
attributes do
|
||
|
uuid_primary_key :id
|
||
|
|
||
|
attribute :first_name, :string do
|
||
|
allow_nil? false
|
||
|
end
|
||
|
|
||
|
attribute :last_name, :string do
|
||
|
allow_nil? false
|
||
|
end
|
||
|
|
||
|
attribute :email, :string do
|
||
|
allow_nil? false
|
||
|
|
||
|
constraints [
|
||
|
match: ~r/^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/
|
||
|
]
|
||
|
end
|
||
|
|
||
|
attribute :type, :atom do
|
||
|
constraints [
|
||
|
one_of: [:admin, :teacher, :student]
|
||
|
]
|
||
|
end
|
||
|
|
||
|
create_timestamp :inserted_at
|
||
|
update_timestamp :updated_at
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## attributes.attribute
|
||
|
|
||
|
|
||
|
Declares an attribute on the resource.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
attribute :name, :string do
|
||
|
allow_nil? false
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the attribute. |
|
||
|
| `type`* | `module` | | The type of the attribute. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `description` | `String.t` | | An optional description for the attribute. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
|
||
|
| `source` | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
|
||
|
| `always_select?` | `boolean` | false | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
|
||
|
| `primary_key?` | `boolean` | false | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the attribute can be set to nil. If nil value is given error is raised. |
|
||
|
| `generated?` | `boolean` | false | Whether or not the value may be generated by the data layer. |
|
||
|
| `writable?` | `boolean` | true | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
|
||
|
| `private?` | `boolean` | false | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | `(-> any) \| mfa \| any()` | | A value to be set on all creates, unless a value is being provided already. |
|
||
|
| `update_default` | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the attribute can be referenced in filters. |
|
||
|
| `match_other_defaults?` | `boolean` | false | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Attribute`
|
||
|
|
||
|
## attributes.create_timestamp
|
||
|
|
||
|
|
||
|
Declares a non-writable attribute with a create default of `&DateTime.utc_now/0`
|
||
|
|
||
|
Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except it sets
|
||
|
the following different defaults:
|
||
|
|
||
|
writable? false
|
||
|
private? true
|
||
|
default &DateTime.utc_now/0
|
||
|
match_other_defaults? true
|
||
|
type Ash.Type.UTCDatetimeUsec
|
||
|
allow_nil? false
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
create_timestamp :inserted_at
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the attribute. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `type` | `module` | Ash.Type.UtcDatetimeUsec | The type of the attribute. See `Ash.Type` for more. |
|
||
|
| `constraints` | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `description` | `String.t` | | An optional description for the attribute. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
|
||
|
| `source` | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
|
||
|
| `always_select?` | `boolean` | false | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
|
||
|
| `primary_key?` | `boolean` | false | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
|
||
|
| `allow_nil?` | `boolean` | false | Whether or not the attribute can be set to nil. If nil value is given error is raised. |
|
||
|
| `generated?` | `boolean` | false | Whether or not the value may be generated by the data layer. |
|
||
|
| `writable?` | `boolean` | false | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
|
||
|
| `private?` | `boolean` | true | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | `(-> any) \| mfa \| any()` | &DateTime.utc_now/0 | A value to be set on all creates, unless a value is being provided already. |
|
||
|
| `update_default` | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the attribute can be referenced in filters. |
|
||
|
| `match_other_defaults?` | `boolean` | true | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Attribute`
|
||
|
|
||
|
## attributes.update_timestamp
|
||
|
|
||
|
|
||
|
Declares a non-writable attribute with a create and update default of `&DateTime.utc_now/0`
|
||
|
|
||
|
Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except it sets
|
||
|
the following different defaults:
|
||
|
|
||
|
writable? false
|
||
|
private? true
|
||
|
default &DateTime.utc_now/0
|
||
|
match_other_defaults? true
|
||
|
update_default &DateTime.utc_now/0
|
||
|
type Ash.Type.UTCDatetimeUsec
|
||
|
allow_nil? false
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
update_timestamp :inserted_at
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the attribute. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `type` | `module` | Ash.Type.UtcDatetimeUsec | The type of the attribute. See `Ash.Type` for more. |
|
||
|
| `constraints` | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `description` | `String.t` | | An optional description for the attribute. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
|
||
|
| `source` | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
|
||
|
| `always_select?` | `boolean` | false | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
|
||
|
| `primary_key?` | `boolean` | false | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
|
||
|
| `allow_nil?` | `boolean` | false | Whether or not the attribute can be set to nil. If nil value is given error is raised. |
|
||
|
| `generated?` | `boolean` | false | Whether or not the value may be generated by the data layer. |
|
||
|
| `writable?` | `boolean` | false | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
|
||
|
| `private?` | `boolean` | true | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | `(-> any) \| mfa \| any()` | &DateTime.utc_now/0 | A value to be set on all creates, unless a value is being provided already. |
|
||
|
| `update_default` | `(-> any) \| mfa \| any()` | &DateTime.utc_now/0 | A value to be set on all updates, unless a value is being provided already. |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the attribute can be referenced in filters. |
|
||
|
| `match_other_defaults?` | `boolean` | true | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Attribute`
|
||
|
|
||
|
## attributes.integer_primary_key
|
||
|
|
||
|
|
||
|
Declares a generated, non writable, non-nil, primary key column of type integer.
|
||
|
|
||
|
Generated integer primary keys must be supported by the data layer.
|
||
|
|
||
|
Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except for `allow_nil?`, but it sets
|
||
|
the following different defaults:
|
||
|
|
||
|
writable? false
|
||
|
primary_key? true
|
||
|
generated? true
|
||
|
type :integer
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
integer_primary_key :id
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the attribute. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `type` | `module` | :integer | The type of the attribute. See `Ash.Type` for more. |
|
||
|
| `constraints` | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `description` | `String.t` | | An optional description for the attribute. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
|
||
|
| `source` | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
|
||
|
| `always_select?` | `boolean` | false | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
|
||
|
| `primary_key?` | `boolean` | true | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
|
||
|
| `generated?` | `boolean` | true | Whether or not the value may be generated by the data layer. |
|
||
|
| `writable?` | `boolean` | false | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
|
||
|
| `private?` | `boolean` | false | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | `(-> any) \| mfa \| any()` | | A value to be set on all creates, unless a value is being provided already. |
|
||
|
| `update_default` | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the attribute can be referenced in filters. |
|
||
|
| `match_other_defaults?` | `boolean` | false | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Attribute`
|
||
|
|
||
|
## attributes.uuid_primary_key
|
||
|
|
||
|
|
||
|
Declares a non writable, non-nil, primary key column of type `uuid`, which defaults to `Ash.UUID.generate/0`.
|
||
|
|
||
|
Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except for `allow_nil?`, but it sets
|
||
|
the following different defaults:
|
||
|
|
||
|
writable? false
|
||
|
default &Ash.UUID.generate/0
|
||
|
primary_key? true
|
||
|
generated? true
|
||
|
type :uuid
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
uuid_primary_key :id
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the attribute. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `type` | `module` | :uuid | The type of the attribute. See `Ash.Type` for more. |
|
||
|
| `constraints` | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `description` | `String.t` | | An optional description for the attribute. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. |
|
||
|
| `source` | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. |
|
||
|
| `always_select?` | `boolean` | false | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. |
|
||
|
| `primary_key?` | `boolean` | true | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. |
|
||
|
| `generated?` | `boolean` | false | Whether or not the value may be generated by the data layer. |
|
||
|
| `writable?` | `boolean` | false | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. |
|
||
|
| `private?` | `boolean` | false | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | `(-> any) \| mfa \| any()` | &Ash.UUID.generate/0 | A value to be set on all creates, unless a value is being provided already. |
|
||
|
| `update_default` | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the attribute can be referenced in filters. |
|
||
|
| `match_other_defaults?` | `boolean` | false | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Attribute`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## relationships
|
||
|
|
||
|
* [has_one](#relationships-has_one)
|
||
|
* [has_many](#relationships-has_many)
|
||
|
* [many_to_many](#relationships-many_to_many)
|
||
|
* [belongs_to](#relationships-belongs_to)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
relationships do
|
||
|
belongs_to :post, MyApp.Post do
|
||
|
primary_key? true
|
||
|
end
|
||
|
|
||
|
belongs_to :category, MyApp.Category do
|
||
|
primary_key? true
|
||
|
end
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
relationships do
|
||
|
belongs_to :author, MyApp.Author
|
||
|
|
||
|
many_to_many :categories, MyApp.Category do
|
||
|
through MyApp.PostCategory
|
||
|
destination_attribute_on_join_resource :category_id
|
||
|
source_attribute_on_join_resource :post_id
|
||
|
end
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
relationships do
|
||
|
has_many :posts, MyApp.Post do
|
||
|
destination_attribute :author_id
|
||
|
end
|
||
|
|
||
|
has_many :composite_key_posts, MyApp.CompositeKeyPost do
|
||
|
destination_attribute :author_id
|
||
|
end
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## relationships.has_one
|
||
|
|
||
|
|
||
|
Declares a `has_one` relationship. In a relational database, the foreign key would be on the *other* table.
|
||
|
|
||
|
Generally speaking, a `has_one` also implies that the destination table is unique on that foreign key.
|
||
|
|
||
|
See the [relationships guide](/documentation/topics/relationships.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
# In a resource called `Word`
|
||
|
has_one :dictionary_entry, DictionaryEntry do
|
||
|
source_attribute :text
|
||
|
destination_attribute :word_text
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name` | `atom` | | The name of the relationship |
|
||
|
| `destination` | `module` | | The destination resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `manual` | `(any, any -> any) \| module` | | A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. |
|
||
|
| `no_attributes?` | `boolean` | | All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/relationships.md) for more. |
|
||
|
| `allow_nil?` | `boolean` | true | Marks the relationship as required. Has no effect on validations, but can inform extensions that there will always be a related entity. |
|
||
|
| `from_many?` | `boolean` | false | Signal that this relationship is actually a `has_many` where the first record is given via the `sort`. This will allow data layers to properly deduplicate when necessary. |
|
||
|
| `description` | `String.t` | | An optional description for the relationship |
|
||
|
| `destination_attribute` | `atom` | | The attribute on the related resource that should match the `source_attribute` configured on this resource. |
|
||
|
| `validate_destination_attribute?` | `boolean` | true | Whether or not to validate that the destination field exists on the destination resource |
|
||
|
| `source_attribute` | `atom` | :id | The field on this resource that should match the `destination_attribute` on the related resource. |
|
||
|
| `relationship_context` | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. |
|
||
|
| `private?` | `boolean` | false | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `not_found_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. |
|
||
|
| `writable?` | `boolean` | true | Whether or not the relationship may be managed. |
|
||
|
| `read_action` | `atom` | | The read action on the destination resource to use when loading data and filtering. |
|
||
|
| `api` | `atom` | | The API module to use when working with the related entity. |
|
||
|
| `filter` | ``any`` | | A filter to be applied when reading the relationship. |
|
||
|
| `filterable?` | `boolean` | true | If set to `false`, the relationship will not be usable in filters. |
|
||
|
| `sort` | ``any`` | | A sort statement to be applied when loading the relationship. |
|
||
|
| `could_be_related_at_creation?` | `boolean` | false | Whether or not related values may exist for this relationship at creation. |
|
||
|
| `violation_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Relationships.HasOne`
|
||
|
|
||
|
## relationships.has_many
|
||
|
|
||
|
|
||
|
Declares a `has_many` relationship. There can be any number of related entities.
|
||
|
|
||
|
See the [relationships guide](/documentation/topics/relationships.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
# In a resource called `Word`
|
||
|
has_many :definitions, DictionaryDefinition do
|
||
|
source_attribute :text
|
||
|
destination_attribute :word_text
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name` | `atom` | | The name of the relationship |
|
||
|
| `destination` | `module` | | The destination resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `manual` | `(any, any -> any) \| module` | | A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. |
|
||
|
| `no_attributes?` | `boolean` | | All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/relationships.md) for more. |
|
||
|
| `description` | `String.t` | | An optional description for the relationship |
|
||
|
| `destination_attribute` | `atom` | | The attribute on the related resource that should match the `source_attribute` configured on this resource. |
|
||
|
| `validate_destination_attribute?` | `boolean` | true | Whether or not to validate that the destination field exists on the destination resource |
|
||
|
| `source_attribute` | `atom` | :id | The field on this resource that should match the `destination_attribute` on the related resource. |
|
||
|
| `relationship_context` | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. |
|
||
|
| `private?` | `boolean` | false | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `not_found_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. |
|
||
|
| `writable?` | `boolean` | true | Whether or not the relationship may be managed. |
|
||
|
| `read_action` | `atom` | | The read action on the destination resource to use when loading data and filtering. |
|
||
|
| `api` | `atom` | | The API module to use when working with the related entity. |
|
||
|
| `filter` | ``any`` | | A filter to be applied when reading the relationship. |
|
||
|
| `filterable?` | `boolean` | true | If set to `false`, the relationship will not be usable in filters. |
|
||
|
| `sort` | ``any`` | | A sort statement to be applied when loading the relationship. |
|
||
|
| `could_be_related_at_creation?` | `boolean` | false | Whether or not related values may exist for this relationship at creation. |
|
||
|
| `violation_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Relationships.HasMany`
|
||
|
|
||
|
## relationships.many_to_many
|
||
|
|
||
|
|
||
|
Declares a `many_to_many` relationship. Many to many relationships require a join resource.
|
||
|
|
||
|
A join resource is a resource that consists of a relationship to the source and destination of the many to many.
|
||
|
|
||
|
See the [relationships guide](/documentation/topics/relationships.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
# In a resource called `Word`
|
||
|
many_to_many :books, Book do
|
||
|
through BookWord
|
||
|
source_attribute :text
|
||
|
source_attribute_on_join_resource :word_text
|
||
|
destination_attribute :id
|
||
|
destination_attribute_on_join_resource :book_id
|
||
|
end
|
||
|
|
||
|
# And in `BookWord` (the join resource)
|
||
|
belongs_to :book, Book, primary_key?: true, allow_nil?: false
|
||
|
belongs_to :word, Word, primary_key?: true, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name` | `atom` | | The name of the relationship |
|
||
|
| `destination` | `module` | | The destination resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `source_attribute_on_join_resource`* | `atom` | | The attribute on the join resource that should line up with `source_attribute` on this resource. |
|
||
|
| `destination_attribute_on_join_resource`* | `atom` | | The attribute on the join resource that should line up with `destination_attribute` on the related resource. |
|
||
|
| `through`* | `module` | | The resource to use as the join resource. |
|
||
|
| `join_relationship` | `atom` | | The has_many relationship to the join resource. Defaults to <relationship_name>_join_assoc |
|
||
|
| `description` | `String.t` | | An optional description for the relationship |
|
||
|
| `destination_attribute` | `atom` | :id | The attribute on the related resource that should match the `source_attribute` configured on this resource. |
|
||
|
| `validate_destination_attribute?` | `boolean` | true | Whether or not to validate that the destination field exists on the destination resource |
|
||
|
| `source_attribute` | `atom` | :id | The field on this resource that should match the `destination_attribute` on the related resource. |
|
||
|
| `relationship_context` | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. |
|
||
|
| `private?` | `boolean` | false | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `not_found_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. |
|
||
|
| `writable?` | `boolean` | true | Whether or not the relationship may be managed. |
|
||
|
| `read_action` | `atom` | | The read action on the destination resource to use when loading data and filtering. |
|
||
|
| `api` | `atom` | | The API module to use when working with the related entity. |
|
||
|
| `filter` | ``any`` | | A filter to be applied when reading the relationship. |
|
||
|
| `filterable?` | `boolean` | true | If set to `false`, the relationship will not be usable in filters. |
|
||
|
| `sort` | ``any`` | | A sort statement to be applied when loading the relationship. |
|
||
|
| `could_be_related_at_creation?` | `boolean` | false | Whether or not related values may exist for this relationship at creation. |
|
||
|
| `violation_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Relationships.ManyToMany`
|
||
|
|
||
|
## relationships.belongs_to
|
||
|
|
||
|
|
||
|
Declares a `belongs_to` relationship. In a relational database, the foreign key would be on the *source* table.
|
||
|
|
||
|
This creates a field on the resource with the corresponding name and type, unless `define_attribute?: false` is provided.
|
||
|
|
||
|
See the [relationships guide](/documentation/topics/relationships.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
# In a resource called `Word`
|
||
|
belongs_to :dictionary_entry, DictionaryEntry do
|
||
|
source_attribute :text,
|
||
|
destination_attribute :word_text
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name` | `atom` | | The name of the relationship |
|
||
|
| `destination` | `module` | | The destination resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `primary_key?` | `boolean` | false | Whether the generated attribute is, or is part of, the primary key of a resource. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether this relationship must always be present, e.g: must be included on creation, and never removed (it may be modified). The generated attribute will not allow nil values. |
|
||
|
| `attribute_writable?` | `boolean` | false | Whether the generated attribute will be marked as public & writable. |
|
||
|
| `define_attribute?` | `boolean` | true | If set to `false` an attribute is not created on the resource for this relationship, and one must be manually added in `attributes`, invalidating many other options. |
|
||
|
| `attribute_type` | ``any`` | :uuid | The type of the generated created attribute. See `Ash.Type` for more. |
|
||
|
| `description` | `String.t` | | An optional description for the relationship |
|
||
|
| `destination_attribute` | `atom` | :id | The attribute on the related resource that should match the `source_attribute` configured on this resource. |
|
||
|
| `validate_destination_attribute?` | `boolean` | true | Whether or not to validate that the destination field exists on the destination resource |
|
||
|
| `source_attribute` | `atom` | | The field on this resource that should match the `destination_attribute` on the related resource. - Defaults to <name>_id |
|
||
|
| `relationship_context` | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. |
|
||
|
| `private?` | `boolean` | false | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `not_found_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. |
|
||
|
| `writable?` | `boolean` | true | Whether or not the relationship may be managed. |
|
||
|
| `read_action` | `atom` | | The read action on the destination resource to use when loading data and filtering. |
|
||
|
| `api` | `atom` | | The API module to use when working with the related entity. |
|
||
|
| `filter` | ``any`` | | A filter to be applied when reading the relationship. |
|
||
|
| `filterable?` | `boolean` | true | If set to `false`, the relationship will not be usable in filters. |
|
||
|
| `sort` | ``any`` | | A sort statement to be applied when loading the relationship. |
|
||
|
| `violation_message` | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Relationships.BelongsTo`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## actions
|
||
|
A section for declaring resource actions.
|
||
|
|
||
|
All manipulation of data through the underlying data layer happens through actions.
|
||
|
There are four types of action: `create`, `read`, `update`, and `destroy`. You may
|
||
|
recognize these from the acronym `CRUD`. You can have multiple actions of the same
|
||
|
type, as long as they have different names. This is the primary mechanism for customizing
|
||
|
your resources to conform to your business logic. It is normal and expected to have
|
||
|
multiple actions of each type in a large application.
|
||
|
|
||
|
|
||
|
* [action](#actions-action)
|
||
|
* argument
|
||
|
* [create](#actions-create)
|
||
|
* change
|
||
|
* validate
|
||
|
* argument
|
||
|
* metadata
|
||
|
* [read](#actions-read)
|
||
|
* argument
|
||
|
* prepare
|
||
|
* pagination
|
||
|
* metadata
|
||
|
* [update](#actions-update)
|
||
|
* change
|
||
|
* validate
|
||
|
* metadata
|
||
|
* argument
|
||
|
* [destroy](#actions-destroy)
|
||
|
* change
|
||
|
* validate
|
||
|
* metadata
|
||
|
* argument
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
actions do
|
||
|
create :signup do
|
||
|
argument :password, :string
|
||
|
argument :password_confirmation, :string
|
||
|
validate confirm(:password, :password_confirmation)
|
||
|
change {MyApp.HashPassword, []} # A custom implemented Change
|
||
|
end
|
||
|
|
||
|
read :me do
|
||
|
# An action that auto filters to only return the user for the current user
|
||
|
filter [id: actor(:id)]
|
||
|
end
|
||
|
|
||
|
update :update do
|
||
|
accept [:first_name, :last_name]
|
||
|
end
|
||
|
|
||
|
destroy do
|
||
|
change set_attribute(:deleted_at, &DateTime.utc_now/0)
|
||
|
# This tells it that even though this is a delete action, it
|
||
|
# should be treated like an update because `deleted_at` is set.
|
||
|
# This should be coupled with a `base_filter` on the resource
|
||
|
# or with the read actions having a `filter` for `is_nil: :deleted_at`
|
||
|
soft? true
|
||
|
end
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `defaults` | `list(:create \| :read \| :update \| :destroy)` | | Creates a simple action of each specified type, with the same name as the type. These will be `primary?` unless one already exists for that type. Embedded resources, however, have a default of all resource types. |
|
||
|
| `default_accept` | `list(atom)` | | A default value for the `accept` option for each action. Defaults to all public attributes. |
|
||
|
|
||
|
|
||
|
|
||
|
## actions.action
|
||
|
|
||
|
|
||
|
Declares a generic action. A combination of arguments, a return type and a run function.
|
||
|
|
||
|
For calling this action, see the `Ash.Api` documentation.
|
||
|
|
||
|
|
||
|
* [argument](#actions-action-argument)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
action :top_user_emails, {:array, :string} do
|
||
|
argument :limit, :integer, default: 10, allow_nil?: false
|
||
|
run fn input, context ->
|
||
|
with {:ok, top_users} <- top_users(input.limit) do
|
||
|
{:ok, Enum.map(top_users, &(&1.email))}
|
||
|
end
|
||
|
end
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the action |
|
||
|
| `returns` | `module` | | The return type of the action. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | | Constraints for the return type. See the [constriants topic](/documentation/topics/constraints.md) for more. |
|
||
|
| `allow_nil?` | `boolean` | false | Wether or not the action can return nil. Unlike attributes & arguments, this defaults to `false`. |
|
||
|
| `run` | `(any, any -> any) \| module` | | |
|
||
|
| `primary?` | `boolean` | false | Whether or not this action should be used when no action is specified by the caller. |
|
||
|
| `description` | `String.t` | | An optional description for the action |
|
||
|
| `transaction?` | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
|
||
|
| `touches_resources` | `list(atom)` | | A list of resources that the action may touch, used when building transactions. |
|
||
|
|
||
|
|
||
|
## actions.action.argument
|
||
|
|
||
|
|
||
|
Declares an argument on the action
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
argument :password_confirmation, :string
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the argument |
|
||
|
| `type`* | `module` | | The type of the argument. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `description` | `String.t` | | An optional description for the argument. |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
|
||
|
| `private?` | `boolean` | false | Whether or not the argument should be suppliable by the client. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Argument`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Action`
|
||
|
|
||
|
## actions.create
|
||
|
|
||
|
|
||
|
Declares a `create` action. For calling this action, see the `Ash.Api` documentation.
|
||
|
|
||
|
|
||
|
* [change](#actions-create-change)
|
||
|
* [validate](#actions-create-validate)
|
||
|
* [argument](#actions-create-argument)
|
||
|
* [metadata](#actions-create-metadata)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
create :register do
|
||
|
primary? true
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the action |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `allow_nil_input` | `list(atom)` | | A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the record is created. |
|
||
|
| `manual` | `(any, any -> any) \| module` | | Override the creation behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
| `upsert?` | `boolean` | false | Forces all uses of this action to be treated as an upsert. |
|
||
|
| `upsert_identity` | `atom` | | The identity to use for the upsert. Cannot be overriden by the caller. Ignored if `upsert?` is not set to `true`. |
|
||
|
| `upsert_fields` | `list(atom)` | | The fields to overwrite in the case of an upsert. If not provided, all fields except for fields set by defaults will be overwritten. |
|
||
|
| `primary?` | `boolean` | false | Whether or not this action should be used when no action is specified by the caller. |
|
||
|
| `description` | `String.t` | | An optional description for the action |
|
||
|
| `transaction?` | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
|
||
|
| `touches_resources` | `list(atom)` | | A list of resources that the action may touch, used when building transactions. |
|
||
|
| `accept` | `:all \| list(atom)` | | The list of attributes to accept. Defaults to all attributes on the resource |
|
||
|
| `delay_global_validations?` | `boolean` | false | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. |
|
||
|
| `skip_global_validations?` | `boolean` | false | If true, global validations will be skipped. Useful for manual actions. |
|
||
|
| `reject` | `:all \| list(atom)` | | A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. |
|
||
|
| `require_attributes` | `list(atom)` | | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? |
|
||
|
| `error_handler` | `mfa` | | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more |
|
||
|
| `manual?` | `boolean` | | Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
|
||
|
|
||
|
## actions.create.change
|
||
|
|
||
|
|
||
|
A change to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Change` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
change relate_actor(:reporter)
|
||
|
```
|
||
|
|
||
|
```
|
||
|
change {MyCustomChange, :foo}
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `change`* | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `only_when_valid?` | `boolean` | false | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. |
|
||
|
| `description` | `String.t` | | An optional description for the change |
|
||
|
| `where` | `list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Change`
|
||
|
|
||
|
## actions.create.validate
|
||
|
|
||
|
|
||
|
Declares a validation to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Validation` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
validate changing(:email)
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `validation`* | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `where` | `(any -> any) \| module \| list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. |
|
||
|
| `only_when_valid?` | `boolean` | false | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. |
|
||
|
| `message` | `String.t` | | If provided, overrides any message set by the validation error |
|
||
|
| `description` | `String.t` | | An optional description for the validation |
|
||
|
| `before_action?` | `boolean` | false | If set to `true`, the validation will be run in a before_action hook |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Validation`
|
||
|
|
||
|
## actions.create.argument
|
||
|
|
||
|
|
||
|
Declares an argument on the action
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
argument :password_confirmation, :string
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the argument |
|
||
|
| `type`* | `module` | | The type of the argument. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `description` | `String.t` | | An optional description for the argument. |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
|
||
|
| `private?` | `boolean` | false | Whether or not the argument should be suppliable by the client. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Argument`
|
||
|
|
||
|
## actions.create.metadata
|
||
|
|
||
|
|
||
|
A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom
|
||
|
change via `Ash.Resource.Info.put_metadata/3`.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
metadata :api_token, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
metadata :operation_id, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the metadata |
|
||
|
| `type`* | ``any`` | | The type of the metadata. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | [] | Type constraints on the metadata |
|
||
|
| `description` | `String.t` | | An optional description for the metadata. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the metadata may return `nil` |
|
||
|
| `default` | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Metadata`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Create`
|
||
|
|
||
|
## actions.read
|
||
|
|
||
|
|
||
|
Declares a `read` action. For calling this action, see the `Ash.Api` documentation.
|
||
|
|
||
|
|
||
|
* [argument](#actions-read-argument)
|
||
|
* [prepare](#actions-read-prepare)
|
||
|
* [pagination](#actions-read-pagination)
|
||
|
* [metadata](#actions-read-metadata)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
read :read_all do
|
||
|
primary? true
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the action |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `filter` | ``any`` | | A filter template that will be applied whenever the action is used. See `Ash.Filter` for more on templates |
|
||
|
| `manual` | `(any, any, any -> any) \| module` | | Delegates running of the query to the provided module. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
| `get?` | `boolean` | false | Expresses that this action innately only returns a single result. Used by extensions to validate and/or modify behavior. Causes code interfaces to return a single value instead of a list. See the [code interface guide](/documentation/topics/code-interface.md) for more. |
|
||
|
| `modify_query` | `mfa \| (any, any -> any)` | | Allows direct manipulation of the data layer query via an MFA. The ash query and the data layer query will be provided as additional arguments. The result must be `{:ok, new_data_layer_query} \| {:error, error}`. |
|
||
|
| `get_by` | `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. |
|
||
|
| `primary?` | `boolean` | false | Whether or not this action should be used when no action is specified by the caller. |
|
||
|
| `description` | `String.t` | | An optional description for the action |
|
||
|
| `transaction?` | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
|
||
|
| `touches_resources` | `list(atom)` | | A list of resources that the action may touch, used when building transactions. |
|
||
|
|
||
|
|
||
|
## actions.read.argument
|
||
|
|
||
|
|
||
|
Declares an argument on the action
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
argument :password_confirmation, :string
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the argument |
|
||
|
| `type`* | `module` | | The type of the argument. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `description` | `String.t` | | An optional description for the argument. |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
|
||
|
| `private?` | `boolean` | false | Whether or not the argument should be suppliable by the client. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Argument`
|
||
|
|
||
|
## actions.read.prepare
|
||
|
|
||
|
|
||
|
Declares a preparation, which can be used to prepare a query for a read action.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
prepare build(sort: [:foo, :bar])
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `preparation`* | `(any, any -> any) \| module` | | The module and options for a preparation. Also accepts functions take the query and the context. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Preparation`
|
||
|
|
||
|
## actions.read.pagination
|
||
|
```elixir
|
||
|
pagination
|
||
|
```
|
||
|
|
||
|
|
||
|
Adds pagination options to a resource
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `keyset?` | `boolean` | false | Whether or not keyset based pagination is supported |
|
||
|
| `offset?` | `boolean` | false | Whether or not offset based pagination is supported |
|
||
|
| `default_limit` | `pos_integer` | | The default page size to apply, if one is not supplied |
|
||
|
| `countable` | `true \| false \| :by_default` | false | Whether not a returned page will have a full count of all records. Use `:by_default` to do it automatically. |
|
||
|
| `max_page_size` | `pos_integer` | 250 | The maximum amount of records that can be requested in a single page |
|
||
|
| `required?` | `boolean` | true | Whether or not pagination can be disabled. Only relevant if some pagination configuration is supplied. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Read.Pagination`
|
||
|
|
||
|
## actions.read.metadata
|
||
|
|
||
|
|
||
|
A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom
|
||
|
change via `Ash.Resource.Info.put_metadata/3`.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
metadata :api_token, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
metadata :operation_id, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the metadata |
|
||
|
| `type`* | ``any`` | | The type of the metadata. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | [] | Type constraints on the metadata |
|
||
|
| `description` | `String.t` | | An optional description for the metadata. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the metadata may return `nil` |
|
||
|
| `default` | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Metadata`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Read`
|
||
|
|
||
|
## actions.update
|
||
|
|
||
|
|
||
|
Declares a `update` action. For calling this action, see the `Ash.Api` documentation.
|
||
|
|
||
|
|
||
|
* [change](#actions-update-change)
|
||
|
* [validate](#actions-update-validate)
|
||
|
* [metadata](#actions-update-metadata)
|
||
|
* [argument](#actions-update-argument)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
update :flag_for_review, primary?: true
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the action |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `manual` | `(any, any -> any) \| module` | | Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
| `primary?` | `boolean` | false | Whether or not this action should be used when no action is specified by the caller. |
|
||
|
| `description` | `String.t` | | An optional description for the action |
|
||
|
| `transaction?` | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
|
||
|
| `touches_resources` | `list(atom)` | | A list of resources that the action may touch, used when building transactions. |
|
||
|
| `accept` | `:all \| list(atom)` | | The list of attributes to accept. Defaults to all attributes on the resource |
|
||
|
| `delay_global_validations?` | `boolean` | false | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. |
|
||
|
| `skip_global_validations?` | `boolean` | false | If true, global validations will be skipped. Useful for manual actions. |
|
||
|
| `reject` | `:all \| list(atom)` | | A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. |
|
||
|
| `require_attributes` | `list(atom)` | | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? |
|
||
|
| `error_handler` | `mfa` | | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more |
|
||
|
| `manual?` | `boolean` | | Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
|
||
|
|
||
|
## actions.update.change
|
||
|
|
||
|
|
||
|
A change to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Change` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
change relate_actor(:reporter)
|
||
|
```
|
||
|
|
||
|
```
|
||
|
change {MyCustomChange, :foo}
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `change`* | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `only_when_valid?` | `boolean` | false | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. |
|
||
|
| `description` | `String.t` | | An optional description for the change |
|
||
|
| `where` | `list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Change`
|
||
|
|
||
|
## actions.update.validate
|
||
|
|
||
|
|
||
|
Declares a validation to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Validation` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
validate changing(:email)
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `validation`* | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `where` | `(any -> any) \| module \| list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. |
|
||
|
| `only_when_valid?` | `boolean` | false | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. |
|
||
|
| `message` | `String.t` | | If provided, overrides any message set by the validation error |
|
||
|
| `description` | `String.t` | | An optional description for the validation |
|
||
|
| `before_action?` | `boolean` | false | If set to `true`, the validation will be run in a before_action hook |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Validation`
|
||
|
|
||
|
## actions.update.metadata
|
||
|
|
||
|
|
||
|
A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom
|
||
|
change via `Ash.Resource.Info.put_metadata/3`.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
metadata :api_token, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
metadata :operation_id, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the metadata |
|
||
|
| `type`* | ``any`` | | The type of the metadata. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | [] | Type constraints on the metadata |
|
||
|
| `description` | `String.t` | | An optional description for the metadata. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the metadata may return `nil` |
|
||
|
| `default` | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Metadata`
|
||
|
|
||
|
## actions.update.argument
|
||
|
|
||
|
|
||
|
Declares an argument on the action
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
argument :password_confirmation, :string
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the argument |
|
||
|
| `type`* | `module` | | The type of the argument. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `description` | `String.t` | | An optional description for the argument. |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
|
||
|
| `private?` | `boolean` | false | Whether or not the argument should be suppliable by the client. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Argument`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Update`
|
||
|
|
||
|
## actions.destroy
|
||
|
|
||
|
|
||
|
Declares a `destroy` action. For calling this action, see the `Ash.Api` documentation.
|
||
|
|
||
|
|
||
|
* [change](#actions-destroy-change)
|
||
|
* [validate](#actions-destroy-validate)
|
||
|
* [metadata](#actions-destroy-metadata)
|
||
|
* [argument](#actions-destroy-argument)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
destroy :soft_delete do
|
||
|
primary? true
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the action |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `soft?` | `atom` | false | If specified, the destroy action behaves as an update internally |
|
||
|
| `manual` | `(any, any -> any) \| module` | | Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
| `primary?` | `boolean` | false | Whether or not this action should be used when no action is specified by the caller. |
|
||
|
| `description` | `String.t` | | An optional description for the action |
|
||
|
| `transaction?` | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. |
|
||
|
| `touches_resources` | `list(atom)` | | A list of resources that the action may touch, used when building transactions. |
|
||
|
| `accept` | `:all \| list(atom)` | | The list of attributes to accept. Defaults to all attributes on the resource |
|
||
|
| `delay_global_validations?` | `boolean` | false | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. |
|
||
|
| `skip_global_validations?` | `boolean` | false | If true, global validations will be skipped. Useful for manual actions. |
|
||
|
| `reject` | `:all \| list(atom)` | | A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. |
|
||
|
| `require_attributes` | `list(atom)` | | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? |
|
||
|
| `error_handler` | `mfa` | | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more |
|
||
|
| `manual?` | `boolean` | | Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. |
|
||
|
|
||
|
|
||
|
## actions.destroy.change
|
||
|
|
||
|
|
||
|
A change to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Change` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
change relate_actor(:reporter)
|
||
|
```
|
||
|
|
||
|
```
|
||
|
change {MyCustomChange, :foo}
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `change`* | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `only_when_valid?` | `boolean` | false | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. |
|
||
|
| `description` | `String.t` | | An optional description for the change |
|
||
|
| `where` | `list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Change`
|
||
|
|
||
|
## actions.destroy.validate
|
||
|
|
||
|
|
||
|
Declares a validation to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Validation` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
validate changing(:email)
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `validation`* | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `where` | `(any -> any) \| module \| list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. |
|
||
|
| `only_when_valid?` | `boolean` | false | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. |
|
||
|
| `message` | `String.t` | | If provided, overrides any message set by the validation error |
|
||
|
| `description` | `String.t` | | An optional description for the validation |
|
||
|
| `before_action?` | `boolean` | false | If set to `true`, the validation will be run in a before_action hook |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Validation`
|
||
|
|
||
|
## actions.destroy.metadata
|
||
|
|
||
|
|
||
|
A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom
|
||
|
change via `Ash.Resource.Info.put_metadata/3`.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
metadata :api_token, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
metadata :operation_id, :string, allow_nil?: false
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the metadata |
|
||
|
| `type`* | ``any`` | | The type of the metadata. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | [] | Type constraints on the metadata |
|
||
|
| `description` | `String.t` | | An optional description for the metadata. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the metadata may return `nil` |
|
||
|
| `default` | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Metadata`
|
||
|
|
||
|
## actions.destroy.argument
|
||
|
|
||
|
|
||
|
Declares an argument on the action
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
argument :password_confirmation, :string
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the argument |
|
||
|
| `type`* | `module` | | The type of the argument. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `description` | `String.t` | | An optional description for the argument. |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. |
|
||
|
| `private?` | `boolean` | false | Whether or not the argument should be suppliable by the client. |
|
||
|
| `sensitive?` | `boolean` | false | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `default` | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Argument`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Actions.Destroy`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## code_interface
|
||
|
Functions that will be defined on the Api module to interact with this resource. See the [code interface guide](/documentation/topics/code-interface.md) for more.
|
||
|
|
||
|
|
||
|
* [define](#code_interface-define)
|
||
|
* [define_calculation](#code_interface-define_calculation)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
code_interface do
|
||
|
define_for MyApp.Api
|
||
|
define :create_user, action: :create
|
||
|
define :get_user_by_id, action: :get_by_id, args: [:id], get?: true
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `define_for` | `module` | false | Defines the code interface on the resource module directly, using the provided Api. |
|
||
|
|
||
|
|
||
|
|
||
|
## code_interface.define
|
||
|
|
||
|
|
||
|
Defines a function with the corresponding name and arguments. See the [code interface guide](/documentation/topics/code-interface.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
define :get_user_by_id, action: :get_by_id, args: [:id], get?: true
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the function that will be defined |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `action` | `atom` | | The name of the action that will be called. Defaults to the same name as the function. |
|
||
|
| `args` | `list(atom \| {:optional, atom})` | | Map specific arguments to named inputs. Can provide any argument/attributes that the action allows. |
|
||
|
| `not_found_error?` | `boolean` | true | If the action or interface is configured with `get?: true`, this determines whether or not an error is raised or `nil` is returned. |
|
||
|
| `get?` | `boolean` | | Expects to only receive a single result from a read action, and returns a single result instead of a list. Ignored for other action types. |
|
||
|
| `get_by` | `list(atom)` | | Takes a list of fields and adds those fields as arguments, which will then be used to filter. Sets `get?` to true automatically. Ignored for non-read actions. |
|
||
|
| `get_by_identity` | `atom` | | Only relevant for read actions. Takes an identity, and gets its field list, performing the same logic as `get_by` once it has the list of fields. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Interface`
|
||
|
|
||
|
## code_interface.define_calculation
|
||
|
|
||
|
|
||
|
Defines a function with the corresponding name and arguments, that evaluates a calculation. Use `:_record` to take an instance of a record. See the [code interface guide](/documentation/topics/code-interface.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
define_calculation :referral_link, args: [:id]
|
||
|
```
|
||
|
|
||
|
```
|
||
|
define_calculation :referral_link, args: [{:arg, :id}, {:ref, :id}]
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the function that will be defined |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `calculation` | `atom` | | The name of the calculation that will be evaluated. Defaults to the same name as the function. |
|
||
|
| `args` | ``any`` | [] | Supply field or argument values referenced by the calculation, in the form of :name, `{:arg, :name}` and/or `{:ref, :name}`. See the [code interface guide](/documentation/topics/code-interface.md) for more. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.CalculationInterface`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## resource
|
||
|
General resource configuration
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
resource do
|
||
|
description "A description of this resource"
|
||
|
base_filter [is_nil: :deleted_at]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `description` | `String.t` | | A human readable description of the resource, to be used in generated documentation |
|
||
|
| `base_filter` | ``any`` | | A filter statement to be applied to any queries on the resource |
|
||
|
| `default_context` | ``any`` | | Default context to apply to any queries/changesets generated for this resource. |
|
||
|
| `trace_name` | `String.t` | | The name to use in traces. Defaults to the short_name stringified. See the [monitoring guide](/documentation/topics/monitoring.md) for more. |
|
||
|
| `short_name` | `atom` | | A short identifier for the resource, which should be unique. See the [monitoring guide](/documentation/topics/monitoring.md) for more. |
|
||
|
| `plural_name` | `atom` | | A pluralized version of the resource short_name. May be used by generators or automated tooling. |
|
||
|
| `simple_notifiers` | `list(module)` | | A list of notifiers that require no DSL. Can be used to avoid compile time dependencies on notifiers |
|
||
|
| `require_primary_key?` | `boolean` | true | Allow the resource to be used without any primary key fields. Warning: this option is experimental, and should not be used unless you know what you're doing. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## identities
|
||
|
|
||
|
* [identity](#identities-identity)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
identities do
|
||
|
identity :full_name, [:first_name, :last_name]
|
||
|
identity :email, [:email]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## identities.identity
|
||
|
|
||
|
|
||
|
Represents a unique constraint on the resource.
|
||
|
|
||
|
See the [identities guide](/documentation/topics/identities.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
identity :name, [:name]
|
||
|
```
|
||
|
|
||
|
```
|
||
|
identity :full_name, [:first_name, :last_name]
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the identity. |
|
||
|
| `keys`* | ``any`` | | The names of the attributes that uniquely identify this resource. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `eager_check_with` | `module` | | Validates that the unique identity provided is unique at validation time, outside of any transactions, using the api module provided. |
|
||
|
| `pre_check_with` | `module` | | Validates that the unique identity provided is unique in a before_action hook. |
|
||
|
| `description` | `String.t` | | An optional description for the identity |
|
||
|
| `message` | `String.t` | | An error message to use when the unique identity would be violated |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Identity`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## changes
|
||
|
|
||
|
* [change](#changes-change)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
changes do
|
||
|
change {Mod, [foo: :bar]}
|
||
|
change set_context(%{some: :context})
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## changes.change
|
||
|
|
||
|
|
||
|
A change to be applied to the changeset.
|
||
|
|
||
|
See `Ash.Resource.Change` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
change relate_actor(:reporter)
|
||
|
```
|
||
|
|
||
|
```
|
||
|
change {MyCustomChange, :foo}
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `change`* | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `on` | ``any`` | [:create, :update] | The action types the validation should run on. Destroy actions are omitted by default as most changes don't make sense for a destroy. |
|
||
|
| `only_when_valid?` | `boolean` | false | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. |
|
||
|
| `description` | `String.t` | | An optional description for the change |
|
||
|
| `where` | `list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Change`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## preparations
|
||
|
|
||
|
* [prepare](#preparations-prepare)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
preparations do
|
||
|
prepare {Mod, [foo: :bar]}
|
||
|
prepare set_context(%{some: :context})
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## preparations.prepare
|
||
|
|
||
|
|
||
|
Declares a preparation, which can be used to prepare a query for a read action.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
prepare build(sort: [:foo, :bar])
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `preparation`* | `(any, any -> any) \| module` | | The module and options for a preparation. Also accepts functions take the query and the context. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Preparation`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## validations
|
||
|
|
||
|
* [validate](#validations-validate)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
validations do
|
||
|
validate {Mod, [foo: :bar]}
|
||
|
validate at_least_one_of_present([:first_name, :last_name])
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## validations.validate
|
||
|
|
||
|
|
||
|
Declares a validation for creates and updates.
|
||
|
|
||
|
See `Ash.Resource.Change` for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
validate {Mod, [foo: :bar]}
|
||
|
```
|
||
|
|
||
|
```
|
||
|
validate at_least_one_of_present([:first_name, :last_name])
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `validation`* | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `where` | `(any -> any) \| module \| list((any -> any) \| module)` | [] | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. |
|
||
|
| `on` | ``any`` | [:create, :update] | The action types the validation should run on. Many validations don't make sense in the context of deletion, so by default it is not included. |
|
||
|
| `only_when_valid?` | `boolean` | false | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. |
|
||
|
| `message` | `String.t` | | If provided, overrides any message set by the validation error |
|
||
|
| `description` | `String.t` | | An optional description for the validation |
|
||
|
| `before_action?` | `boolean` | false | If set to `true`, the validation will be run in a before_action hook |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Validation`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## aggregates
|
||
|
|
||
|
* [count](#aggregates-count)
|
||
|
* [exists](#aggregates-exists)
|
||
|
* [first](#aggregates-first)
|
||
|
* [sum](#aggregates-sum)
|
||
|
* [list](#aggregates-list)
|
||
|
* [max](#aggregates-max)
|
||
|
* [min](#aggregates-min)
|
||
|
* [avg](#aggregates-avg)
|
||
|
* [custom](#aggregates-custom)
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
aggregates do
|
||
|
count :assigned_ticket_count, :reported_tickets do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## aggregates.count
|
||
|
|
||
|
|
||
|
Declares a named count aggregate on the resource
|
||
|
|
||
|
Supports `filter`, but not `sort` (because that wouldn't affect the count)
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
count :assigned_ticket_count, :assigned_tickets do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `uniq?` | `boolean` | false | Wether or not to count unique values only |
|
||
|
| `read_action` | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.exists
|
||
|
|
||
|
|
||
|
Declares a named `exists` aggregate on the resource
|
||
|
|
||
|
Supports `filter`, but not `sort` (because that wouldn't affect if something exists)
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
exists :has_ticket, :assigned_tickets
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.first
|
||
|
|
||
|
|
||
|
Declares a named `first` aggregate on the resource
|
||
|
|
||
|
First aggregates return the first value of the related record
|
||
|
that matches. Supports both `filter` and `sort`.
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
first :first_assigned_ticket_subject, :assigned_tickets, :subject do
|
||
|
filter [active: true]
|
||
|
sort [:subject]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `sort` | ``any`` | | A sort to be applied to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.sum
|
||
|
|
||
|
|
||
|
Declares a named `sum` aggregate on the resource
|
||
|
|
||
|
Supports `filter`, but not `sort` (because that wouldn't affect the sum)
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
sum :assigned_ticket_price_sum, :assigned_tickets, :price do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.list
|
||
|
|
||
|
|
||
|
Declares a named `list` aggregate on the resource.
|
||
|
|
||
|
A list aggregate selects the list of all values for the given field
|
||
|
and relationship combination.
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
list :assigned_ticket_prices, :assigned_tickets, :price do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `uniq?` | `boolean` | false | Wether or not to count unique values only |
|
||
|
| `read_action` | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `sort` | ``any`` | | A sort to be applied to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.max
|
||
|
|
||
|
|
||
|
Declares a named `max` aggregate on the resource
|
||
|
|
||
|
Supports `filter`, but not `sort` (because that wouldn't affect the max)
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
max :first_assigned_ticket_subject, :assigned_tickets, :severity do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.min
|
||
|
|
||
|
|
||
|
Declares a named `min` aggregate on the resource
|
||
|
|
||
|
Supports `filter`, but not `sort` (because that wouldn't affect the min)
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
min :first_assigned_ticket_subject, :assigned_tickets, :severity do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.avg
|
||
|
|
||
|
|
||
|
Declares a named `avg` aggregate on the resource
|
||
|
|
||
|
Supports `filter`, but not `sort` (because that wouldn't affect the avg)
|
||
|
|
||
|
See the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
avg :assigned_ticket_price_sum, :assigned_tickets, :price do
|
||
|
filter [active: true]
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
## aggregates.custom
|
||
|
|
||
|
|
||
|
Declares a named `custom` aggregate on the resource
|
||
|
|
||
|
Supports `filter` and `sort`.
|
||
|
|
||
|
Custom aggregates provide an `implementation` which must implement data layer specific callbacks.
|
||
|
|
||
|
See the relevant data layer documentation and the [aggregates guide](/documentation/topics/aggregates.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
custom :author_names, :authors, :string do
|
||
|
implementation {StringAgg, delimiter: ","}
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field to place the aggregate in |
|
||
|
| `relationship_path`* | ``any`` | | The relationship or relationship path to use for the aggregate |
|
||
|
| `type`* | `module` | | The type of the value returned by the aggregate |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `implementation`* | `module` | | The module that implements the relevant data layer callbacks |
|
||
|
| `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. |
|
||
|
| `kind`* | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate |
|
||
|
| `field` | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource |
|
||
|
| `filter` | ``any`` | [] | A filter to apply to the aggregate |
|
||
|
| `sort` | ``any`` | | A sort to be applied to the aggregate |
|
||
|
| `description` | `String.t` | | An optional description for the aggregate |
|
||
|
| `default` | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. |
|
||
|
| `private?` | `boolean` | false | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the aggregate should be usable in filters. |
|
||
|
| `authorize?` | `boolean` | true | Wether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Aggregate`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## calculations
|
||
|
|
||
|
* [calculate](#calculations-calculate)
|
||
|
* argument
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
calculations do
|
||
|
calculate :full_name, :string, MyApp.MyResource.FullName
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## calculations.calculate
|
||
|
|
||
|
|
||
|
Declares a named calculation on the resource.
|
||
|
|
||
|
Takes a module that must adopt the `Ash.Calculation` behaviour. See that module
|
||
|
for more information.
|
||
|
|
||
|
To ensure that the necessary fields are selected:
|
||
|
|
||
|
1.) Specifying the `select` option on a calculation in the resource.
|
||
|
2.) Define a `select/2` callback in the calculation module
|
||
|
3.) Set `always_select?` on the attribute in question
|
||
|
|
||
|
See the [calculations guide](/documentation/topics/calculations.md) for more.
|
||
|
|
||
|
|
||
|
* [argument](#calculations-calculate-argument)
|
||
|
|
||
|
### Examples
|
||
|
`Ash.Calculation` implementation example:
|
||
|
```
|
||
|
calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}, select: [:first_name, :last_name]
|
||
|
```
|
||
|
|
||
|
`expr/1` example:
|
||
|
```
|
||
|
calculate :full_name, :string, expr(first_name <> " " <> last_name)
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The field name to use for the calculation value |
|
||
|
| `type`* | ``any`` | | The type of the calculation. See `Ash.Type` for more. |
|
||
|
| `calculation`* | `(any, any -> any) \| module \| `any`` | | The `module`, `{module, opts}` or `expr(...)` to use for the calculation. Also accepts a function that takes *a single record* and produces the result. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type. See `Ash.Type` for more. |
|
||
|
| `description` | `String.t` | | An optional description for the calculation |
|
||
|
| `private?` | `boolean` | false | Whether or not the calculation will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. |
|
||
|
| `select` | `list(atom)` | [] | A list of fields to ensure selected if the calculation is used. |
|
||
|
| `load` | ``any`` | [] | A load statement to be applied if the calculation is used. |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the calculation can return nil. |
|
||
|
| `filterable?` | `boolean \| :simple_equality` | true | Whether or not the calculation should be usable in filters. |
|
||
|
|
||
|
|
||
|
## calculations.calculate.argument
|
||
|
|
||
|
|
||
|
An argument to be passed into the calculation's arguments map
|
||
|
|
||
|
See the [calculations guide](/documentation/topics/calculations.md) for more.
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
argument :params, :map do
|
||
|
default %{}
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
```
|
||
|
argument :retries, :integer do
|
||
|
allow_nil? false
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
### Arguments
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `name`* | `atom` | | The name of the argument |
|
||
|
| `type`* | `module` | | The type of the argument. See `Ash.Type` for more. |
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `default` | `(-> any) \| mfa \| any()` | | A default value to use for the argument if not provided |
|
||
|
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil (or may be not provided) |
|
||
|
| `allow_expr?` | `boolean` | false | Allow passing expressions as argument values. Expressions cannot be type validated. |
|
||
|
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. See the type's documentation and `Ash.Type` for more. |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Calculation.Argument`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Introspection
|
||
|
|
||
|
Target: `Ash.Resource.Calculation`
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
## multitenancy
|
||
|
Options for configuring the multitenancy behavior of a resource.
|
||
|
|
||
|
To specify a tenant, use `Ash.Query.set_tenant/2` or
|
||
|
`Ash.Changeset.set_tenant/2` before passing it to an operation.
|
||
|
|
||
|
See the [multitenancy guide](/documentation/topics/multitenancy.md)
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Examples
|
||
|
```
|
||
|
multitenancy do
|
||
|
strategy :attribute
|
||
|
attribute :organization_id
|
||
|
global? true
|
||
|
end
|
||
|
|
||
|
```
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
### Options
|
||
|
| Name | Type | Default | Docs |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `strategy` | `:context \| :attribute` | :context | Determine if multitenancy is performed with attribute filters or using data layer features. |
|
||
|
| `attribute` | `atom` | | If using the `attribute` strategy, the attribute to use, e.g `org_id` |
|
||
|
| `global?` | `boolean` | false | Whether or not the data also exists outside of each tenant. |
|
||
|
| `parse_attribute` | `mfa` | {Ash.Resource.Dsl, :identity, []} | An mfa ({module, function, args}) pointing to a function that takes a tenant and returns the attribute value |
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|