View Source Ash.Resource.Dsl (ash v2.7.1)
The built in resource DSL.
dsl-documentation
DSL Documentation
index
Index
- attributes
- attribute
- create_timestamp
- update_timestamp
- integer_primary_key
- uuid_primary_key
- relationships
- has_one
- has_many
- many_to_many
- belongs_to
- actions
- create
- change
- validate
- argument
- metadata
- read
- argument
- prepare
- pagination
- metadata
- update
- change
- validate
- metadata
- argument
- destroy
- change
- validate
- metadata
- argument
- create
- code_interface
- define
- define_calculation
- resource
- identities
- identity
- changes
- change
- preparations
- prepare
- validations
- validate
- aggregates
- count
- first
- sum
- list
- max
- min
- avg
- custom
- calculations
- calculate
- argument
- calculate
- multitenancy
docs
Docs
attributes
attributes
A section for declaring attributes on the resource.
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
Imports:
attribute
attribute
Declares an attribute on the resource.
Examples:
attribute :name, :string do
allow_nil? false
end
:name
(atom/0
) - The name of the attribute.:type
(term/0
) - The type of the attribute. SeeAsh.Type
for more.:constraints
(keyword/0
) - Constraints to provide to the type when casting the value. For more information see the specific type's documentation, for general type information seeAsh.Type
and for practical example see the constraints topic.:description
(String.t/0
) - An optional description for the attribute.:sensitive?
(boolean/0
) - Whether or not the attribute value contains sensitive information, like PII. Using this option will cause the attribute to be** Redacted **
from the resource when logging or inspecting. See the Security guide for more. The default value isfalse
.:source
(atom/0
) - If the field should be mapped to a different name in the data layer. Support varies by data layer.:always_select?
(boolean/0
) - Whether or not to ensure this attribute is always selected when reading from the database.
When this option is true and performing a read action, the attribute will always be selected even if it was explicitly selected out of the query. For example say there is a resource with two attributes:foo
and:bar
. Say:foo
hasalways_select? true
set. The queryAsh.Query.select(MyResource, [:bar])
would return both:foo
and:bar
even though:foo
was not selected in the query. The default value isfalse
.:primary_key?
(boolean/0
) - Whether the attribute is the primary key. Composite primary key is also possible by usingprimary_key? true
in more than one attribute. If primary_key? is true, allow_nil? must be false. The default value isfalse
.:allow_nil?
(boolean/0
) - Whether or not the attribute can be set to nil. If nil value is given error is raised. The default value istrue
.:generated?
(boolean/0
) - Whether or not the value may be generated by the data layer. The default value isfalse
.:writable?
(boolean/0
) - Whether or not the value can be written to. Ifwritable? false
then attribute is read-only and cannot be written to even when creating a record. This can be overridden withAsh.Changeset.force_change_attribute/3
. The default value istrue
.:private?
(boolean/0
) - Ifprivate? true
then attribute is read-only and cannot be written to even when creating a record. Additionally it tells other extensions (e.g. AshJsonApi or AshGraphql) not to expose these attributes through the API. The value of the attribute can be overridden withAsh.Changeset.force_change_attribute/3
.
See the security guide for more. The default value isfalse
.:default
- A value to be set on all creates, unless a value is being provided already.:update_default
- A value to be set on all updates, unless a value is being provided already.:filterable?
- Whether or not the attribute can be referenced in filters. Can be used to prevent filtering on large text columns with no indexing. The default value istrue
.:match_other_defaults?
(boolean/0
) - Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unlessdefault
is a zero argument function. For example, create and update timestamps use this option, and have the same lazy function&DateTime.utc_now/0
, so they get the same value, instead of having slightly different timestamps. The default value isfalse
.
create_timestamp
create_timestamp
Declares a non-writable attribute with a create default of &DateTime.utc_now/0
Accepts all the same options as 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
:name
(atom/0
) - The name of the attribute.
update_timestamp
update_timestamp
Declares a non-writable attribute with a create and update default of &DateTime.utc_now/0
Accepts all the same options as 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
:name
(atom/0
) - The name of the attribute.
integer_primary_key
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 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
:name
(atom/0
) - The name of the attribute.
uuid_primary_key
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 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
:name
(atom/0
) - The name of the attribute.
relationships
relationships
A section for declaring relationships on the resource.
Relationships are a core component of resource oriented design. Many components of Ash
will use these relationships. A simple use case is loading relationships (done via the Ash.Query.load/2
).
See the relationships guide for more.
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
Imports:
has_one
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 for more.
Examples:
# In a resource called `Word`
has_one :dictionary_entry, DictionaryEntry do
source_attribute :text
destination_attribute :word_text
end
:manual
- A module that implementsAsh.Resource.ManualRelationship
. Also accepts a 2 argument function that takes the source records and the context.:no_attributes?
(boolean/0
) - If true, all existing entities are considered related, i.e this relationship is not based on any fields, andsource_attribute
anddestination_attribute
are ignored.
This can be very useful when combined with multitenancy. Specifically, if you have a tenant resource likeOrganization
, you can useno_attributes?
to do things likehas_many :employees, Employee, no_attributes?: true
, which lets you avoid having an unnecessaryorganization_id
field onEmployee
. The same works in reverse:has_one :organization, Organization, no_attributes?: true
allows relating the employee to their organization.
Some important caveats here:- You can still manage relationships from one to the other, but "relate" and "unrelate" will have no effect, because there are no fields to change.
- Loading the relationship on a list of resources will not behave as expected in all circumstances involving multitenancy. For example,
if you get a list of
Organization
and then try to loademployees
, you would need to set a single tenant on the load query, meaning you'll get all organizations back with the set of employees from one tenant. This could eventually be solved, but for now it is considered an edge case.
:allow_nil?
(boolean/0
) - Marks the relationship as required. Has no effect on validations, but can inform extensions that there will always be a related entity. The default value istrue
.:name
(atom/0
) - The name of the relationship:destination
(atom/0
) - The destination resource:description
(String.t/0
) - An optional description for the relationship:destination_attribute
(atom/0
) - The attribute on the related resource that should match thesource_attribute
configured on this resource.:validate_destination_attribute?
(boolean/0
) - Whether or not to validate that the destination field exists on the destination resource The default value istrue
.:source_attribute
(atom/0
) - The field on this resource that should match thedestination_attribute
on the related resource. The default value is:id
.:relationship_context
(term/0
) - Context to be set on any queries or changesets generated for managing or querying this relationship.:private?
(boolean/0
) - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
See the security guide for more. The default value isfalse
.:not_found_message
(String.t/0
) - 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/0
) - Whether or not the relationship may be managed. The default value istrue
.:read_action
(atom/0
) - The read action on the destination resource to use when loading data and filtering.:api
(atom/0
) - The API module to use when working with the related entity.:filter
(term/0
) - A filter to be applied when reading the relationship.:filterable?
(boolean/0
) - If set tofalse
, the relationship will not be usable in filters. The default value istrue
.:sort
(term/0
) - A sort statement to be applied when loading the relationship.:could_be_related_at_creation?
(boolean/0
) - Whether or not related values may exist for this relationship at creation. The default value isfalse
.:violation_message
(String.t/0
) - 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
has_many
Declares a has_many relationship. There can be any number of related entities.
See the relationships guide for more.
Examples:
# In a resource called `Word`
has_many :definitions, DictionaryDefinition do
source_attribute :text
destination_attribute :word_text
end
:manual
- A module that implementsAsh.Resource.ManualRelationship
. Also accepts a 2 argument function that takes the source records and the context.:no_attributes?
(boolean/0
) - If true, all existing entities are considered related, i.e this relationship is not based on any fields, andsource_attribute
anddestination_attribute
are ignored.
This can be very useful when combined with multitenancy. Specifically, if you have a tenant resource likeOrganization
, you can useno_attributes?
to do things likehas_many :employees, Employee, no_attributes?: true
, which lets you avoid having an unnecessaryorganization_id
field onEmployee
. The same works in reverse:has_one :organization, Organization, no_attributes?: true
allows relating the employee to their organization.
Some important caveats here:- You can still manage relationships from one to the other, but "relate" and "unrelate" will have no effect, because there are no fields to change.
- Loading the relationship on a list of resources will not behave as expected in all circumstances involving multitenancy. For example,
if you get a list of
Organization
and then try to loademployees
, you would need to set a single tenant on the load query, meaning you'll get all organizations back with the set of employees from one tenant. This could eventually be solved, but for now it is considered an edge case.
:name
(atom/0
) - The name of the relationship:destination
(atom/0
) - The destination resource:description
(String.t/0
) - An optional description for the relationship:destination_attribute
(atom/0
) - The attribute on the related resource that should match thesource_attribute
configured on this resource.:validate_destination_attribute?
(boolean/0
) - Whether or not to validate that the destination field exists on the destination resource The default value istrue
.:source_attribute
(atom/0
) - The field on this resource that should match thedestination_attribute
on the related resource. The default value is:id
.:relationship_context
(term/0
) - Context to be set on any queries or changesets generated for managing or querying this relationship.:private?
(boolean/0
) - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
See the security guide for more. The default value isfalse
.:not_found_message
(String.t/0
) - 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/0
) - Whether or not the relationship may be managed. The default value istrue
.:read_action
(atom/0
) - The read action on the destination resource to use when loading data and filtering.:api
(atom/0
) - The API module to use when working with the related entity.:filter
(term/0
) - A filter to be applied when reading the relationship.:filterable?
(boolean/0
) - If set tofalse
, the relationship will not be usable in filters. The default value istrue
.:sort
(term/0
) - A sort statement to be applied when loading the relationship.:could_be_related_at_creation?
(boolean/0
) - Whether or not related values may exist for this relationship at creation. The default value isfalse
.:violation_message
(String.t/0
) - 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
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 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
:source_attribute_on_join_resource
(atom/0
) - Required. The attribute on the join resource that should line up withsource_attribute
on this resource.:destination_attribute_on_join_resource
(atom/0
) - Required. The attribute on the join resource that should line up withdestination_attribute
on the related resource.:through
(atom/0
) - Required. The resource to use as the join resource.:join_relationship
(atom/0
) - The has_many relationship to the join resource. Defaults to <relationship_name>_join_assoc:name
(atom/0
) - The name of the relationship:destination
(atom/0
) - The destination resource:description
(String.t/0
) - An optional description for the relationship:destination_attribute
(atom/0
) - The attribute on the related resource that should match thesource_attribute
configured on this resource. The default value is:id
.:validate_destination_attribute?
(boolean/0
) - Whether or not to validate that the destination field exists on the destination resource The default value istrue
.:source_attribute
(atom/0
) - The field on this resource that should match thedestination_attribute
on the related resource. The default value is:id
.:relationship_context
(term/0
) - Context to be set on any queries or changesets generated for managing or querying this relationship.:private?
(boolean/0
) - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
See the security guide for more. The default value isfalse
.:not_found_message
(String.t/0
) - 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/0
) - Whether or not the relationship may be managed. The default value istrue
.:read_action
(atom/0
) - The read action on the destination resource to use when loading data and filtering.:api
(atom/0
) - The API module to use when working with the related entity.:filter
(term/0
) - A filter to be applied when reading the relationship.:filterable?
(boolean/0
) - If set tofalse
, the relationship will not be usable in filters. The default value istrue
.:sort
(term/0
) - A sort statement to be applied when loading the relationship.:could_be_related_at_creation?
(boolean/0
) - Whether or not related values may exist for this relationship at creation. The default value isfalse
.:violation_message
(String.t/0
) - 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
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 for more.
Examples:
# In a resource called `Word`
belongs_to :dictionary_entry, DictionaryEntry do
source_attribute :text,
destination_attribute :word_text
end
:primary_key?
(boolean/0
) - Whether the generated attribute is, or is part of, the primary key of a resource. The default value isfalse
.:allow_nil?
(boolean/0
) - 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. The default value istrue
.:attribute_writable?
(boolean/0
) - Whether the generated attribute will be marked as public & writable. The default value isfalse
.:define_attribute?
(boolean/0
) - If set tofalse
an attribute is not created on the resource for this relationship, and one must be manually added inattributes
, invalidating many other options. The default value istrue
.:attribute_type
(term/0
) - The type of the generated created attribute. SeeAsh.Type
for more. The default value is:uuid
.:name
(atom/0
) - The name of the relationship:destination
(atom/0
) - The destination resource:description
(String.t/0
) - An optional description for the relationship:destination_attribute
(atom/0
) - The attribute on the related resource that should match thesource_attribute
configured on this resource. The default value is:id
.:validate_destination_attribute?
(boolean/0
) - Whether or not to validate that the destination field exists on the destination resource The default value istrue
.:source_attribute
(atom/0
) - The field on this resource that should match thedestination_attribute
on the related resource. - Defaults to <name>_id:relationship_context
(term/0
) - Context to be set on any queries or changesets generated for managing or querying this relationship.:private?
(boolean/0
) - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
See the security guide for more. The default value isfalse
.:not_found_message
(String.t/0
) - 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/0
) - Whether or not the relationship may be managed. The default value istrue
.:read_action
(atom/0
) - The read action on the destination resource to use when loading data and filtering.:api
(atom/0
) - The API module to use when working with the related entity.:filter
(term/0
) - A filter to be applied when reading the relationship.:filterable?
(boolean/0
) - If set tofalse
, the relationship will not be usable in filters. The default value istrue
.:sort
(term/0
) - A sort statement to be applied when loading the relationship.:violation_message
(String.t/0
) - 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
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.
- create
- change
- validate
- argument
- metadata
- read
- argument
- prepare
- pagination
- metadata
- update
- change
- validate
- metadata
- argument
- 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
:defaults
- Creates a simple action of each specified type, with the same name as the type. These actions will be the primary actions, unless you've declared a different action of the same type that is explicitly set as primary.
By default, resources have no default actions. Embedded resources, however, have a default of all resource types.:default_accept
(list ofatom/0
) - A default value for theaccept
option for each action. Defaults to all public attributes.
create
create
Declares a create
action. For calling this action, see the Ash.Api
documentation.
Examples:
create :register do
primary? true
end
:allow_nil_input
(list ofatom/0
) - 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
- Override the creation behavior. See the manual action guides for more. Accepts a module or module and opts, or a function that takes the changeset and context.
See the manual actions guide for more.:upsert?
(boolean/0
) - Wether or not this action is always an upsert.
If this is false, the action can still be used as an upsert by passingupsert?: true
when using it. This option forces all uses of this action to be treated as an upsert The default value isfalse
.:upsert_identity
(atom/0
) - The identity to use for the upsert. Cannot be overriden by the caller. Ignored ifupsert?
is not set totrue
. The default value isfalse
.:name
(atom/0
) - Required. The name of the action:primary?
(boolean/0
) - Whether or not this action should be used when no action is specified by the caller. The default value isfalse
.:description
(String.t/0
) - An optional description for the action:transaction?
(boolean/0
) - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default totrue
.
Has no effect if the data layer does not support transactions, or if that data layer is already in a transaction.:touches_resources
(list ofatom/0
) - A list of resources that the action may touch, used when building transactions.:accept
- The list of attributes to accept. Defaults to all attributes on the resource:delay_global_validations?
(boolean/0
) - If true, global validations will be done in abefore_action
hook, regardless of their configuration on the resource. The default value isfalse
.:skip_global_validations?
(boolean/0
) - If true, global validations will be skipped. Useful for manual actions. The default value isfalse
.: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 withaccept
, then everything in theaccept
list minus any matches in thereject
list will be accepted.:require_attributes
(list ofatom/0
) - A list of attributes that would normallyallow_nil?
, to require for this action.
No need to include attributes that already do not allow nil?:error_handler
- Sets the error handler on the changeset. SeeAsh.Changeset.handle_errors/2
for more:manual?
(boolean/0
) - Instructs Ash to skip the actual update/create/destroy step at the data layer. See the manual action guides for more.
See the manual actions guide for more.
change
A change to be applied to the changeset.
See Ash.Resource.Change
for more.
Examples:
change relate_actor(:reporter)
change {MyCustomChange, :foo}
:only_when_valid?
(boolean/0
) - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. The default value isfalse
.:description
(String.t/0
) - An optional description for the change:change
- Required. The module and options for a change. Also accepts a function that takes the changeset and the context.
SeeAsh.Resource.Change.Builtins
for more.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but instead just result in this change being ignored. Also accepts functions take the changeset. The default value is[]
.
validate
Declares a validation to be applied to the changeset.
See Ash.Resource.Validation
for more.
Examples:
validate changing(:email)
:validation
- Required. The module (or module and opts) that implements theAsh.Resource.Validation
behaviour. Also accepts a one argument function that takes the changeset.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but will instead result in this validation being ignored. Accepts a module, module and opts, or a 1 argument function that takes the changeset. The default value is[]
.:only_when_valid?
(boolean/0
) - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. The default value isfalse
.:message
(String.t/0
) - If provided, overrides any message set by the validation error:description
(String.t/0
) - An optional description for the validation:before_action?
(boolean/0
) - If set totrue
, the validation will be run in a before_action hook The default value isfalse
.
argument
Declares an argument on the action
Examples:
argument :password_confirmation, :string
:name
(atom/0
) - Required. The name of the argument:type
(term/0
) - Required. The type of the argument. SeeAsh.Type
for more.:description
(String.t/0
) - An optional description for the argument.:constraints
(keyword/0
) - Constraints to provide to the type when casting the value. For more information see the specific type's documentation, for general type information seeAsh.Type
and for practical example see the constraints topic. The default value is[]
.:allow_nil?
(boolean/0
) - Whether or not the argument value may be nil (or may be not provided) If nil value is given error is raised. The default value istrue
.:private?
(boolean/0
) - Whether or not the argument should be suppliable by the client. The default value isfalse
.:sensitive?
(boolean/0
) - Whether or not the argument value contains sensitive information, like PII. Using this option will cause the argument to be** Redacted **
from the resource when logging or inspecting. See the security guide for more. The default value isfalse
.:default
(term/0
) - The default value for the argument to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
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
:name
(atom/0
) - Required. The name of the metadata:type
(term/0
) - Required. The type of the metadata. SeeAsh.Type
for more.:constraints
(keyword/0
) - Type constraints on the metadata The default value is[]
.:description
(String.t/0
) - An optional description for the metadata.:allow_nil?
(boolean/0
) - Whether or not the metadata may returnnil
The default value istrue
.:default
(term/0
) - The default value for the metadata to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
read
read
Declares a read
action. For calling this action, see the Ash.Api
documentation.
Examples:
read :read_all do
primary? true
end
:filter
(term/0
) - A filter template that will be applied whenever the action is used. SeeAsh.Filter
for more on templates:manual
- 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 for more.:get?
(boolean/0
) - Expresses that this action innately only returns a single result. Can be used by extensions to validate that you have not hooked something up that expects a list to an action that can only return one thing. Used by the code interface when defining functions for read actions.
See the code interface guide for more. The default value isfalse
.:modify_query
- 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}
.
Here be dragons.:get_by
- A helper to automatically generate a "get by X" action.
Using this option will setget?
to true, add arguments for each of the specified fields, and add a filter to the underlying query for each of the arguments. The default value isnil
.:name
(atom/0
) - Required. The name of the action:primary?
(boolean/0
) - Whether or not this action should be used when no action is specified by the caller. The default value isfalse
.:description
(String.t/0
) - An optional description for the action:transaction?
(boolean/0
) - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default totrue
.
Has no effect if the data layer does not support transactions, or if that data layer is already in a transaction.:touches_resources
(list ofatom/0
) - A list of resources that the action may touch, used when building transactions.
argument
Declares an argument on the action
Examples:
argument :password_confirmation, :string
:name
(atom/0
) - Required. The name of the argument:type
(term/0
) - Required. The type of the argument. SeeAsh.Type
for more.:description
(String.t/0
) - An optional description for the argument.:constraints
(keyword/0
) - Constraints to provide to the type when casting the value. For more information see the specific type's documentation, for general type information seeAsh.Type
and for practical example see the constraints topic. The default value is[]
.:allow_nil?
(boolean/0
) - Whether or not the argument value may be nil (or may be not provided) If nil value is given error is raised. The default value istrue
.:private?
(boolean/0
) - Whether or not the argument should be suppliable by the client. The default value isfalse
.:sensitive?
(boolean/0
) - Whether or not the argument value contains sensitive information, like PII. Using this option will cause the argument to be** Redacted **
from the resource when logging or inspecting. See the security guide for more. The default value isfalse
.:default
(term/0
) - The default value for the argument to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
prepare
Declares a preparation, which can be used to prepare a query for a read action.
Examples:
prepare build(sort: [:foo, :bar])
:preparation
- Required. The module and options for a preparation. Also accepts functions take the query and the context.
pagination
Adds pagination options to a resource
:keyset?
(boolean/0
) - Whether or not keyset based pagination is supported The default value isfalse
.:offset?
(boolean/0
) - Whether or not offset based pagination is supported The default value isfalse
.:default_limit
(pos_integer/0
) - 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 isfalse
.:max_page_size
(pos_integer/0
) - The maximum amount of records that can be requested in a single page The default value is250
.:required?
(boolean/0
) - Whether or not pagination can be disabled. Only relevant if some pagination configuration is supplied. The default value istrue
.
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
:name
(atom/0
) - Required. The name of the metadata:type
(term/0
) - Required. The type of the metadata. SeeAsh.Type
for more.:constraints
(keyword/0
) - Type constraints on the metadata The default value is[]
.:description
(String.t/0
) - An optional description for the metadata.:allow_nil?
(boolean/0
) - Whether or not the metadata may returnnil
The default value istrue
.:default
(term/0
) - The default value for the metadata to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
update
update
Declares a update
action. For calling this action, see the Ash.Api
documentation.
Examples:
update :flag_for_review, primary?: true
:manual
- Override the update behavior. See the manual action guides for more. Accepts a module or module and opts, or a function that takes the changeset and context.
See the manual actions guide for more.:name
(atom/0
) - Required. The name of the action:primary?
(boolean/0
) - Whether or not this action should be used when no action is specified by the caller. The default value isfalse
.:description
(String.t/0
) - An optional description for the action:transaction?
(boolean/0
) - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default totrue
.
Has no effect if the data layer does not support transactions, or if that data layer is already in a transaction.:touches_resources
(list ofatom/0
) - A list of resources that the action may touch, used when building transactions.:accept
- The list of attributes to accept. Defaults to all attributes on the resource:delay_global_validations?
(boolean/0
) - If true, global validations will be done in abefore_action
hook, regardless of their configuration on the resource. The default value isfalse
.:skip_global_validations?
(boolean/0
) - If true, global validations will be skipped. Useful for manual actions. The default value isfalse
.: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 withaccept
, then everything in theaccept
list minus any matches in thereject
list will be accepted.:require_attributes
(list ofatom/0
) - A list of attributes that would normallyallow_nil?
, to require for this action.
No need to include attributes that already do not allow nil?:error_handler
- Sets the error handler on the changeset. SeeAsh.Changeset.handle_errors/2
for more:manual?
(boolean/0
) - Instructs Ash to skip the actual update/create/destroy step at the data layer. See the manual action guides for more.
See the manual actions guide for more.
change
A change to be applied to the changeset.
See Ash.Resource.Change
for more.
Examples:
change relate_actor(:reporter)
change {MyCustomChange, :foo}
:only_when_valid?
(boolean/0
) - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. The default value isfalse
.:description
(String.t/0
) - An optional description for the change:change
- Required. The module and options for a change. Also accepts a function that takes the changeset and the context.
SeeAsh.Resource.Change.Builtins
for more.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but instead just result in this change being ignored. Also accepts functions take the changeset. The default value is[]
.
validate
Declares a validation to be applied to the changeset.
See Ash.Resource.Validation
for more.
Examples:
validate changing(:email)
:validation
- Required. The module (or module and opts) that implements theAsh.Resource.Validation
behaviour. Also accepts a one argument function that takes the changeset.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but will instead result in this validation being ignored. Accepts a module, module and opts, or a 1 argument function that takes the changeset. The default value is[]
.:only_when_valid?
(boolean/0
) - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. The default value isfalse
.:message
(String.t/0
) - If provided, overrides any message set by the validation error:description
(String.t/0
) - An optional description for the validation:before_action?
(boolean/0
) - If set totrue
, the validation will be run in a before_action hook The default value isfalse
.
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
:name
(atom/0
) - Required. The name of the metadata:type
(term/0
) - Required. The type of the metadata. SeeAsh.Type
for more.:constraints
(keyword/0
) - Type constraints on the metadata The default value is[]
.:description
(String.t/0
) - An optional description for the metadata.:allow_nil?
(boolean/0
) - Whether or not the metadata may returnnil
The default value istrue
.:default
(term/0
) - The default value for the metadata to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
argument
Declares an argument on the action
Examples:
argument :password_confirmation, :string
:name
(atom/0
) - Required. The name of the argument:type
(term/0
) - Required. The type of the argument. SeeAsh.Type
for more.:description
(String.t/0
) - An optional description for the argument.:constraints
(keyword/0
) - Constraints to provide to the type when casting the value. For more information see the specific type's documentation, for general type information seeAsh.Type
and for practical example see the constraints topic. The default value is[]
.:allow_nil?
(boolean/0
) - Whether or not the argument value may be nil (or may be not provided) If nil value is given error is raised. The default value istrue
.:private?
(boolean/0
) - Whether or not the argument should be suppliable by the client. The default value isfalse
.:sensitive?
(boolean/0
) - Whether or not the argument value contains sensitive information, like PII. Using this option will cause the argument to be** Redacted **
from the resource when logging or inspecting. See the security guide for more. The default value isfalse
.:default
(term/0
) - The default value for the argument to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
destroy
destroy
Declares a destroy
action. For calling this action, see the Ash.Api
documentation.
Examples:
destroy :soft_delete do
primary? true
end
:soft?
(atom/0
) - If specified, the destroy action behaves as an update internally The default value isfalse
.:manual
- Override the update behavior. See the manual action guides for more. Accepts a module or module and opts, or a function that takes the changeset and context.
See the manual actions guide for more.:name
(atom/0
) - Required. The name of the action:primary?
(boolean/0
) - Whether or not this action should be used when no action is specified by the caller. The default value isfalse
.:description
(String.t/0
) - An optional description for the action:transaction?
(boolean/0
) - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default totrue
.
Has no effect if the data layer does not support transactions, or if that data layer is already in a transaction.:touches_resources
(list ofatom/0
) - A list of resources that the action may touch, used when building transactions.:accept
- The list of attributes to accept. Defaults to all attributes on the resource:delay_global_validations?
(boolean/0
) - If true, global validations will be done in abefore_action
hook, regardless of their configuration on the resource. The default value isfalse
.:skip_global_validations?
(boolean/0
) - If true, global validations will be skipped. Useful for manual actions. The default value isfalse
.: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 withaccept
, then everything in theaccept
list minus any matches in thereject
list will be accepted.:require_attributes
(list ofatom/0
) - A list of attributes that would normallyallow_nil?
, to require for this action.
No need to include attributes that already do not allow nil?:error_handler
- Sets the error handler on the changeset. SeeAsh.Changeset.handle_errors/2
for more:manual?
(boolean/0
) - Instructs Ash to skip the actual update/create/destroy step at the data layer. See the manual action guides for more.
See the manual actions guide for more.
change
A change to be applied to the changeset.
See Ash.Resource.Change
for more.
Examples:
change relate_actor(:reporter)
change {MyCustomChange, :foo}
:only_when_valid?
(boolean/0
) - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. The default value isfalse
.:description
(String.t/0
) - An optional description for the change:change
- Required. The module and options for a change. Also accepts a function that takes the changeset and the context.
SeeAsh.Resource.Change.Builtins
for more.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but instead just result in this change being ignored. Also accepts functions take the changeset. The default value is[]
.
validate
Declares a validation to be applied to the changeset.
See Ash.Resource.Validation
for more.
Examples:
validate changing(:email)
:validation
- Required. The module (or module and opts) that implements theAsh.Resource.Validation
behaviour. Also accepts a one argument function that takes the changeset.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but will instead result in this validation being ignored. Accepts a module, module and opts, or a 1 argument function that takes the changeset. The default value is[]
.:only_when_valid?
(boolean/0
) - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. The default value isfalse
.:message
(String.t/0
) - If provided, overrides any message set by the validation error:description
(String.t/0
) - An optional description for the validation:before_action?
(boolean/0
) - If set totrue
, the validation will be run in a before_action hook The default value isfalse
.
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
:name
(atom/0
) - Required. The name of the metadata:type
(term/0
) - Required. The type of the metadata. SeeAsh.Type
for more.:constraints
(keyword/0
) - Type constraints on the metadata The default value is[]
.:description
(String.t/0
) - An optional description for the metadata.:allow_nil?
(boolean/0
) - Whether or not the metadata may returnnil
The default value istrue
.:default
(term/0
) - The default value for the metadata to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
argument
Declares an argument on the action
Examples:
argument :password_confirmation, :string
:name
(atom/0
) - Required. The name of the argument:type
(term/0
) - Required. The type of the argument. SeeAsh.Type
for more.:description
(String.t/0
) - An optional description for the argument.:constraints
(keyword/0
) - Constraints to provide to the type when casting the value. For more information see the specific type's documentation, for general type information seeAsh.Type
and for practical example see the constraints topic. The default value is[]
.:allow_nil?
(boolean/0
) - Whether or not the argument value may be nil (or may be not provided) If nil value is given error is raised. The default value istrue
.:private?
(boolean/0
) - Whether or not the argument should be suppliable by the client. The default value isfalse
.:sensitive?
(boolean/0
) - Whether or not the argument value contains sensitive information, like PII. Using this option will cause the argument to be** Redacted **
from the resource when logging or inspecting. See the security guide for more. The default value isfalse
.:default
(term/0
) - The default value for the argument to take. It can be a zero argument function e.g&MyMod.my_fun/0
or a value
code_interface
code_interface
Functions that will be defined on the Api module to interact with this resource.
See the code interface guide for more.
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
:define_for
(atom/0
) - Defines the code interface on the resource module directly, using the provided Api. The default value isfalse
.
define
define
Defines a function with the corresponding name and arguments.
See the code interface guide for more.
Examples:
define :get_user_by_id, action: :get_by_id, args: [:id], get?: true
:name
(atom/0
) - Required. The name of the function that will be defined:action
(atom/0
) - The name of the action that will be called. Defaults to the same name as the function.:args
- Map specific arguments to named inputs. Can provide any argument/attributes that the action allows.:not_found_error?
(boolean/0
) - If the action or interface is configured withget?: true
, this determines whether or not an error is raised ornil
is returned. The default value istrue
.:get?
(boolean/0
) - 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 ofatom/0
) - Takes a list of fields and adds those fields as arguments, which will then be used to filter. Setsget?
to true automatically. Ignored for non-read actions.:get_by_identity
(atom/0
) - Only relevant for read actions. Takes an identity, and gets its field list, performing the same logic asget_by
once it has the list of fields.
define_calculation
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 for more.
Examples:
define_calculation :referral_link, args: [:id]
define_calculation :referral_link, args: [{:arg, :id}, {:ref, :id}]
:name
(atom/0
) - Required. The name of the function that will be defined:calculation
(atom/0
) - The name of the calculation that will be evaluated. Defaults to the same name as the function.:args
(term/0
) - Supply field or argument values referenced by the calculation.
By default, the value will be provided for any matching named reference and argument. This is normally fine, but in the case that you have an argument and a reference with the same name, you can specify it by supplying{:arg, :name}
and{:ref, :name}
. For example:define_calculation :id_matches, args: [{:arg, :id}, {:ref, :id}]
To make arguments optional, wrap them in
{:optional, ..}
, for example:define_calculation :id_matches, args: [{:arg, :id}, {:optional, {:ref, :id}}] ``` The default value is `[]`.
resource
resource
General resource configuration
Examples:
resource do
description "A description of this resource"
base_filter [is_nil: :deleted_at]
end
Imports:
:description
(String.t/0
) - A human readable description of the resource, to be used in generated documentation:base_filter
(term/0
) - A filter statement to be applied to any queries on the resource:default_context
(term/0
) - Default context to apply to any queries/changesets generated for this resource.:trace_name
(String.t/0
) - The name to use in traces. Defaults to the short_name stringified.
See the monitoring guide for more.:short_name
(atom/0
) - A short identifier for the resource, which should be unique.
See the monitoring guide for more.:simple_notifiers
(list ofatom/0
) - A list of notifiers that require no DSL. Can be used to avoid compile time dependencies on notifiers
identities
identities
Unique identifiers for the resource
Examples:
identities do
identity :full_name, [:first_name, :last_name]
identity :email, [:email]
end
identity
identity
Represents a unique constraint on the resource.
See the identities guide for more.
Examples:
identity :name, [:name]
identity :full_name, [:first_name, :last_name]
:name
(atom/0
) - Required. The name of the identity.:keys
- Required. The names of the attributes that uniquely identify this resource.:eager_check_with
(atom/0
) - Validates that the unique identity provided is unique at validation time, outside of any transactions, using the api module provided.:pre_check_with
(atom/0
) - Validates that the unique identity provided is unique in a before_action hook.:description
(String.t/0
) - An optional description for the identity:message
(String.t/0
) - An error message to use when the unique identity would be violated
changes
changes
Declare changes that occur on create/update/destroy actions against the resource
See Ash.Resource.Change
for more.
Examples:
changes do
change {Mod, [foo: :bar]}
change set_context(%{some: :context})
end
Imports:
change
change
A change to be applied to the changeset.
See Ash.Resource.Change
for more.
Examples:
change relate_actor(:reporter)
change {MyCustomChange, :foo}
:on
- The action types the validation should run on. Destroy actions are omitted by default as most changes don't make sense for a destroy. The default value is[:create, :update]
.:only_when_valid?
(boolean/0
) - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. The default value isfalse
.:description
(String.t/0
) - An optional description for the change:change
- Required. The module and options for a change. Also accepts a function that takes the changeset and the context.
SeeAsh.Resource.Change.Builtins
for more.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but instead just result in this change being ignored. Also accepts functions take the changeset. The default value is[]
.
preparations
preparations
Declare preparations that occur on all read actions for a given resource
Examples:
preparations do
prepare {Mod, [foo: :bar]}
prepare set_context(%{some: :context})
end
Imports:
prepare
prepare
Declares a preparation, which can be used to prepare a query for a read action.
Examples:
prepare build(sort: [:foo, :bar])
:preparation
- Required. The module and options for a preparation. Also accepts functions take the query and the context.
validations
validations
Declare validations prior to performing actions against the resource
Examples:
validations do
validate {Mod, [foo: :bar]}
validate at_least_one_of_present([:first_name, :last_name])
end
Imports:
validate
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])
:validation
- Required. The module (or module and opts) that implements theAsh.Resource.Validation
behaviour. Also accepts a one argument function that takes the changeset.:where
- Validations that should pass in order for this validation to apply. These validations failing will not invalidate the changes, but will instead result in this validation being ignored. Accepts a module, module and opts, or a 1 argument function that takes the changeset. The default value is[]
.: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]
.:only_when_valid?
(boolean/0
) - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. The default value isfalse
.:message
(String.t/0
) - If provided, overrides any message set by the validation error:description
(String.t/0
) - An optional description for the validation:before_action?
(boolean/0
) - If set totrue
, the validation will be run in a before_action hook The default value isfalse
.
aggregates
aggregates
Declare named aggregates on the resource.
These are aggregates that can be loaded only by name using Ash.Query.load/2
.
They are also available as top level fields on the resource.
See the aggregates guide for more.
Examples:
aggregates do
count :assigned_ticket_count, :reported_tickets do
filter [active: true]
end
end
Imports:
count
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 for more.
Examples:
count :assigned_ticket_count, :assigned_tickets do
filter [active: true]
end
:uniq?
(boolean/0
) - Wether or not to count unique values only The default value isfalse
.:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
first
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 for more.
Examples:
first :first_assigned_ticket_subject, :assigned_tickets, :subject do
filter [active: true]
sort [:subject]
end
:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:sort
(term/0
) - A sort to be applied to the aggregate:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
sum
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 for more.
Examples:
sum :assigned_ticket_price_sum, :assigned_tickets, :price do
filter [active: true]
end
:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
list
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 for more.
Examples:
list :assigned_ticket_prices, :assigned_tickets, :price do
filter [active: true]
end
:uniq?
(boolean/0
) - Wether or not to count unique values only The default value isfalse
.:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:sort
(term/0
) - A sort to be applied to the aggregate:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
max
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 for more.
Examples:
max :first_assigned_ticket_subject, :assigned_tickets, :severity do
filter [active: true]
end
:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
min
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 for more.
Examples:
min :first_assigned_ticket_subject, :assigned_tickets, :severity do
filter [active: true]
end
:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
avg
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 for more.
Examples:
avg :assigned_ticket_price_sum, :assigned_tickets, :price do
filter [active: true]
end
:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
custom
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 for more.
Examples:
custom :author_names, :authors, :string do
implementation {StringAgg, delimiter: ","}
end
:implementation
- Required. The module that implements the relevant data layer callbacks:type
(atom/0
) - Required. The type of the value returned by the aggregate:name
(atom/0
) - Required. The field to place the aggregate in:read_action
(atom/0
) - 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.:relationship_path
- Required. The relationship or relationship path to use for the aggregate:kind
- Required. The kind of the aggregate:field
(atom/0
) - The field to aggregate. Defaults to the first field in the primary key of the resource:filter
(term/0
) - A filter to apply to the aggregate The default value is[]
.:sort
(term/0
) - A sort to be applied to the aggregate:description
(String.t/0
) - An optional description for the aggregate:default
(term/0
) - A default value to use in cases where nil would be used. Count defaults to0
.:private?
(boolean/0
) - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql The default value isfalse
.:filterable?
- Whether or not the aggregate should be usable in filters. The default value istrue
.:authorize?
(boolean/0
) - Wether or not the aggregate query should authorize based on the target action.
If you are using filter checks or simple checks that don't depend on arguments on the destination resource, then this should be set totrue
. Additionally, you can setread_action
to a separate action that does have filter checks. Otherwise, you can setauthorize? false
on the aggregate.
If the parent query is not being authorized, then the aggregate not be authorized either regardless of the setting. The default value istrue
.
calculations
calculations
Declare named calculations on the resource.
These are calculations that can be loaded only by name using Ash.Query.load/2
.
They are also available as top level fields on the resource.
See the calculations guide for more.
- calculate
- argument
Examples:
calculations do
calculate :full_name, :string, MyApp.MyResource.FullName
end
Imports:
calculate
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 for more.
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)
:name
(atom/0
) - Required. The field name to use for the calculation value:type
(term/0
) - Required. The type of the calculation. SeeAsh.Type
for more.:constraints
(keyword/0
) - Constraints to provide to the type. SeeAsh.Type
for more. The default value is[]
.:calculation
- Required. The module or{module, opts}
to use for the calculation Also accepts a function that takes the list of records and the context.:description
(String.t/0
) - An optional description for the calculation:private?
(boolean/0
) - Whether or not the calculation will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql
See the security guide for more. The default value isfalse
.:select
(list ofatom/0
) - A list of fields to ensure selected if the calculation is used. The default value is[]
.:load
(term/0
) - A load statement to be applied if the calculation is used. The default value is[]
.:allow_nil?
(boolean/0
) - Whether or not the calculation can return nil. The default value istrue
.:filterable?
- Whether or not the calculation should be usable in filters. The default value istrue
.
argument
An argument to be passed into the calculation's arguments map
See the calculations guide for more.
Examples:
argument :params, :map do
default %{}
end
argument :retries, :integer do
allow_nil? false
end
:name
(atom/0
) - Required. The name of the argument:type
(term/0
) - Required. The type of the argument. SeeAsh.Type
for more.:default
- A default value to use for the argument if not provided:allow_nil?
(boolean/0
) - Whether or not the argument value may be nil (or may be not provided) The default value istrue
.:allow_expr?
(boolean/0
) - Allow passing expressions as argument values. Expressions cannot be type validated. The default value isfalse
.:constraints
(keyword/0
) - Constraints to provide to the type when casting the value. See the type's documentation andAsh.Type
for more. The default value is[]
.
multitenancy
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
Examples:
multitenancy do
strategy :attribute
attribute :organization_id
global? true
end
:strategy
- Determine if multitenancy is performed with attribute filters or using data layer features. The default value is:context
.:attribute
(atom/0
) - If using theattribute
strategy, the attribute to use, e.gorg_id
:global?
(boolean/0
) - Whether or not the data also exists outside of each tenant. The default value isfalse
.:parse_attribute
- An mfa ({module, function, args}) pointing to a function that takes a tenant and returns the attribute value The default value is{Ash.Resource.Dsl, :identity, []}
.