Ash.Resource.Dsl (ash v1.47.6) View Source

Examples:

attribute :first_name, :string do
  primary_key? true
end

:name - The name of the attribute.
:type - The type of the attribute.
:constraints - Constraints to provide to the type when casting the value. See the type's documentation for more information.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:always_select? - Whether or not to always select this attribute when reading from the database. Useful if fields are used in read action preparations consistently.
A primary key attribute cannot be deselected, so this option will have no effect.
Generally, you should favor selecting the field that you need while running your preparation. For example:
```
defmodule MyApp.QueryPreparation.Thing do
use Ash.Resource.Preparation  
def prepare(query, _, _) do
query
|> Ash.Query.select(:attribute_i_need)
|> Ash.Query.after_action(fn query, results ->
  {:ok, Enum.map(results, fn result ->
    do_something_with_attribute_i_need(result)
  end)}
end)
end
end
```
This will prevent unnecessary fields from being selected. The default value is false.
:primary_key? - Whether or not the attribute is part of the primary key (one or more fields that uniquely identify a resource). If primary_key? is true, allow_nil? must be false. The default value is false.
:allow_nil? - Whether or not the attribute can be set to nil. The default value is true.
:generated? - Whether or not the value may be generated by the data layer. If it is, the data layer will know to read the value back after writing. The default value is false.
:writable? - Whether or not the value can be written to. The default value is true.
:private? - Whether or not the attribute will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql. The default value is false.
:update_default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_update/4 sets the default in the changeset if a value is not provided.
:default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_create/4 sets the default in the changeset if a value is not provided.
:description - An optional description for the attribute.

create_timestamp

Declares a non-writable attribute with a create default of &DateTime.utc_now/0

Introspection Target:

Examples:

create_timestamp :inserted_at

:name - The name of the attribute.
:type - The type of the attribute. The default value is Ash.Type.UtcDatetimeUsec.
:constraints - Constraints to provide to the type when casting the value. See the type's documentation for more information.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:always_select? - Whether or not to always select this attribute when reading from the database. Useful if fields are used in read action preparations consistently.
A primary key attribute cannot be deselected, so this option will have no effect.
Generally, you should favor selecting the field that you need while running your preparation. For example:
```
defmodule MyApp.QueryPreparation.Thing do
use Ash.Resource.Preparation  
def prepare(query, _, _) do
query
|> Ash.Query.select(:attribute_i_need)
|> Ash.Query.after_action(fn query, results ->
  {:ok, Enum.map(results, fn result ->
    do_something_with_attribute_i_need(result)
  end)}
end)
end
end
```
This will prevent unnecessary fields from being selected. The default value is false.
:primary_key? - Whether or not the attribute is part of the primary key (one or more fields that uniquely identify a resource). If primary_key? is true, allow_nil? must be false. The default value is false.
:allow_nil? - Whether or not the attribute can be set to nil. The default value is false.
:generated? - Whether or not the value may be generated by the data layer. If it is, the data layer will know to read the value back after writing. The default value is false.
:writable? - Whether or not the value can be written to. The default value is false.
:private? - Whether or not the attribute will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql. The default value is true.
:update_default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_update/4 sets the default in the changeset if a value is not provided.
:default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_create/4 sets the default in the changeset if a value is not provided. The default value is &DateTime.utc_now/0.
:description - An optional description for the attribute.

update_timestamp

Declares a non-writable attribute with a create and update default of &DateTime.utc_now/0

Introspection Target:

Examples:

update_timestamp :inserted_at

:name - The name of the attribute.
:type - The type of the attribute. The default value is Ash.Type.UtcDatetimeUsec.
:constraints - Constraints to provide to the type when casting the value. See the type's documentation for more information.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:always_select? - Whether or not to always select this attribute when reading from the database. Useful if fields are used in read action preparations consistently.
A primary key attribute cannot be deselected, so this option will have no effect.
Generally, you should favor selecting the field that you need while running your preparation. For example:
```
defmodule MyApp.QueryPreparation.Thing do
use Ash.Resource.Preparation  
def prepare(query, _, _) do
query
|> Ash.Query.select(:attribute_i_need)
|> Ash.Query.after_action(fn query, results ->
  {:ok, Enum.map(results, fn result ->
    do_something_with_attribute_i_need(result)
  end)}
end)
end
end
```
This will prevent unnecessary fields from being selected. The default value is false.
:primary_key? - Whether or not the attribute is part of the primary key (one or more fields that uniquely identify a resource). If primary_key? is true, allow_nil? must be false. The default value is false.
:allow_nil? - Whether or not the attribute can be set to nil. The default value is false.
:generated? - Whether or not the value may be generated by the data layer. If it is, the data layer will know to read the value back after writing. The default value is false.
:writable? - Whether or not the value can be written to. The default value is false.
:private? - Whether or not the attribute will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql. The default value is true.
:update_default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_update/4 sets the default in the changeset if a value is not provided. The default value is &DateTime.utc_now/0.
:default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_create/4 sets the default in the changeset if a value is not provided. The default value is &DateTime.utc_now/0.
:description - An optional description for the attribute.

timestamps

Declares non-writable inserted_at and updated_at attributes whith create and update defaults of &DateTime.utc_now/0.

Introspection Target:

Examples:

timestamps()

integer_primary_key

Declares a generated (set by the data layer), non writable, non nil, primary key column of type integer. Using integer_primary_key, allow_nil? is automatically set to false.

Introspection Target:

Examples:

integer_primary_key :id

:name - The name of the attribute.
:type - The type of the attribute. The default value is Ash.Type.Integer.
:constraints - Constraints to provide to the type when casting the value. See the type's documentation for more information.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:always_select? - Whether or not to always select this attribute when reading from the database. Useful if fields are used in read action preparations consistently.
A primary key attribute cannot be deselected, so this option will have no effect.
Generally, you should favor selecting the field that you need while running your preparation. For example:
```
defmodule MyApp.QueryPreparation.Thing do
use Ash.Resource.Preparation  
def prepare(query, _, _) do
query
|> Ash.Query.select(:attribute_i_need)
|> Ash.Query.after_action(fn query, results ->
  {:ok, Enum.map(results, fn result ->
    do_something_with_attribute_i_need(result)
  end)}
end)
end
end
```
This will prevent unnecessary fields from being selected. The default value is false.
:primary_key? - Whether or not the attribute is part of the primary key (one or more fields that uniquely identify a resource). If primary_key? is true, allow_nil? must be false. The default value is true.
:generated? - Whether or not the value may be generated by the data layer. If it is, the data layer will know to read the value back after writing. The default value is true.
:writable? - Whether or not the value can be written to. The default value is false.
:private? - Whether or not the attribute will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql. The default value is false.
:update_default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_update/4 sets the default in the changeset if a value is not provided.
:default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_create/4 sets the default in the changeset if a value is not provided.
:description - An optional description for the attribute.

uuid_primary_key

Declares a non writable, non nil, primary key column of type uuid, which defaults to Ash.UUID.generate/0. Using uuid_primary_key, allow_nil? is automatically set to false.

Introspection Target:

Ash.Resource.Relationships.HasOne

Examples:

uuid_primary_key :id

:name - The name of the attribute.
:type - The type of the attribute. The default value is Ash.Type.UUID.
:constraints - Constraints to provide to the type when casting the value. See the type's documentation for more information.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:always_select? - Whether or not to always select this attribute when reading from the database. Useful if fields are used in read action preparations consistently.
A primary key attribute cannot be deselected, so this option will have no effect.
Generally, you should favor selecting the field that you need while running your preparation. For example:
```
defmodule MyApp.QueryPreparation.Thing do
use Ash.Resource.Preparation  
def prepare(query, _, _) do
query
|> Ash.Query.select(:attribute_i_need)
|> Ash.Query.after_action(fn query, results ->
  {:ok, Enum.map(results, fn result ->
    do_something_with_attribute_i_need(result)
  end)}
end)
end
end
```
This will prevent unnecessary fields from being selected. The default value is false.
:primary_key? - Whether or not the attribute is part of the primary key (one or more fields that uniquely identify a resource). If primary_key? is true, allow_nil? must be false. The default value is true.
:generated? - Whether or not the value may be generated by the data layer. If it is, the data layer will know to read the value back after writing. The default value is false.
:writable? - Whether or not the value can be written to. The default value is false.
:private? - Whether or not the attribute will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql. The default value is false.
:update_default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_update/4 sets the default in the changeset if a value is not provided.
:default - A zero argument function, an {mod, fun, args} triple or a value. Ash.Changeset.for_create/4 sets the default in the changeset if a value is not provided. The default value is &Ash.UUID.generate/0.
:description - An optional description for the attribute.

relationships

A section for declaring relationships on the resource.

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

has_one
has_many
many_to_many
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_field_on_join_table :category_id
    source_field_on_join_table :post_id
  end
end

relationships do
  has_many :posts, MyApp.Post do
    destination_field :author_id
  end

  has_many :composite_key_posts, MyApp.CompositeKeyPost do
    destination_field :author_id
  end
end

Imports:

Ash.Filter.TemplateHelpers

has_one

Declares a has_one relationship. In a relationsal 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.

Introspection Target:

Examples:

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

:required? - Marks the relationship as required. This is not currently validated anywhere, since the relationship is managed by the destination, but ash_graphql uses it for type information, and it can be used for expressiveness.
:name - The name of the relationship
:destination - The destination resource
:destination_field - The field on the related resource that should match the source_field on this resource.
:validate_destination_field? - Whether or not to validate that the destination field exists on the destination resource The default value is true.
:source_field - The field on this resource that should match the destination_field on the related resource. The default value is :id.
:writable? - Whether or not the relationship may be edited. The default value is true.
:description - An optional description for the relationship
:relationship_context - Context to be set on any queries or changesets generated for this relationship.
This is used by ash_postgres for polymorphic resources.
:private? - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.
:not_found_message - A message to show if there is a conflict with this relationship in the database on update or create.
For example, if a value is added that has no match in the destination (very hard to do with the way Ash relationship changes work).
:read_action - The read action on the destination resource to use when loading data.
Keep in mind, any filters that exist on the destination action are not honored when filtering on this relationship. The only time the read action comes into play is when loading the actual relationship, which happens when they are loaded explicitly and when the relationship is managed.
:filter - A filter to be applied when reading the relationship.
:sort - A sort statement to be applied when reading the relationship.
:violation_message - A message to show if there is a conflict with this relationship in the database on destroy. For example, if a record is deleted while related records still exist (and aren't configured to cascade deletes)

has_many

Declares a has_many relationship. There can be any number of related entities.

Introspection Target:

Ash.Resource.Relationships.HasMany

Examples:

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

:name - The name of the relationship
:destination - The destination resource
:destination_field - The field on the related resource that should match the source_field on this resource.
:validate_destination_field? - Whether or not to validate that the destination field exists on the destination resource The default value is true.
:source_field - The field on this resource that should match the destination_field on the related resource. The default value is :id.
:writable? - Whether or not the relationship may be edited. The default value is true.
:description - An optional description for the relationship
:relationship_context - Context to be set on any queries or changesets generated for this relationship.
This is used by ash_postgres for polymorphic resources.
:private? - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.
:not_found_message - A message to show if there is a conflict with this relationship in the database on update or create.
For example, if a value is added that has no match in the destination (very hard to do with the way Ash relationship changes work).
:read_action - The read action on the destination resource to use when loading data.
Keep in mind, any filters that exist on the destination action are not honored when filtering on this relationship. The only time the read action comes into play is when loading the actual relationship, which happens when they are loaded explicitly and when the relationship is managed.
:filter - A filter to be applied when reading the relationship.
:sort - A sort statement to be applied when reading the relationship.
:violation_message - A message to show if there is a conflict with this relationship in the database on destroy. For example, if a record is deleted while related records still exist (and aren't configured to cascade deletes)

many_to_many

Declares a many_to_many relationship. Many to many relationships require a join table.

A join table is typically a table who's primary key consists of one foreign key to each resource.

Introspection Target:

Ash.Resource.Relationships.ManyToMany

Examples:

# In a resource called `Word`
many_to_many :books, Book do
  through BookWord
  source_field :text
  source_field_on_join_table :word_text
  destination_field :id
  destination_field_on_join_table :book_id
end

# And in `BookWord` (the resource that defines the join table)
belongs_to :book, Book, primary_key?: true, required?: true
belongs_to :word, Word, primary_key?: true, required?: true

:source_field_on_join_table - Required. The field on the join table that should line up with source_field on this resource.
:destination_field_on_join_table - Required. The field on the join table that should line up with destination_field on the related resource.
:through - Required. The resource to use as the join resource.
:join_relationship - The has_many relationship to the join table. Defaults to <relationship_name>_join_assoc
:join_attributes - Attributes to expose as editable when modifying the relationship.
Extensions may use this when deciding what fields to render from the join table.
See Ash.Changeset.append_to_relationship/3 and Ash.Changeset.replace_relationship/3 for how to edit these fields. The default value is [].
:name - The name of the relationship
:destination - The destination resource
:destination_field - The field on the related resource that should match the source_field on this resource. The default value is :id.
:validate_destination_field? - Whether or not to validate that the destination field exists on the destination resource The default value is true.
:source_field - The field on this resource that should match the destination_field on the related resource. The default value is :id.
:writable? - Whether or not the relationship may be edited. The default value is true.
:description - An optional description for the relationship
:relationship_context - Context to be set on any queries or changesets generated for this relationship.
This is used by ash_postgres for polymorphic resources.
:private? - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.
:not_found_message - A message to show if there is a conflict with this relationship in the database on update or create.
For example, if a value is added that has no match in the destination (very hard to do with the way Ash relationship changes work).
:read_action - The read action on the destination resource to use when loading data.
Keep in mind, any filters that exist on the destination action are not honored when filtering on this relationship. The only time the read action comes into play is when loading the actual relationship, which happens when they are loaded explicitly and when the relationship is managed.
:filter - A filter to be applied when reading the relationship.
:sort - A sort statement to be applied when reading the relationship.
:violation_message - A message to show if there is a conflict with this relationship in the database on destroy. For example, if a record is deleted while related records still exist (and aren't configured to cascade deletes)

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_field?: false is provided.

Introspection Target:

Ash.Resource.Relationships.BelongsTo

Examples:

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

:primary_key? - Whether this field is, or is part of, the primary key of a resource. The default value is false.
:required? - Whether this relationship must always be present, e.g: must be included on creation, and never removed (it can still be changed) The default value is false.
:define_field? - If set to false a field is not created on the resource for this relationship, and one must be manually added in attributes. The default value is true.
:field_type - The field type of the automatically created field. The default value is :uuid.
:name - The name of the relationship
:destination - The destination resource
:destination_field - The field on the related resource that should match the source_field on this resource. The default value is :id.
:validate_destination_field? - Whether or not to validate that the destination field exists on the destination resource The default value is true.
:source_field - The field on this resource that should match the destination_field on the related resource. - Defaults to <name>_id
:writable? - Whether or not the relationship may be edited. The default value is true.
:description - An optional description for the relationship
:relationship_context - Context to be set on any queries or changesets generated for this relationship.
This is used by ash_postgres for polymorphic resources.
:private? - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.
:not_found_message - A message to show if there is a conflict with this relationship in the database on update or create.
For example, if a value is added that has no match in the destination (very hard to do with the way Ash relationship changes work).
:read_action - The read action on the destination resource to use when loading data.
Keep in mind, any filters that exist on the destination action are not honored when filtering on this relationship. The only time the read action comes into play is when loading the actual relationship, which happens when they are loaded explicitly and when the relationship is managed.
:filter - A filter to be applied when reading the relationship.
:sort - A sort statement to be applied when reading the relationship.
:violation_message - A message to show if there is a conflict with this relationship in the database on destroy. For example, if a record is deleted while related records still exist (and aren't configured to cascade deletes)

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.

Primary actions

If you have multiple actions of the same type, one of them must be designated as the primary action for that type, via the primary? option. This tells the ash what to do if an action of that type is requested, but no specific action name is given. This is how many relationship changes will happen, by utilizing the primary actions. For this reason, when defining actions, you usually want to ensure that the primary action takes no required arguments . Without that, relationship changes to your resources might fail due to missing arguments. This does, however, allow you to customize exactly how related entities are read/ created.

create
- change
- validate
- argument
read
- argument
- prepare
update
- change
- validate
- argument
destroy
- change
- validate
- 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

Imports:

:defaults - By default, an action of each type is added to each resource.
If any other actions of that same type are added, the default of that type is not added. If you wish to skip adding defaults of certain types, specify this option with the defaults that you do want implemented. The default value is [:create, :read, :update, :destroy].

create

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

change
validate
argument

Introspection Target:

Ash.Resource.Actions.Create

Examples:

create :register do
  primary? true
end

:allow_nil_input - A list of attributes that would normally be required, but should not be for this action.
This exists because extensions like ash_graphql and ash_json_api will add non-null validations to their input for any attribute that is accepted by an action that has allow_nil?: false. This tells those extensions that some change on the resource might set that attribute, and so they should not require it at the API layer.
Ash core doesn't actually use the values in this list, because it does its nil validation after running all resource changes. If the value is still nil by the time Ash would submit to the data layer, then an error is returned.
:name - Required. The name of the action
:primary? - Whether or not this action should be used when no action is specified by the caller. The default value is false.
:description - An optional description for the action
:accept - The list of attributes to accept. Defaults to all attributes on the resource
:reject - A list of attributes not to accept. This is useful if you want to say 'accept all but x'
If this is specified along with accept, then everything in the accept list minus any matches in the reject list will be accepted.
:require_attributes - A list of attributes that would normally allow_nil to require for this action.
No need to include attributes that are allow_nil?: false.
:error_handler - Sets the error handler on the changeset. See Ash.Changeset.handle_errors/2 for more
:manual? - Instructs Ash to skip the actual update/create/destroy step.
All validation still takes place, but the result in any after_action callbacks attached to that action will simply be the record that was read from the database initially. For creates, the result will be nil, and you will be expected to handle the changeset in an after_action callback and return an instance of the record. This is a good way to prevent Ash from issuing an unnecessary update to the record, e.g updating the updated_at of the record when an action actually only involves modifying relating records.
You could then handle the changeset automatically.
For example:
in the action
```
action :special_create do
manual? true
change MyApp.DoCreate
end  
# The change
defmodule MyApp.DoCreate do
use Ash.Resource.Change  
def change(changeset, _, _) do
Ash.Changeset.after_action(changeset, fn changeset, _result ->
  # result will be `nil`, because this is a manual action  
  result = do_something_that_creates_the_record(changeset)  
  {:ok, result}
end)
end
end
```

change

A change to be applied to the changeset after it is generated. They are run in order, from top to bottom.

To implement your own, see Ash.Resource.Change. To use it, you can simply refer to the module and its options, like so:

change {MyChange, foo: 1}

But for readability, you may want to define a function elsewhere and import it, so you can say something like:

change my_change(1)

For destroys, changes are not applied unless soft? is set to true.

Introspection Target:

Ash.Resource.Change

Examples:

change relate_actor(:reporter)

change {MyCustomChange, :foo}

:change - Required. The module and options for a change.

validate

Declares a validation for the current action

Introspection Target:

Examples:

validate changing(:email)

:validation - Required. The module/opts pair of the validation
:expensive? - If a validation is expensive, it won't be run on invalid changes. All inexpensive validations are always run, to provide informative errors. The default value is false.
:message - If provided, overrides any message set by the validation error
:description - An optional description for the validation
:before_action? - If set to true, the validation is not run when building changesets using Ash.Changeset.for_*. The validation will only ever be run once the action itself is called. The default value is false.

argument

Declares an argument on the action

The type can be either a built in type (see Ash.Type) for more, or a module implementing the Ash.Type behaviour.

Introspection Target:

Ash.Resource.Actions.Read

Examples:

argument :password_confirmation, :string

:allow_nil? - Whether or not the argument may be ommitted or set to nil The default value is true.
:type - Required. The type of the argument
:name - Required. The name of the argument
:private? - Whether or not the argument should be part of the public API The default value is false.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:default - The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value
:constraints - Type constraints on the argument The default value is [].
:description - An optional description for the argument.

read

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

Pagination

:keyset? - Whether or not keyset based pagination is supported The default value is false.
:offset? - Whether or not offset based pagination is supported The default value is false.
:default_limit - The default page size to apply, if one is not supplied
:countable - Whether not a returned page will have a full count of all records. Use :by_default to do it automatically. The default value is false.
:max_page_size - The maximum amount of records that can be requested in a single page The default value is 250.
:required? - Whether or not pagination can be disabled. Only relevant if some pagination configuration is supplied. The default value is true.
argument
prepare

Introspection Target:

Examples:

read :read_all do
  primary? true
end

:filter - A filter template, that may contain actor references. See Ash.Filter for more on templates
:transaction? - Whether or not this read action should happen in a transaction.
Only relevant if the data layer supports transactions.
This is useful for cases where you have read actions with preparations that create data in before_action or after_action and you want those operations to happen in the same transaction as the read. The default value is false.
:pagination - Options for how the action should support pagination. See the pagination section for more information. The default value is false.
:name - Required. The name of the action
:primary? - Whether or not this action should be used when no action is specified by the caller. The default value is false.
:description - An optional description for the action

argument

Declares an argument on the action

The type can be either a built in type (see Ash.Type) for more, or a module implementing the Ash.Type behaviour.

Introspection Target:

Ash.Resource.Preparation

Examples:

argument :password_confirmation, :string

:allow_nil? - Whether or not the argument may be ommitted or set to nil The default value is true.
:type - Required. The type of the argument
:name - Required. The name of the argument
:private? - Whether or not the argument should be part of the public API The default value is false.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:default - The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value
:constraints - Type constraints on the argument The default value is [].
:description - An optional description for the argument.

prepare

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

Introspection Target:

Examples:

prepare default_sort([:foo, :bar])

:preparation - Required. The module and options for a preparation.

update

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

change
validate
argument

Introspection Target:

Ash.Resource.Actions.Update

Examples:

update :flag_for_review, primary?: true

:name - Required. The name of the action
:primary? - Whether or not this action should be used when no action is specified by the caller. The default value is false.
:description - An optional description for the action
:accept - The list of attributes to accept. Defaults to all attributes on the resource
:reject - A list of attributes not to accept. This is useful if you want to say 'accept all but x'
If this is specified along with accept, then everything in the accept list minus any matches in the reject list will be accepted.
:require_attributes - A list of attributes that would normally allow_nil to require for this action.
No need to include attributes that are allow_nil?: false.
:error_handler - Sets the error handler on the changeset. See Ash.Changeset.handle_errors/2 for more
:manual? - Instructs Ash to skip the actual update/create/destroy step.
All validation still takes place, but the result in any after_action callbacks attached to that action will simply be the record that was read from the database initially. For creates, the result will be nil, and you will be expected to handle the changeset in an after_action callback and return an instance of the record. This is a good way to prevent Ash from issuing an unnecessary update to the record, e.g updating the updated_at of the record when an action actually only involves modifying relating records.
You could then handle the changeset automatically.
For example:
in the action
```
action :special_create do
manual? true
change MyApp.DoCreate
end  
# The change
defmodule MyApp.DoCreate do
use Ash.Resource.Change  
def change(changeset, _, _) do
Ash.Changeset.after_action(changeset, fn changeset, _result ->
  # result will be `nil`, because this is a manual action  
  result = do_something_that_creates_the_record(changeset)  
  {:ok, result}
end)
end
end
```

change

A change to be applied to the changeset after it is generated. They are run in order, from top to bottom.

To implement your own, see Ash.Resource.Change. To use it, you can simply refer to the module and its options, like so:

change {MyChange, foo: 1}

But for readability, you may want to define a function elsewhere and import it, so you can say something like:

change my_change(1)

For destroys, changes are not applied unless soft? is set to true.

Introspection Target:

Ash.Resource.Change

Examples:

change relate_actor(:reporter)

change {MyCustomChange, :foo}

:change - Required. The module and options for a change.

validate

Declares a validation for the current action

Introspection Target:

Examples:

validate changing(:email)

:validation - Required. The module/opts pair of the validation
:expensive? - If a validation is expensive, it won't be run on invalid changes. All inexpensive validations are always run, to provide informative errors. The default value is false.
:message - If provided, overrides any message set by the validation error
:description - An optional description for the validation
:before_action? - If set to true, the validation is not run when building changesets using Ash.Changeset.for_*. The validation will only ever be run once the action itself is called. The default value is false.

argument

Declares an argument on the action

The type can be either a built in type (see Ash.Type) for more, or a module implementing the Ash.Type behaviour.

Introspection Target:

Ash.Resource.Actions.Destroy

Examples:

argument :password_confirmation, :string

:allow_nil? - Whether or not the argument may be ommitted or set to nil The default value is true.
:type - Required. The type of the argument
:name - Required. The name of the argument
:private? - Whether or not the argument should be part of the public API The default value is false.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:default - The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value
:constraints - Type constraints on the argument The default value is [].
:description - An optional description for the argument.

destroy

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

change
validate
argument

Introspection Target:

Examples:

destroy :soft_delete do
  primary? true
end

:soft? - If specified, the destroy action calls the datalayer's update function with any specified changes.
:name - Required. The name of the action
:primary? - Whether or not this action should be used when no action is specified by the caller. The default value is false.
:description - An optional description for the action
:accept - The list of attributes to accept. Defaults to all attributes on the resource
:reject - A list of attributes not to accept. This is useful if you want to say 'accept all but x'
If this is specified along with accept, then everything in the accept list minus any matches in the reject list will be accepted.
:require_attributes - A list of attributes that would normally allow_nil to require for this action.
No need to include attributes that are allow_nil?: false.
:error_handler - Sets the error handler on the changeset. See Ash.Changeset.handle_errors/2 for more
:manual? - Instructs Ash to skip the actual update/create/destroy step.
All validation still takes place, but the result in any after_action callbacks attached to that action will simply be the record that was read from the database initially. For creates, the result will be nil, and you will be expected to handle the changeset in an after_action callback and return an instance of the record. This is a good way to prevent Ash from issuing an unnecessary update to the record, e.g updating the updated_at of the record when an action actually only involves modifying relating records.
You could then handle the changeset automatically.
For example:
in the action
```
action :special_create do
manual? true
change MyApp.DoCreate
end  
# The change
defmodule MyApp.DoCreate do
use Ash.Resource.Change  
def change(changeset, _, _) do
Ash.Changeset.after_action(changeset, fn changeset, _result ->
  # result will be `nil`, because this is a manual action  
  result = do_something_that_creates_the_record(changeset)  
  {:ok, result}
end)
end
end
```

change

A change to be applied to the changeset after it is generated. They are run in order, from top to bottom.

To implement your own, see Ash.Resource.Change. To use it, you can simply refer to the module and its options, like so:

change {MyChange, foo: 1}

But for readability, you may want to define a function elsewhere and import it, so you can say something like:

change my_change(1)

For destroys, changes are not applied unless soft? is set to true.

Introspection Target:

Ash.Resource.Change

Examples:

change relate_actor(:reporter)

change {MyCustomChange, :foo}

:change - Required. The module and options for a change.

validate

Declares a validation for the current action

Introspection Target:

Examples:

validate changing(:email)

:validation - Required. The module/opts pair of the validation
:expensive? - If a validation is expensive, it won't be run on invalid changes. All inexpensive validations are always run, to provide informative errors. The default value is false.
:message - If provided, overrides any message set by the validation error
:description - An optional description for the validation
:before_action? - If set to true, the validation is not run when building changesets using Ash.Changeset.for_*. The validation will only ever be run once the action itself is called. The default value is false.

argument

Declares an argument on the action

The type can be either a built in type (see Ash.Type) for more, or a module implementing the Ash.Type behaviour.

Introspection Target:

Examples:

argument :password_confirmation, :string

:allow_nil? - Whether or not the argument may be ommitted or set to nil The default value is true.
:type - Required. The type of the argument
:name - Required. The name of the argument
:private? - Whether or not the argument should be part of the public API The default value is false.
:sensitive? - Whether or not the attribute value contains sensitive information, like PII. If so, it will be redacted while inspecting data. The default value is false.
:default - The default value for the argument to take. It can be a zero argument function e.g &MyMod.my_fun/0 or a value
:constraints - Type constraints on the argument The default value is [].
:description - An optional description for the argument.

resource

Resource-wide configuration

Examples:

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

Imports:

Ash.Filter.TemplateHelpers

:description - A human readable description of the resource, to be used in generated documentation
:base_filter - A filter statement to be applied to any queries on the resource
:default_context - Default context to apply to any queries/changesets generated for this resource.

validations

Declare validations prior to performing actions against the resource

validate

Examples:

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

Imports:

Ash.Resource.Validation.Builtins

validate

Declares a validation for creates and updates.

Introspection Target:

Examples:

validate {Mod, [foo: :bar]}

validate at_least_one_of_present([:first_name, :last_name])

:validation - Required. The module/opts pair of the validation
:on - The action types the validation should run on.
Many validations don't make sense in the context of deletion, so by default it is left out of the list. The default value is [:create, :update].
:expensive? - If a validation is expensive, it won't be run on invalid changes. All inexpensive validations are always run, to provide informative errors. The default value is false.
:message - If provided, overrides any message set by the validation error
:description - An optional description for the validation
:before_action? - If set to true, the validation is not run when building changesets using Ash.Changeset.for_*. The validation will only ever be run once the action itself is called. The default value is false.

aggregates

Declare named aggregates on the resource.

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

count
first
sum
list

Examples:

aggregates do
  count :assigned_ticket_count, :reported_tickets do
    filter [active: true]
  end
end

Imports:

Ash.Filter.TemplateHelpers

count

Declares a named count aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the count)

Introspection Target:

Examples:

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

:name - Required. The field to place the aggregate in
:relationship_path - Required. The relationship or relationship path to use for the aggregate
:kind - Required. The kind of the aggregate
:field - false The field to aggregate. Defaults to the first field in the primary key of the resource
:filter - A filter to apply to the aggregate The default value is [].
:description - An optional description for the aggregate
:private? - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.

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.

Introspection Target:

Examples:

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

:name - Required. The field to place the aggregate in
:relationship_path - Required. The relationship or relationship path to use for the aggregate
:kind - Required. The kind of the aggregate
:field - false The field to aggregate. Defaults to the first field in the primary key of the resource
:filter - A filter to apply to the aggregate The default value is [].
:sort - A sort to be applied to the aggregate
:description - An optional description for the aggregate
:private? - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.

sum

Declares a named sum aggregate on the resource

Supports filter, but not sort (because that wouldn't affect the sum)

Introspection Target:

Examples:

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

:name - Required. The field to place the aggregate in
:relationship_path - Required. The relationship or relationship path to use for the aggregate
:kind - Required. The kind of the aggregate
:field - false The field to aggregate. Defaults to the first field in the primary key of the resource
:filter - A filter to apply to the aggregate The default value is [].
:description - An optional description for the aggregate
:private? - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value is false.

list

Declares a named list aggregate on the resource.

A list aggregate simply selects the list of all values for the given field and relationship combination.

Introspection Target: