diff --git a/documentation/dsls/DSL:-Ash.Api.cheatmd b/documentation/dsls/DSL:-Ash.Api.cheatmd deleted file mode 100644 index 1ed46c06f..000000000 --- a/documentation/dsls/DSL:-Ash.Api.cheatmd +++ /dev/null @@ -1,393 +0,0 @@ - -# DSL: Ash.Api.Dsl - -Apis are the entrypoints for working with your resources. - -Apis may optionally include a list of resources, in which case they can be -used as an `Ash.Registry` in various places. This is for backwards compatibility, -but if at all possible you should define an `Ash.Registry` if you are using an extension -that requires a list of resources. For example, most extensions look for two application -environment variables called `:ash_apis` and `:ash_registries` to find any potential registries - - -## api -General Api configuration - - - -### Examples -``` -api do - description """ - Resources related to the flux capacitor. - """ -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - A description for the api. - -
- - - - - - -## resources -List the resources present in this API - -### Nested DSLs - * [resource](#resources-resource) - - -### Examples -``` -resources do - resource MyApp.Tweet - resource MyApp.Comment -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - allow - - - - - mfa - - - - Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed. - -
- - - allow_unregistered? - - - - - boolean - - false - - Whether the Api will support only registered entries or not. - -
- - - registry - - - - - module - - - - Configure a registry that contains the resources. This option is generally not necessary anymore, and remains for backwards compatibility. Instead, configure resources in this block directly. - -
- - - -## resources.resource -```elixir -resource resource -``` - - -A resource present in the API - - - -### Examples -``` -resource Foo -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - resource - - - * - - - module - - - - -
- - - - - - -### Introspection - -Target: `Ash.Api.Dsl.ResourceReference` - - - - -## execution -Options for how requests are executed using this Api - - - -### Examples -``` -execution do - timeout :timer.seconds(30) -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - timeout - - - - - timeout - - 30000 - - The default timeout to use for requests using this API. See the [timeouts guide](/documentation/topics/timeouts.md) for more. - -
- - - trace_name - - - - - String.t - - - - The name to use in traces. Defaults to the last part of the module. See the [monitoring guide](/documentation/topics/monitoring.md) for more - -
- - - - - - -## authorization -Options for how requests are authorized using this Api. See the [security guide](/documentation/topics/security.md) for more. - - - - -### Examples -``` -authorization do - authorize :by_default -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - require_actor? - - - - - boolean - - false - - Requires that an actor has been supplied. -
- - - authorize - - - - - :always | :by_default | :when_requested - - :when_requested - - When to run authorization for a given request. - -
- - - - - - diff --git a/documentation/dsls/DSL:-Ash.Api.md b/documentation/dsls/DSL:-Ash.Api.md new file mode 100644 index 000000000..d36f4fde1 --- /dev/null +++ b/documentation/dsls/DSL:-Ash.Api.md @@ -0,0 +1,166 @@ + +# DSL: Ash.Api.Dsl + +Apis are the entrypoints for working with your resources. + +Apis may optionally include a list of resources, in which case they can be +used as an `Ash.Registry` in various places. This is for backwards compatibility, +but if at all possible you should define an `Ash.Registry` if you are using an extension +that requires a list of resources. For example, most extensions look for two application +environment variables called `:ash_apis` and `:ash_registries` to find any potential registries + + +## api +General Api configuration + + + +### Examples +``` +api do + description """ + Resources related to the flux capacitor. + """ +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#api-description){: #api-description } | `String.t` | | A description for the api. | + + + + + + +## resources +List the resources present in this API + +### Nested DSLs + * [resource](#resources-resource) + + +### Examples +``` +resources do + resource MyApp.Tweet + resource MyApp.Comment +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`allow`](#resources-allow){: #resources-allow } | `mfa` | | Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed. | +| [`allow_unregistered?`](#resources-allow_unregistered?){: #resources-allow_unregistered? } | `boolean` | `false` | Whether the Api will support only registered entries or not. | +| [`registry`](#resources-registry){: #resources-registry } | `module` | | Configure a registry that contains the resources. This option is generally not necessary anymore, and remains for backwards compatibility. Instead, configure resources in this block directly. | + + + +## resources.resource +```elixir +resource resource +``` + + +A resource present in the API + + + +### Examples +``` +resource Foo +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`resource`](#resources-resource-resource){: #resources-resource-resource .spark-required} | `module` | | | + + + + + + +### Introspection + +Target: `Ash.Api.Dsl.ResourceReference` + + + + +## execution +Options for how requests are executed using this Api + + + +### Examples +``` +execution do + timeout :timer.seconds(30) +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`timeout`](#execution-timeout){: #execution-timeout } | `timeout` | `30000` | The default timeout to use for requests using this API. See the [timeouts guide](/documentation/topics/timeouts.md) for more. | +| [`trace_name`](#execution-trace_name){: #execution-trace_name } | `String.t` | | The name to use in traces. Defaults to the last part of the module. See the [monitoring guide](/documentation/topics/monitoring.md) for more | + + + + + + +## authorization +Options for how requests are authorized using this Api. See the [security guide](/documentation/topics/security.md) for more. + + + + +### Examples +``` +authorization do + authorize :by_default +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`require_actor?`](#authorization-require_actor?){: #authorization-require_actor? } | `boolean` | `false` | Requires that an actor has been supplied. | +| [`authorize`](#authorization-authorize){: #authorization-authorize } | `:always \| :by_default \| :when_requested` | `:when_requested` | When to run authorization for a given request. | + + + + + + + + diff --git a/documentation/dsls/DSL:-Ash.DataLayer.Ets.cheatmd b/documentation/dsls/DSL:-Ash.DataLayer.Ets.cheatmd deleted file mode 100644 index 0ef291490..000000000 --- a/documentation/dsls/DSL:-Ash.DataLayer.Ets.cheatmd +++ /dev/null @@ -1,90 +0,0 @@ - -# DSL: Ash.DataLayer.Ets - -An ETS (Erlang Term Storage) backed Ash Datalayer, for testing and lightweight usage. - -Remember, this does not have support for transactions! This is not recommended for production -use, especially in multi-user applications. It can, however, be great for prototyping. - - -## ets -A section for configuring the ets data layer - - - - -### Examples -``` -ets do - # Used in testing - private? true -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - private? - - - - - boolean - - false - - Sets the ets table protection to private, and scopes it to only this process. The table name will not be used directly if this is true, to allow multiple processes to use this resource separately. -
- - - table - - - - - atom - - - - The name of the table. Defaults to the resource name. - -
- - - - - - diff --git a/documentation/dsls/DSL:-Ash.DataLayer.Ets.md b/documentation/dsls/DSL:-Ash.DataLayer.Ets.md new file mode 100644 index 000000000..7048a12d5 --- /dev/null +++ b/documentation/dsls/DSL:-Ash.DataLayer.Ets.md @@ -0,0 +1,43 @@ + +# DSL: Ash.DataLayer.Ets + +An ETS (Erlang Term Storage) backed Ash Datalayer, for testing and lightweight usage. + +Remember, this does not have support for transactions! This is not recommended for production +use, especially in multi-user applications. It can, however, be great for prototyping. + + +## ets +A section for configuring the ets data layer + + + + +### Examples +``` +ets do + # Used in testing + private? true +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`private?`](#ets-private?){: #ets-private? } | `boolean` | `false` | Sets the ets table protection to private, and scopes it to only this process. The table name will not be used directly if this is true, to allow multiple processes to use this resource separately. | +| [`table`](#ets-table){: #ets-table } | `atom` | | The name of the table. Defaults to the resource name. | + + + + + + + + diff --git a/documentation/dsls/DSL:-Ash.DataLayer.Mnesia.cheatmd b/documentation/dsls/DSL:-Ash.DataLayer.Mnesia.md similarity index 51% rename from documentation/dsls/DSL:-Ash.DataLayer.Mnesia.cheatmd rename to documentation/dsls/DSL:-Ash.DataLayer.Mnesia.md index dab3ff0f0..2b9cd6841 100644 --- a/documentation/dsls/DSL:-Ash.DataLayer.Mnesia.cheatmd +++ b/documentation/dsls/DSL:-Ash.DataLayer.Mnesia.md @@ -33,41 +33,14 @@ end ### Options - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - table - - - - - atom - - - - The table name to use, defaults to the name of the resource -
+| Name | Type | Default | Docs | +|------|------|---------|------| +| [`table`](#mnesia-table){: #mnesia-table } | `atom` | | The table name to use, defaults to the name of the resource | + + diff --git a/documentation/dsls/DSL:-Ash.Flow.cheatmd b/documentation/dsls/DSL:-Ash.Flow.cheatmd deleted file mode 100644 index 27792fd16..000000000 --- a/documentation/dsls/DSL:-Ash.Flow.cheatmd +++ /dev/null @@ -1,3555 +0,0 @@ - -# DSL: Ash.Flow.Dsl - -The built in flow DSL. - -## Halting - -Steps can be halted, which will stop the flow from continuing and return a halted flow. To attach a specific reason, use a `halt_reason`. -If you need more complex halting logic, then you'd want to use a custom step, and return `{:error, Ash.Error.Flow.Halted.exception(...)}` - - -## flow -Details about the flow itself, like description and the successful return type. - - -### Nested DSLs - * [argument](#flow-argument) - - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - api - - - - - module - - - - An api to use by default when calling actions -
- - - description - - - - - String.t - - - - A description of the flow -
- - - trace_name - - - - - String.t - - - - The name to use when creating traces. Defaults to the short name. -
- - - short_name - - - - - atom - - - - A short name to use for the flow. Defaults to the last to parts of the module name, underscored. -
- - - returns - - - - - `any` - - - - The step or step that should constitute the return value. - -
- - - -## flow.argument -```elixir -argument name, type -``` - - -An argument to be passed into the flow - - - - -### Examples -``` -argument :params, :map do - default %{} -end - -``` - -``` -argument :retries, :integer do - allow_nil? false -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name to use for the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - default - - - - - (-> any) | mfa | any() - - - - A default value to use for the argument if not provided -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. See the type's documentation for more information. -
- - - - - -### Introspection - -Target: `Ash.Flow.Argument` - - - - -## steps -The steps to run. - - -### Nested DSLs - * [map](#steps-map) - - * [branch](#steps-branch) - - * [transaction](#steps-transaction) - - * [create](#steps-create) - * [debug](#steps-debug) - * [update](#steps-update) - * [destroy](#steps-destroy) - * [validate](#steps-validate) - * [read](#steps-read) - * [run_flow](#steps-run_flow) - * [custom](#steps-custom) - - -### Examples -``` -steps do - # invokes a create action - create :create_post, MyApp.Post, :create -end - -``` - - - - -## steps.map -```elixir -map name, over -``` - - -Runs a set of steps for each item in a provided list. - - - - -### Examples -``` -map :create_users, range(1, arg(:count)) do - output :create_user - - create :create_user, Org, :create do - input %{ - first_name: {Faker.Person, :first_name, []}, - last_name: {Faker.Person, :last_name, []} - } - end -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - over - - - - - `any` - - - - The value to be iterated over. Will be available inside the `map` step as `element(:map_step_name)` -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - output - - - - - atom - - - - Which step to use when constructing the output list. Defaults to the last step. -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Map` - -## steps.branch -```elixir -branch name, condition -``` - - -Runs a set of steps based on a given value. - - - - -### Examples -``` -branch :create_users, result(:create_users?) do - output :create_user - - create :create_user, Org, :create do - input %{ - first_name: {Faker.Person, :first_name, []}, - last_name: {Faker.Person, :last_name, []} - } - end -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - condition - - - - - `any` - - - - A template that must evaluate to `true` for the branch to be executed. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - output - - - - - atom - - - - Which step to use as the output. Defaults to the last step. -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Branch` - -## steps.transaction -```elixir -transaction name, resource -``` - - -Runs a set of steps in a transaction. - - - - -### Examples -``` -transaction :create_user_with_org do - touches_resources [User, Org] - - create :create_user, User, :create do - input %{ - first_name: {Faker.Person, :first_name, []}, - last_name: {Faker.Person, :last_name, []} - } - end - - create :create_org, Org, :create do - input %{ - user_id: path(result(:create_user), :id), - name: {Faker.Color, :name, []} - } - end -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - resource - - - - - module | list(module) - - - - The Ash resource to use for the transaction. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - output - - - - - `any` - - - - Which step or steps to use when constructing the output. Defaults to the last step. -
- - - timeout - - - - - timeout - - - - A timeout to apply to the transaction. -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Transaction` - -## steps.create -```elixir -create name, resource, action -``` - - -Declares a step that will call a create action on a resource. - - - - -### Examples -``` -create :create_post, MyApp.Post, :create - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - resource - - - * - - - `any` - - - - The resource to call the action on. -
- - - action - - - * - - - `any` - - - - The action to call on the resource. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - upsert? - - - - - boolean - - false - - Whether or not this action is always an upsert. -
- - - upsert_identity - - - - - atom - - - - The identity to use for the upsert. -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - api - - - - - `any` - - - - The api to use when calling the action. Defaults to the api set in the `flow` section. -
- - - tenant - - - - - `any` - - - - A tenant to use for the operation. May be a template or a literal value. -
- - - input - - - - - `any` - - - - A template for the input. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Create` - -## steps.debug -```elixir -debug name -``` - - -Declares a step that will inspect its input and provide -additional debug information. - - - - -### Examples -``` -debug :show_some_information do - input %{post: result(:create_post)} -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - input - - - - - `any` - - - - A template for the input. - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Debug` - -## steps.update -```elixir -update name, resource, action -``` - - -Declares a step that will call a update action on a resource. - - - - -### Examples -``` -update :update_post, MyApp.Post, :update do - record result(:get_post) -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - resource - - - * - - - `any` - - - - The resource to call the action on. -
- - - action - - - * - - - `any` - - - - The action to call on the resource. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - record - - - * - - - `any` - - - - The record to be updated, can use template helpers, e.g `result(:step_name)`. - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - api - - - - - `any` - - - - The api to use when calling the action. Defaults to the api set in the `flow` section. -
- - - tenant - - - - - `any` - - - - A tenant to use for the operation. May be a template or a literal value. -
- - - input - - - - - `any` - - - - A template for the input. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Update` - -## steps.destroy -```elixir -destroy name, resource, action -``` - - -Declares a step that will call a destroy action on a resource. - - - - -### Examples -``` -destroy :destroy_post, MyApp.Post, :destroy - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - resource - - - * - - - `any` - - - - The resource to call the action on. -
- - - action - - - * - - - `any` - - - - The action to call on the resource. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - record - - - * - - - `any` - - - - The record to be updated, can use template helpers, e.g `result(:step_name)`. - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - api - - - - - `any` - - - - The api to use when calling the action. Defaults to the api set in the `flow` section. -
- - - tenant - - - - - `any` - - - - A tenant to use for the operation. May be a template or a literal value. -
- - - input - - - - - `any` - - - - A template for the input. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Destroy` - -## steps.validate -```elixir -validate name, resource, action -``` - - -Validates some input against an action. - - - - -### Examples -``` -validate :update_post, MyApp.Post, :update do - record result(:get_post) - only_keys [:name] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - resource - - - * - - - `any` - - - - The resource to call the action on. -
- - - action - - - * - - - `any` - - - - The action to call on the resource. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - record - - - - - `any` - - - - The record to be created/updated/destroyed. If the value is `nil` and would be required by the action type, the step is skipped and `nil` is the result of the step. - -
- - - only_keys - - - - - list(atom | list(atom)) - - - - A list of keys or paths to keys that should be validated. Others will be ignored, and errors generated for other fields will be ignored. - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - api - - - - - `any` - - - - The api to use when calling the action. Defaults to the api set in the `flow` section. -
- - - tenant - - - - - `any` - - - - A tenant to use for the operation. May be a template or a literal value. -
- - - input - - - - - `any` - - - - A template for the input. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Update` - -## steps.read -```elixir -read name, resource, action -``` - - -Declares a step that will call a read action on a resource. - - - - -### Examples -``` -read :destroy_post, MyApp.Post, :destroy - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - resource - - - * - - - `any` - - - - The resource to call the action on. -
- - - action - - - * - - - `any` - - - - The action to call on the resource. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - get? - - - - - boolean - - false - - Whether or not read action is expected to return a single result or `nil`. Set to `true` automatically if `get? true`. - -
- - - not_found_error? - - - - - boolean - - true - - Whether or not finding no record should result in a not found error - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - api - - - - - `any` - - - - The api to use when calling the action. Defaults to the api set in the `flow` section. -
- - - tenant - - - - - `any` - - - - A tenant to use for the operation. May be a template or a literal value. -
- - - input - - - - - `any` - - - - A template for the input. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Read` - -## steps.run_flow -```elixir -run_flow name, flow -``` - - -Runs another flow as part of the current flow. -The return value of the step is the return value of the flow. - - - - -### Examples -``` -run_flow :get_org, GetOrgByName do - input %{ - name: arg(:org_name) - } - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - flow - - - * - - - atom - - - - The flow to run. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - input - - - - - `any` - - - - A template for the input. - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.RunFlow` - -## steps.custom -```elixir -custom name, custom -``` - - -Runs a custom step module. - -See `Ash.Flow.Step` for the necessary callbacks and more information. - - - - -### Examples -``` -custom :do_custom_thing, MyApp.DoCustomThing do - input %{...} -end - -``` - -``` -custom :do_custom_thing, {MyApp.DoCustomThing, opt1: :foo, opt2: :bar} do - input %{...} -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the step. Will be used when expressing dependencies, and step inputs. -
- - - custom - - - - - (any, any -> any) | module - - - - The module that implements the step behaviour. Also accepts a 2 argument function that takes the input and the context. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - input - - - - - `any` - - - - A template for the input. - -
- - - async? - - - - - boolean - - false - - Whether or not this step can be run outside of the current process. - -
- - - short_name - - - - - String.t - - - - Set a short name for the step. Will be used when building things like mermaid charts. -
- - - wait_for - - - - - `any` - - - - Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. - -
- - - halt_if - - - - - `any` - - - - Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. - -
- - - halt_reason - - - - - `any` - - :halted - - Configures the reason for the `halt_if` clause. - -
- - - description - - - - - String.t - - - - A description for the step. - -
- - - - - -### Introspection - -Target: `Ash.Flow.Step.Custom` - - - - diff --git a/documentation/dsls/DSL:-Ash.Flow.md b/documentation/dsls/DSL:-Ash.Flow.md new file mode 100644 index 000000000..d116ca8ae --- /dev/null +++ b/documentation/dsls/DSL:-Ash.Flow.md @@ -0,0 +1,702 @@ + +# DSL: Ash.Flow.Dsl + +The built in flow DSL. + +## Halting + +Steps can be halted, which will stop the flow from continuing and return a halted flow. To attach a specific reason, use a `halt_reason`. +If you need more complex halting logic, then you'd want to use a custom step, and return `{:error, Ash.Error.Flow.Halted.exception(...)}` + + +## flow +Details about the flow itself, like description and the successful return type. + + +### Nested DSLs + * [argument](#flow-argument) + + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`api`](#flow-api){: #flow-api } | `module` | | An api to use by default when calling actions | +| [`description`](#flow-description){: #flow-description } | `String.t` | | A description of the flow | +| [`trace_name`](#flow-trace_name){: #flow-trace_name } | `String.t` | | The name to use when creating traces. Defaults to the short name. | +| [`short_name`](#flow-short_name){: #flow-short_name } | `atom` | | A short name to use for the flow. Defaults to the last to parts of the module name, underscored. | +| [`returns`](#flow-returns){: #flow-returns } | ``any`` | | The step or step that should constitute the return value. | + + + +## flow.argument +```elixir +argument name, type +``` + + +An argument to be passed into the flow + + + + +### Examples +``` +argument :params, :map do + default %{} +end + +``` + +``` +argument :retries, :integer do + allow_nil? false +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#flow-argument-name){: #flow-argument-name .spark-required} | `atom` | | The name to use for the argument | +| [`type`](#flow-argument-type){: #flow-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`default`](#flow-argument-default){: #flow-argument-default } | `(-> any) \| mfa \| any()` | | A default value to use for the argument if not provided | +| [`allow_nil?`](#flow-argument-allow_nil?){: #flow-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil | +| [`constraints`](#flow-argument-constraints){: #flow-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. See the type's documentation for more information. | + + + + + +### Introspection + +Target: `Ash.Flow.Argument` + + + + +## steps +The steps to run. + + +### Nested DSLs + * [map](#steps-map) + + * [branch](#steps-branch) + + * [transaction](#steps-transaction) + + * [create](#steps-create) + * [debug](#steps-debug) + * [update](#steps-update) + * [destroy](#steps-destroy) + * [validate](#steps-validate) + * [read](#steps-read) + * [run_flow](#steps-run_flow) + * [custom](#steps-custom) + + +### Examples +``` +steps do + # invokes a create action + create :create_post, MyApp.Post, :create +end + +``` + + + + +## steps.map +```elixir +map name, over +``` + + +Runs a set of steps for each item in a provided list. + + + + +### Examples +``` +map :create_users, range(1, arg(:count)) do + output :create_user + + create :create_user, Org, :create do + input %{ + first_name: {Faker.Person, :first_name, []}, + last_name: {Faker.Person, :last_name, []} + } + end +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-map-name){: #steps-map-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`over`](#steps-map-over){: #steps-map-over } | ``any`` | | The value to be iterated over. Will be available inside the `map` step as `element(:map_step_name)` | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`output`](#steps-map-output){: #steps-map-output } | `atom` | | Which step to use when constructing the output list. Defaults to the last step. | +| [`short_name`](#steps-map-short_name){: #steps-map-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-map-wait_for){: #steps-map-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-map-touches_resources){: #steps-map-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-map-halt_if){: #steps-map-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-map-halt_reason){: #steps-map-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-map-description){: #steps-map-description } | `String.t` | | A description for the step. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Map` + +## steps.branch +```elixir +branch name, condition +``` + + +Runs a set of steps based on a given value. + + + + +### Examples +``` +branch :create_users, result(:create_users?) do + output :create_user + + create :create_user, Org, :create do + input %{ + first_name: {Faker.Person, :first_name, []}, + last_name: {Faker.Person, :last_name, []} + } + end +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-branch-name){: #steps-branch-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`condition`](#steps-branch-condition){: #steps-branch-condition } | ``any`` | | A template that must evaluate to `true` for the branch to be executed. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`output`](#steps-branch-output){: #steps-branch-output } | `atom` | | Which step to use as the output. Defaults to the last step. | +| [`short_name`](#steps-branch-short_name){: #steps-branch-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-branch-wait_for){: #steps-branch-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-branch-touches_resources){: #steps-branch-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-branch-halt_if){: #steps-branch-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-branch-halt_reason){: #steps-branch-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-branch-description){: #steps-branch-description } | `String.t` | | A description for the step. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Branch` + +## steps.transaction +```elixir +transaction name, resource +``` + + +Runs a set of steps in a transaction. + + + + +### Examples +``` +transaction :create_user_with_org do + touches_resources [User, Org] + + create :create_user, User, :create do + input %{ + first_name: {Faker.Person, :first_name, []}, + last_name: {Faker.Person, :last_name, []} + } + end + + create :create_org, Org, :create do + input %{ + user_id: path(result(:create_user), :id), + name: {Faker.Color, :name, []} + } + end +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-transaction-name){: #steps-transaction-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`resource`](#steps-transaction-resource){: #steps-transaction-resource } | `module \| list(module)` | | The Ash resource to use for the transaction. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`output`](#steps-transaction-output){: #steps-transaction-output } | ``any`` | | Which step or steps to use when constructing the output. Defaults to the last step. | +| [`timeout`](#steps-transaction-timeout){: #steps-transaction-timeout } | `timeout` | | A timeout to apply to the transaction. | +| [`short_name`](#steps-transaction-short_name){: #steps-transaction-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-transaction-wait_for){: #steps-transaction-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-transaction-touches_resources){: #steps-transaction-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-transaction-halt_if){: #steps-transaction-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-transaction-halt_reason){: #steps-transaction-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-transaction-description){: #steps-transaction-description } | `String.t` | | A description for the step. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Transaction` + +## steps.create +```elixir +create name, resource, action +``` + + +Declares a step that will call a create action on a resource. + + + + +### Examples +``` +create :create_post, MyApp.Post, :create + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-create-name){: #steps-create-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`resource`](#steps-create-resource){: #steps-create-resource .spark-required} | ``any`` | | The resource to call the action on. | +| [`action`](#steps-create-action){: #steps-create-action .spark-required} | ``any`` | | The action to call on the resource. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`upsert?`](#steps-create-upsert?){: #steps-create-upsert? } | `boolean` | `false` | Whether or not this action is always an upsert. | +| [`upsert_identity`](#steps-create-upsert_identity){: #steps-create-upsert_identity } | `atom` | | The identity to use for the upsert. | +| [`short_name`](#steps-create-short_name){: #steps-create-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-create-wait_for){: #steps-create-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-create-touches_resources){: #steps-create-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-create-halt_if){: #steps-create-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-create-halt_reason){: #steps-create-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-create-description){: #steps-create-description } | `String.t` | | A description for the step. | +| [`api`](#steps-create-api){: #steps-create-api } | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. | +| [`tenant`](#steps-create-tenant){: #steps-create-tenant } | ``any`` | | A tenant to use for the operation. May be a template or a literal value. | +| [`input`](#steps-create-input){: #steps-create-input } | ``any`` | | A template for the input. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Create` + +## steps.debug +```elixir +debug name +``` + + +Declares a step that will inspect its input and provide +additional debug information. + + + + +### Examples +``` +debug :show_some_information do + input %{post: result(:create_post)} +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-debug-name){: #steps-debug-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`input`](#steps-debug-input){: #steps-debug-input } | ``any`` | | A template for the input. | +| [`short_name`](#steps-debug-short_name){: #steps-debug-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-debug-wait_for){: #steps-debug-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`halt_if`](#steps-debug-halt_if){: #steps-debug-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-debug-halt_reason){: #steps-debug-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-debug-description){: #steps-debug-description } | `String.t` | | A description for the step. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Debug` + +## steps.update +```elixir +update name, resource, action +``` + + +Declares a step that will call a update action on a resource. + + + + +### Examples +``` +update :update_post, MyApp.Post, :update do + record result(:get_post) +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-update-name){: #steps-update-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`resource`](#steps-update-resource){: #steps-update-resource .spark-required} | ``any`` | | The resource to call the action on. | +| [`action`](#steps-update-action){: #steps-update-action .spark-required} | ``any`` | | The action to call on the resource. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`record`](#steps-update-record){: #steps-update-record .spark-required} | ``any`` | | The record to be updated, can use template helpers, e.g `result(:step_name)`. | +| [`short_name`](#steps-update-short_name){: #steps-update-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-update-wait_for){: #steps-update-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-update-touches_resources){: #steps-update-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-update-halt_if){: #steps-update-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-update-halt_reason){: #steps-update-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-update-description){: #steps-update-description } | `String.t` | | A description for the step. | +| [`api`](#steps-update-api){: #steps-update-api } | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. | +| [`tenant`](#steps-update-tenant){: #steps-update-tenant } | ``any`` | | A tenant to use for the operation. May be a template or a literal value. | +| [`input`](#steps-update-input){: #steps-update-input } | ``any`` | | A template for the input. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Update` + +## steps.destroy +```elixir +destroy name, resource, action +``` + + +Declares a step that will call a destroy action on a resource. + + + + +### Examples +``` +destroy :destroy_post, MyApp.Post, :destroy + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-destroy-name){: #steps-destroy-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`resource`](#steps-destroy-resource){: #steps-destroy-resource .spark-required} | ``any`` | | The resource to call the action on. | +| [`action`](#steps-destroy-action){: #steps-destroy-action .spark-required} | ``any`` | | The action to call on the resource. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`record`](#steps-destroy-record){: #steps-destroy-record .spark-required} | ``any`` | | The record to be updated, can use template helpers, e.g `result(:step_name)`. | +| [`short_name`](#steps-destroy-short_name){: #steps-destroy-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-destroy-wait_for){: #steps-destroy-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-destroy-touches_resources){: #steps-destroy-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-destroy-halt_if){: #steps-destroy-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-destroy-halt_reason){: #steps-destroy-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-destroy-description){: #steps-destroy-description } | `String.t` | | A description for the step. | +| [`api`](#steps-destroy-api){: #steps-destroy-api } | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. | +| [`tenant`](#steps-destroy-tenant){: #steps-destroy-tenant } | ``any`` | | A tenant to use for the operation. May be a template or a literal value. | +| [`input`](#steps-destroy-input){: #steps-destroy-input } | ``any`` | | A template for the input. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Destroy` + +## steps.validate +```elixir +validate name, resource, action +``` + + +Validates some input against an action. + + + + +### Examples +``` +validate :update_post, MyApp.Post, :update do + record result(:get_post) + only_keys [:name] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-validate-name){: #steps-validate-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`resource`](#steps-validate-resource){: #steps-validate-resource .spark-required} | ``any`` | | The resource to call the action on. | +| [`action`](#steps-validate-action){: #steps-validate-action .spark-required} | ``any`` | | The action to call on the resource. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`record`](#steps-validate-record){: #steps-validate-record } | ``any`` | | The record to be created/updated/destroyed. If the value is `nil` and would be required by the action type, the step is skipped and `nil` is the result of the step. | +| [`only_keys`](#steps-validate-only_keys){: #steps-validate-only_keys } | `list(atom \| list(atom))` | | A list of keys or paths to keys that should be validated. Others will be ignored, and errors generated for other fields will be ignored. | +| [`short_name`](#steps-validate-short_name){: #steps-validate-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-validate-wait_for){: #steps-validate-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-validate-touches_resources){: #steps-validate-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-validate-halt_if){: #steps-validate-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-validate-halt_reason){: #steps-validate-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-validate-description){: #steps-validate-description } | `String.t` | | A description for the step. | +| [`api`](#steps-validate-api){: #steps-validate-api } | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. | +| [`tenant`](#steps-validate-tenant){: #steps-validate-tenant } | ``any`` | | A tenant to use for the operation. May be a template or a literal value. | +| [`input`](#steps-validate-input){: #steps-validate-input } | ``any`` | | A template for the input. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Update` + +## steps.read +```elixir +read name, resource, action +``` + + +Declares a step that will call a read action on a resource. + + + + +### Examples +``` +read :destroy_post, MyApp.Post, :destroy + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-read-name){: #steps-read-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`resource`](#steps-read-resource){: #steps-read-resource .spark-required} | ``any`` | | The resource to call the action on. | +| [`action`](#steps-read-action){: #steps-read-action .spark-required} | ``any`` | | The action to call on the resource. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`get?`](#steps-read-get?){: #steps-read-get? } | `boolean` | `false` | Whether or not read action is expected to return a single result or `nil`. Set to `true` automatically if `get? true`. | +| [`not_found_error?`](#steps-read-not_found_error?){: #steps-read-not_found_error? } | `boolean` | `true` | Whether or not finding no record should result in a not found error | +| [`short_name`](#steps-read-short_name){: #steps-read-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-read-wait_for){: #steps-read-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-read-touches_resources){: #steps-read-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-read-halt_if){: #steps-read-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-read-halt_reason){: #steps-read-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-read-description){: #steps-read-description } | `String.t` | | A description for the step. | +| [`api`](#steps-read-api){: #steps-read-api } | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. | +| [`tenant`](#steps-read-tenant){: #steps-read-tenant } | ``any`` | | A tenant to use for the operation. May be a template or a literal value. | +| [`input`](#steps-read-input){: #steps-read-input } | ``any`` | | A template for the input. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Read` + +## steps.run_flow +```elixir +run_flow name, flow +``` + + +Runs another flow as part of the current flow. +The return value of the step is the return value of the flow. + + + + +### Examples +``` +run_flow :get_org, GetOrgByName do + input %{ + name: arg(:org_name) + } + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-run_flow-name){: #steps-run_flow-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`flow`](#steps-run_flow-flow){: #steps-run_flow-flow .spark-required} | `atom` | | The flow to run. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`input`](#steps-run_flow-input){: #steps-run_flow-input } | ``any`` | | A template for the input. | +| [`short_name`](#steps-run_flow-short_name){: #steps-run_flow-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-run_flow-wait_for){: #steps-run_flow-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-run_flow-touches_resources){: #steps-run_flow-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-run_flow-halt_if){: #steps-run_flow-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-run_flow-halt_reason){: #steps-run_flow-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-run_flow-description){: #steps-run_flow-description } | `String.t` | | A description for the step. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.RunFlow` + +## steps.custom +```elixir +custom name, custom +``` + + +Runs a custom step module. + +See `Ash.Flow.Step` for the necessary callbacks and more information. + + + + +### Examples +``` +custom :do_custom_thing, MyApp.DoCustomThing do + input %{...} +end + +``` + +``` +custom :do_custom_thing, {MyApp.DoCustomThing, opt1: :foo, opt2: :bar} do + input %{...} +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#steps-custom-name){: #steps-custom-name .spark-required} | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. | +| [`custom`](#steps-custom-custom){: #steps-custom-custom } | `(any, any -> any) \| module` | | The module that implements the step behaviour. Also accepts a 2 argument function that takes the input and the context. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`input`](#steps-custom-input){: #steps-custom-input } | ``any`` | | A template for the input. | +| [`async?`](#steps-custom-async?){: #steps-custom-async? } | `boolean` | `false` | Whether or not this step can be run outside of the current process. | +| [`short_name`](#steps-custom-short_name){: #steps-custom-short_name } | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. | +| [`wait_for`](#steps-custom-wait_for){: #steps-custom-wait_for } | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. | +| [`touches_resources`](#steps-custom-touches_resources){: #steps-custom-touches_resources } | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. | +| [`halt_if`](#steps-custom-halt_if){: #steps-custom-halt_if } | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. | +| [`halt_reason`](#steps-custom-halt_reason){: #steps-custom-halt_reason } | ``any`` | `:halted` | Configures the reason for the `halt_if` clause. | +| [`description`](#steps-custom-description){: #steps-custom-description } | `String.t` | | A description for the step. | + + + + + +### Introspection + +Target: `Ash.Flow.Step.Custom` + + + + + + diff --git a/documentation/dsls/DSL:-Ash.Notifier.PubSub.cheatmd b/documentation/dsls/DSL:-Ash.Notifier.PubSub.cheatmd deleted file mode 100644 index e7a27c5f6..000000000 --- a/documentation/dsls/DSL:-Ash.Notifier.PubSub.cheatmd +++ /dev/null @@ -1,440 +0,0 @@ - -# DSL: Ash.Notifier.PubSub - -A pubsub notifier extension. - - -## pub_sub -A section for configuring how resource actions are published over pubsub - -See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guide for more. - - -### Nested DSLs - * [publish](#pub_sub-publish) - * [publish_all](#pub_sub-publish_all) - - -### Examples -``` -pub_sub do - module MyEndpoint - prefix "post" - - publish :destroy, ["foo", :id] - publish :update, ["bar", :name] event: "name_change" - publish_all :create, "created" -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - module - - - * - - - atom - - - - The module to call `broadcast/3` on e.g module.broadcast(topic, event, message). -
- - - prefix - - - - - String.t - - - - A prefix for all pubsub messages, e.g `users`. A message with `created` would be published as `users:created` -
- - - broadcast_type - - - - - :notification | :phoenix_broadcast | :broadcast - - :notification - - What shape the event payloads will be in. See - -
- - - name - - - - - atom - - - - A named pub sub to pass as the first argument to broadcast. -
- - - -## pub_sub.publish -```elixir -publish action, topic -``` - - -Configure a given action to publish its results over a given topic. - -See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guides for more. - - - - -### Examples -``` -publish :create, "created" -``` - -``` -publish :assign, "assigned" - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - action - - - * - - - atom - - - - The name of the action that should be published -
- - - topic - - - * - - - `any` - - - - The topic to publish -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - event - - - - - String.t - - - - The name of the event to publish. Defaults to the action name -
- - - dispatcher - - - - - atom - - - - The module to use as a dispatcher. If none is set, the pubsub module provided is used. -
- - - - - -### Introspection - -Target: `Ash.Notifier.PubSub.Publication` - -## pub_sub.publish_all -```elixir -publish_all type, topic -``` - - -Works just like `publish`, except that it takes a type -and publishes all actions of that type - -See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guides for more. - - - - -### Examples -``` -publish_all :create, "created" -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - type - - - - - :create | :update | :destroy - - - - Publish on all actions of a given type -
- - - topic - - - * - - - `any` - - - - The topic to publish -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - action - - - - - atom - - - - The name of the action that should be published -
- - - event - - - - - String.t - - - - The name of the event to publish. Defaults to the action name -
- - - dispatcher - - - - - atom - - - - The module to use as a dispatcher. If none is set, the pubsub module provided is used. -
- - - - - -### Introspection - -Target: `Ash.Notifier.PubSub.Publication` - - - - diff --git a/documentation/dsls/DSL:-Ash.Notifier.PubSub.md b/documentation/dsls/DSL:-Ash.Notifier.PubSub.md new file mode 100644 index 000000000..358d32851 --- /dev/null +++ b/documentation/dsls/DSL:-Ash.Notifier.PubSub.md @@ -0,0 +1,140 @@ + +# DSL: Ash.Notifier.PubSub + +A pubsub notifier extension. + + +## pub_sub +A section for configuring how resource actions are published over pubsub + +See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guide for more. + + +### Nested DSLs + * [publish](#pub_sub-publish) + * [publish_all](#pub_sub-publish_all) + + +### Examples +``` +pub_sub do + module MyEndpoint + prefix "post" + + publish :destroy, ["foo", :id] + publish :update, ["bar", :name] event: "name_change" + publish_all :create, "created" +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`module`](#pub_sub-module){: #pub_sub-module .spark-required} | `atom` | | The module to call `broadcast/3` on e.g module.broadcast(topic, event, message). | +| [`prefix`](#pub_sub-prefix){: #pub_sub-prefix } | `String.t` | | A prefix for all pubsub messages, e.g `users`. A message with `created` would be published as `users:created` | +| [`broadcast_type`](#pub_sub-broadcast_type){: #pub_sub-broadcast_type } | `:notification \| :phoenix_broadcast \| :broadcast` | `:notification` | What shape the event payloads will be in. See | +| [`name`](#pub_sub-name){: #pub_sub-name } | `atom` | | A named pub sub to pass as the first argument to broadcast. | + + + +## pub_sub.publish +```elixir +publish action, topic +``` + + +Configure a given action to publish its results over a given topic. + +See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guides for more. + + + + +### Examples +``` +publish :create, "created" +``` + +``` +publish :assign, "assigned" + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`action`](#pub_sub-publish-action){: #pub_sub-publish-action .spark-required} | `atom` | | The name of the action that should be published | +| [`topic`](#pub_sub-publish-topic){: #pub_sub-publish-topic .spark-required} | ``any`` | | The topic to publish | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`event`](#pub_sub-publish-event){: #pub_sub-publish-event } | `String.t` | | The name of the event to publish. Defaults to the action name | +| [`dispatcher`](#pub_sub-publish-dispatcher){: #pub_sub-publish-dispatcher } | `atom` | | The module to use as a dispatcher. If none is set, the pubsub module provided is used. | + + + + + +### Introspection + +Target: `Ash.Notifier.PubSub.Publication` + +## pub_sub.publish_all +```elixir +publish_all type, topic +``` + + +Works just like `publish`, except that it takes a type +and publishes all actions of that type + +See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guides for more. + + + + +### Examples +``` +publish_all :create, "created" +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`type`](#pub_sub-publish_all-type){: #pub_sub-publish_all-type } | `:create \| :update \| :destroy` | | Publish on all actions of a given type | +| [`topic`](#pub_sub-publish_all-topic){: #pub_sub-publish_all-topic .spark-required} | ``any`` | | The topic to publish | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`action`](#pub_sub-publish_all-action){: #pub_sub-publish_all-action } | `atom` | | The name of the action that should be published | +| [`event`](#pub_sub-publish_all-event){: #pub_sub-publish_all-event } | `String.t` | | The name of the event to publish. Defaults to the action name | +| [`dispatcher`](#pub_sub-publish_all-dispatcher){: #pub_sub-publish_all-dispatcher } | `atom` | | The module to use as a dispatcher. If none is set, the pubsub module provided is used. | + + + + + +### Introspection + +Target: `Ash.Notifier.PubSub.Publication` + + + + + + diff --git a/documentation/dsls/DSL:-Ash.Policy.Authorizer.cheatmd b/documentation/dsls/DSL:-Ash.Policy.Authorizer.cheatmd deleted file mode 100644 index ee97e8bc1..000000000 --- a/documentation/dsls/DSL:-Ash.Policy.Authorizer.cheatmd +++ /dev/null @@ -1,2287 +0,0 @@ - -# DSL: Ash.Policy.Authorizer - -An authorization extension for ash resources. - -To add this extension to a resource, add it to the list of `authorizers` like so: - -```elixir -use Ash.Resource, - ..., - authorizers: [ - Ash.Policy.Authorizer - ] -``` - -A resource can be given a set of policies, which are enforced on each call to a resource action. - -For reads, policies can be configured to filter out data that the actor shouldn't see, as opposed to -resulting in a forbidden error. - -See the [policies guide](/documentation/topics/policies.md) for practical examples. - -Policies are solved/managed via a boolean satisfiability solver. To read more about boolean satisfiability, -see this page: https://en.wikipedia.org/wiki/Boolean_satisfiability_problem. At the end of -the day, however, it is not necessary to understand exactly how Ash takes your -authorization requirements and determines if a request is allowed. The -important thing to understand is that Ash may or may not run any/all of your -authorization rules as they may be deemed unnecessary. As such, authorization -checks should have no side effects. Ideally, the checks built-in to ash should -cover the bulk of your needs. - - -## policies -A section for declaring authorization policies. - -Each policy that applies must pass independently in order for the -request to be authorized. - -See the [policies guide](/documentation/topics/policies.md) for more. - - -### Nested DSLs - * [policy](#policies-policy) - * authorize_if - * forbid_if - * authorize_unless - * forbid_unless - * [bypass](#policies-bypass) - * authorize_if - * forbid_if - * authorize_unless - * forbid_unless - - -### Examples -``` -policies do - # Anything you can use in a condition, you can use in a check, and vice-versa - # This policy applies if the actor is a super_user - # Additionally, this policy is declared as a `bypass`. That means that this check is allowed to fail without - # failing the whole request, and that if this check *passes*, the entire request passes. - bypass actor_attribute_equals(:super_user, true) do - authorize_if always() - end - - # This will likely be a common occurrence. Specifically, policies that apply to all read actions - policy action_type(:read) do - # unless the actor is an active user, forbid their request - forbid_unless actor_attribute_equals(:active, true) - # if the record is marked as public, authorize the request - authorize_if attribute(:public, true) - # if the actor is related to the data via that data's `owner` relationship, authorize the request - authorize_if relates_to_actor_via(:owner) - end -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - default_access_type - - - - - :strict | :filter | :runtime - - :filter - - The default access type of policies for this resource. - -
- - - -## policies.policy -```elixir -policy condition -``` - - -A policy has a name, a condition, and a list of checks. - -Checks apply logically in the order they are specified, from top to bottom. -If no check explicitly authorizes the request, then the request is forbidden. -This means that, if you want to "blacklist" instead of "whitelist", you likely -want to add an `authorize_if always()` at the bottom of your policy, like so: - -```elixir -policy action_type(:read) do -forbid_if not_logged_in() -forbid_if user_is_denylisted() -forbid_if user_is_in_denylisted_group() - -authorize_if always() -end -``` - -If the policy should always run, use the `always()` check, like so: - -```elixir -policy always() do -... -end -``` - -See the [policies guide](/documentation/topics/policies.md) for more. - - -### Nested DSLs - * [authorize_if](#policies-policy-authorize_if) - * [forbid_if](#policies-policy-forbid_if) - * [authorize_unless](#policies-policy-authorize_unless) - * [forbid_unless](#policies-policy-forbid_unless) - - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - condition - - - - - `any` - - - - A check or list of checks that must be true in order for this policy to apply. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - A description for the policy, used when explaining authorization results -
- - - access_type - - - - - :strict | :filter | :runtime - - - - What portion of the checks inside the policy are allowed to run. See the guide for more. - -
- - -## policies.policy.authorize_if -```elixir -authorize_if check -``` - - -If the check is true, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_if logged_in() -``` - -``` -authorize_if actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## policies.policy.forbid_if -```elixir -forbid_if check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_if not_logged_in() -``` - -``` -forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## policies.policy.authorize_unless -```elixir -authorize_unless check -``` - - -If the check is false, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_unless not_logged_in() -``` - -``` -authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## policies.policy.forbid_unless -```elixir -forbid_unless check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_unless logged_in() -``` - -``` -forbid_unless actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - - - - -### Introspection - -Target: `Ash.Policy.Policy` - -## policies.bypass -```elixir -bypass condition -``` - - -A policy that, if passed, will skip all following policies. If failed, authorization moves on to the next policy - -### Nested DSLs - * [authorize_if](#policies-bypass-authorize_if) - * [forbid_if](#policies-bypass-forbid_if) - * [authorize_unless](#policies-bypass-authorize_unless) - * [forbid_unless](#policies-bypass-forbid_unless) - - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - condition - - - - - `any` - - - - A check or list of checks that must be true in order for this policy to apply. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - A description for the policy, used when explaining authorization results -
- - - access_type - - - - - :strict | :filter | :runtime - - - - What portion of the checks inside the policy are allowed to run. See the guide for more. - -
- - -## policies.bypass.authorize_if -```elixir -authorize_if check -``` - - -If the check is true, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_if logged_in() -``` - -``` -authorize_if actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## policies.bypass.forbid_if -```elixir -forbid_if check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_if not_logged_in() -``` - -``` -forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## policies.bypass.authorize_unless -```elixir -authorize_unless check -``` - - -If the check is false, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_unless not_logged_in() -``` - -``` -authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## policies.bypass.forbid_unless -```elixir -forbid_unless check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_unless logged_in() -``` - -``` -forbid_unless actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - - - - -### Introspection - -Target: `Ash.Policy.Policy` - - - - -## field_policies -Authorize access to specific fields via policies scoped to fields. - -If *any* field policies exist then *all* fields must be authorized by a field policy. -If you want a "deny-list" style, then you can add policies for specific fields -and add a catch-all policy using the special field name `:*`. All policies that apply -to a field must be authorized. - -The only exception to the above behavior is primary keys, which can always be read by everyone. - -Additionally, keep in mind that adding `Ash.Policy.Authorizer` will require that all actions -pass policies. If you want to just add field policies, you will need to add a policy that allows -all access explicitly, i.e - -```elixir -policies do -policy always() do -authorize_if always() -end -end -``` - -Using expressions: unlike in regular policies, expressions in field policies cannot refer -to related entities currently. Instead, you will need to create aggregates or expression calculations -that return the results you want to reference. - -In results, forbidden fields will be replaced with a special value: `%Ash.ForbiddenField{}`. - -When these fields are referred to in filters, they will be replaced with an expression that evaluates -to `nil`. To support this behavior, only expression/filter checks are allowed in field policies. - - -### Nested DSLs - * [field_policy_bypass](#field_policies-field_policy_bypass) - * authorize_if - * forbid_if - * authorize_unless - * forbid_unless - * [field_policy](#field_policies-field_policy) - * authorize_if - * forbid_if - * authorize_unless - * forbid_unless - - -### Examples -``` -field_policies do - field_policy :admin_only_field do - authorize_if actor_attribute_equals(:admin, true) - end -end - -``` - -``` -# Example of denylist style -field_policies do - field_policy [:sensitive, :fields] do - authorize_if actor_attribute_equals(:admin, true) - end - - field_policy :* do - authorize_if always() - end -end - -``` - - - - -## field_policies.field_policy_bypass -```elixir -field_policy_bypass fields, condition \ {Ash.Policy.Check.Static, [result: true]} -``` - - -A field policy that, if passed, will skip all following field policies for that field or fields. If failed, field authorization moves on to the next policy - -### Nested DSLs - * [authorize_if](#field_policies-field_policy_bypass-authorize_if) - * [forbid_if](#field_policies-field_policy_bypass-forbid_if) - * [authorize_unless](#field_policies-field_policy_bypass-authorize_unless) - * [forbid_unless](#field_policies-field_policy_bypass-forbid_unless) - - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - fields - - - - - atom | list(atom) - - - - The field or fields that the policy applies to. -
- - - condition - - - - - `any` - - - - A check or list of checks that must be true in order for this field policy to apply. If not specified, it always applies. -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - A description for the policy, used when explaining authorization results -
- - -## field_policies.field_policy_bypass.authorize_if -```elixir -authorize_if check -``` - - -If the check is true, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_if logged_in() -``` - -``` -authorize_if actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## field_policies.field_policy_bypass.forbid_if -```elixir -forbid_if check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_if not_logged_in() -``` - -``` -forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## field_policies.field_policy_bypass.authorize_unless -```elixir -authorize_unless check -``` - - -If the check is false, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_unless not_logged_in() -``` - -``` -authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## field_policies.field_policy_bypass.forbid_unless -```elixir -forbid_unless check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_unless logged_in() -``` - -``` -forbid_unless actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - - - - -### Introspection - -Target: `Ash.Policy.FieldPolicy` - -## field_policies.field_policy -```elixir -field_policy fields, condition \ {Ash.Policy.Check.Static, [result: true]} -``` - - -Field policies behave similarly to policies. See `d:Ash.Policy.Authorizer.field_policies` -for more. - - -### Nested DSLs - * [authorize_if](#field_policies-field_policy-authorize_if) - * [forbid_if](#field_policies-field_policy-forbid_if) - * [authorize_unless](#field_policies-field_policy-authorize_unless) - * [forbid_unless](#field_policies-field_policy-forbid_unless) - - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - fields - - - - - atom | list(atom) - - - - The field or fields that the policy applies to. -
- - - condition - - - - - `any` - - - - A check or list of checks that must be true in order for this field policy to apply. If not specified, it always applies. -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - A description for the policy, used when explaining authorization results -
- - -## field_policies.field_policy.authorize_if -```elixir -authorize_if check -``` - - -If the check is true, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_if logged_in() -``` - -``` -authorize_if actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## field_policies.field_policy.forbid_if -```elixir -forbid_if check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_if not_logged_in() -``` - -``` -forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## field_policies.field_policy.authorize_unless -```elixir -authorize_unless check -``` - - -If the check is false, the request is authorized, otherwise run remaining checks. - - - -### Examples -``` -authorize_unless not_logged_in() -``` - -``` -authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - -## field_policies.field_policy.forbid_unless -```elixir -forbid_unless check -``` - - -If the check is true, the request is forbidden, otherwise run remaining checks. - - - -### Examples -``` -forbid_unless logged_in() -``` - -``` -forbid_unless actor_attribute_matches_record(:group, :group) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - check - - - * - - - `any` - - - - The check to run. See `Ash.Policy.Check` for more. - -
-### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - String.t - - - - A short name or description for the check, used when explaining authorization results -
- - - - - -### Introspection - -Target: `Ash.Policy.Check` - - - - -### Introspection - -Target: `Ash.Policy.FieldPolicy` - - - - diff --git a/documentation/dsls/DSL:-Ash.Policy.Authorizer.md b/documentation/dsls/DSL:-Ash.Policy.Authorizer.md new file mode 100644 index 000000000..1fea43e50 --- /dev/null +++ b/documentation/dsls/DSL:-Ash.Policy.Authorizer.md @@ -0,0 +1,987 @@ + +# DSL: Ash.Policy.Authorizer + +An authorization extension for ash resources. + +To add this extension to a resource, add it to the list of `authorizers` like so: + +```elixir +use Ash.Resource, + ..., + authorizers: [ + Ash.Policy.Authorizer + ] +``` + +A resource can be given a set of policies, which are enforced on each call to a resource action. + +For reads, policies can be configured to filter out data that the actor shouldn't see, as opposed to +resulting in a forbidden error. + +See the [policies guide](/documentation/topics/policies.md) for practical examples. + +Policies are solved/managed via a boolean satisfiability solver. To read more about boolean satisfiability, +see this page: https://en.wikipedia.org/wiki/Boolean_satisfiability_problem. At the end of +the day, however, it is not necessary to understand exactly how Ash takes your +authorization requirements and determines if a request is allowed. The +important thing to understand is that Ash may or may not run any/all of your +authorization rules as they may be deemed unnecessary. As such, authorization +checks should have no side effects. Ideally, the checks built-in to ash should +cover the bulk of your needs. + + +## policies +A section for declaring authorization policies. + +Each policy that applies must pass independently in order for the +request to be authorized. + +See the [policies guide](/documentation/topics/policies.md) for more. + + +### Nested DSLs + * [policy](#policies-policy) + * authorize_if + * forbid_if + * authorize_unless + * forbid_unless + * [bypass](#policies-bypass) + * authorize_if + * forbid_if + * authorize_unless + * forbid_unless + + +### Examples +``` +policies do + # Anything you can use in a condition, you can use in a check, and vice-versa + # This policy applies if the actor is a super_user + # Additionally, this policy is declared as a `bypass`. That means that this check is allowed to fail without + # failing the whole request, and that if this check *passes*, the entire request passes. + bypass actor_attribute_equals(:super_user, true) do + authorize_if always() + end + + # This will likely be a common occurrence. Specifically, policies that apply to all read actions + policy action_type(:read) do + # unless the actor is an active user, forbid their request + forbid_unless actor_attribute_equals(:active, true) + # if the record is marked as public, authorize the request + authorize_if attribute(:public, true) + # if the actor is related to the data via that data's `owner` relationship, authorize the request + authorize_if relates_to_actor_via(:owner) + end +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`default_access_type`](#policies-default_access_type){: #policies-default_access_type } | `:strict \| :filter \| :runtime` | `:filter` | The default access type of policies for this resource. | + + + +## policies.policy +```elixir +policy condition +``` + + +A policy has a name, a condition, and a list of checks. + +Checks apply logically in the order they are specified, from top to bottom. +If no check explicitly authorizes the request, then the request is forbidden. +This means that, if you want to "blacklist" instead of "whitelist", you likely +want to add an `authorize_if always()` at the bottom of your policy, like so: + +```elixir +policy action_type(:read) do +forbid_if not_logged_in() +forbid_if user_is_denylisted() +forbid_if user_is_in_denylisted_group() + +authorize_if always() +end +``` + +If the policy should always run, use the `always()` check, like so: + +```elixir +policy always() do +... +end +``` + +See the [policies guide](/documentation/topics/policies.md) for more. + + +### Nested DSLs + * [authorize_if](#policies-policy-authorize_if) + * [forbid_if](#policies-policy-forbid_if) + * [authorize_unless](#policies-policy-authorize_unless) + * [forbid_unless](#policies-policy-forbid_unless) + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`condition`](#policies-policy-condition){: #policies-policy-condition } | ``any`` | | A check or list of checks that must be true in order for this policy to apply. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#policies-policy-description){: #policies-policy-description } | `String.t` | | A description for the policy, used when explaining authorization results | +| [`access_type`](#policies-policy-access_type){: #policies-policy-access_type } | `:strict \| :filter \| :runtime` | | What portion of the checks inside the policy are allowed to run. See the guide for more. | + + +## policies.policy.authorize_if +```elixir +authorize_if check +``` + + +If the check is true, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_if logged_in() +``` + +``` +authorize_if actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-policy-authorize_if-check){: #policies-policy-authorize_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-policy-authorize_if-name){: #policies-policy-authorize_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## policies.policy.forbid_if +```elixir +forbid_if check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_if not_logged_in() +``` + +``` +forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-policy-forbid_if-check){: #policies-policy-forbid_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-policy-forbid_if-name){: #policies-policy-forbid_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## policies.policy.authorize_unless +```elixir +authorize_unless check +``` + + +If the check is false, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_unless not_logged_in() +``` + +``` +authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-policy-authorize_unless-check){: #policies-policy-authorize_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-policy-authorize_unless-name){: #policies-policy-authorize_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## policies.policy.forbid_unless +```elixir +forbid_unless check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_unless logged_in() +``` + +``` +forbid_unless actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-policy-forbid_unless-check){: #policies-policy-forbid_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-policy-forbid_unless-name){: #policies-policy-forbid_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + + + + +### Introspection + +Target: `Ash.Policy.Policy` + +## policies.bypass +```elixir +bypass condition +``` + + +A policy that, if passed, will skip all following policies. If failed, authorization moves on to the next policy + +### Nested DSLs + * [authorize_if](#policies-bypass-authorize_if) + * [forbid_if](#policies-bypass-forbid_if) + * [authorize_unless](#policies-bypass-authorize_unless) + * [forbid_unless](#policies-bypass-forbid_unless) + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`condition`](#policies-bypass-condition){: #policies-bypass-condition } | ``any`` | | A check or list of checks that must be true in order for this policy to apply. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#policies-bypass-description){: #policies-bypass-description } | `String.t` | | A description for the policy, used when explaining authorization results | +| [`access_type`](#policies-bypass-access_type){: #policies-bypass-access_type } | `:strict \| :filter \| :runtime` | | What portion of the checks inside the policy are allowed to run. See the guide for more. | + + +## policies.bypass.authorize_if +```elixir +authorize_if check +``` + + +If the check is true, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_if logged_in() +``` + +``` +authorize_if actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-bypass-authorize_if-check){: #policies-bypass-authorize_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-bypass-authorize_if-name){: #policies-bypass-authorize_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## policies.bypass.forbid_if +```elixir +forbid_if check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_if not_logged_in() +``` + +``` +forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-bypass-forbid_if-check){: #policies-bypass-forbid_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-bypass-forbid_if-name){: #policies-bypass-forbid_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## policies.bypass.authorize_unless +```elixir +authorize_unless check +``` + + +If the check is false, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_unless not_logged_in() +``` + +``` +authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-bypass-authorize_unless-check){: #policies-bypass-authorize_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-bypass-authorize_unless-name){: #policies-bypass-authorize_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## policies.bypass.forbid_unless +```elixir +forbid_unless check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_unless logged_in() +``` + +``` +forbid_unless actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#policies-bypass-forbid_unless-check){: #policies-bypass-forbid_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#policies-bypass-forbid_unless-name){: #policies-bypass-forbid_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + + + + +### Introspection + +Target: `Ash.Policy.Policy` + + + + +## field_policies +Authorize access to specific fields via policies scoped to fields. + +If *any* field policies exist then *all* fields must be authorized by a field policy. +If you want a "deny-list" style, then you can add policies for specific fields +and add a catch-all policy using the special field name `:*`. All policies that apply +to a field must be authorized. + +The only exception to the above behavior is primary keys, which can always be read by everyone. + +Additionally, keep in mind that adding `Ash.Policy.Authorizer` will require that all actions +pass policies. If you want to just add field policies, you will need to add a policy that allows +all access explicitly, i.e + +```elixir +policies do +policy always() do +authorize_if always() +end +end +``` + +Using expressions: unlike in regular policies, expressions in field policies cannot refer +to related entities currently. Instead, you will need to create aggregates or expression calculations +that return the results you want to reference. + +In results, forbidden fields will be replaced with a special value: `%Ash.ForbiddenField{}`. + +When these fields are referred to in filters, they will be replaced with an expression that evaluates +to `nil`. To support this behavior, only expression/filter checks are allowed in field policies. + + +### Nested DSLs + * [field_policy_bypass](#field_policies-field_policy_bypass) + * authorize_if + * forbid_if + * authorize_unless + * forbid_unless + * [field_policy](#field_policies-field_policy) + * authorize_if + * forbid_if + * authorize_unless + * forbid_unless + + +### Examples +``` +field_policies do + field_policy :admin_only_field do + authorize_if actor_attribute_equals(:admin, true) + end +end + +``` + +``` +# Example of denylist style +field_policies do + field_policy [:sensitive, :fields] do + authorize_if actor_attribute_equals(:admin, true) + end + + field_policy :* do + authorize_if always() + end +end + +``` + + + + +## field_policies.field_policy_bypass +```elixir +field_policy_bypass fields, condition \\ {Ash.Policy.Check.Static, [result: true]} +``` + + +A field policy that, if passed, will skip all following field policies for that field or fields. If failed, field authorization moves on to the next policy + +### Nested DSLs + * [authorize_if](#field_policies-field_policy_bypass-authorize_if) + * [forbid_if](#field_policies-field_policy_bypass-forbid_if) + * [authorize_unless](#field_policies-field_policy_bypass-authorize_unless) + * [forbid_unless](#field_policies-field_policy_bypass-forbid_unless) + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`fields`](#field_policies-field_policy_bypass-fields){: #field_policies-field_policy_bypass-fields } | `atom \| list(atom)` | | The field or fields that the policy applies to. | +| [`condition`](#field_policies-field_policy_bypass-condition){: #field_policies-field_policy_bypass-condition } | ``any`` | | A check or list of checks that must be true in order for this field policy to apply. If not specified, it always applies. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#field_policies-field_policy_bypass-description){: #field_policies-field_policy_bypass-description } | `String.t` | | A description for the policy, used when explaining authorization results | + + +## field_policies.field_policy_bypass.authorize_if +```elixir +authorize_if check +``` + + +If the check is true, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_if logged_in() +``` + +``` +authorize_if actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy_bypass-authorize_if-check){: #field_policies-field_policy_bypass-authorize_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy_bypass-authorize_if-name){: #field_policies-field_policy_bypass-authorize_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## field_policies.field_policy_bypass.forbid_if +```elixir +forbid_if check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_if not_logged_in() +``` + +``` +forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy_bypass-forbid_if-check){: #field_policies-field_policy_bypass-forbid_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy_bypass-forbid_if-name){: #field_policies-field_policy_bypass-forbid_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## field_policies.field_policy_bypass.authorize_unless +```elixir +authorize_unless check +``` + + +If the check is false, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_unless not_logged_in() +``` + +``` +authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy_bypass-authorize_unless-check){: #field_policies-field_policy_bypass-authorize_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy_bypass-authorize_unless-name){: #field_policies-field_policy_bypass-authorize_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## field_policies.field_policy_bypass.forbid_unless +```elixir +forbid_unless check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_unless logged_in() +``` + +``` +forbid_unless actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy_bypass-forbid_unless-check){: #field_policies-field_policy_bypass-forbid_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy_bypass-forbid_unless-name){: #field_policies-field_policy_bypass-forbid_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + + + + +### Introspection + +Target: `Ash.Policy.FieldPolicy` + +## field_policies.field_policy +```elixir +field_policy fields, condition \\ {Ash.Policy.Check.Static, [result: true]} +``` + + +Field policies behave similarly to policies. See `d:Ash.Policy.Authorizer.field_policies` +for more. + + +### Nested DSLs + * [authorize_if](#field_policies-field_policy-authorize_if) + * [forbid_if](#field_policies-field_policy-forbid_if) + * [authorize_unless](#field_policies-field_policy-authorize_unless) + * [forbid_unless](#field_policies-field_policy-forbid_unless) + + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`fields`](#field_policies-field_policy-fields){: #field_policies-field_policy-fields } | `atom \| list(atom)` | | The field or fields that the policy applies to. | +| [`condition`](#field_policies-field_policy-condition){: #field_policies-field_policy-condition } | ``any`` | | A check or list of checks that must be true in order for this field policy to apply. If not specified, it always applies. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#field_policies-field_policy-description){: #field_policies-field_policy-description } | `String.t` | | A description for the policy, used when explaining authorization results | + + +## field_policies.field_policy.authorize_if +```elixir +authorize_if check +``` + + +If the check is true, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_if logged_in() +``` + +``` +authorize_if actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy-authorize_if-check){: #field_policies-field_policy-authorize_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy-authorize_if-name){: #field_policies-field_policy-authorize_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## field_policies.field_policy.forbid_if +```elixir +forbid_if check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_if not_logged_in() +``` + +``` +forbid_if actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy-forbid_if-check){: #field_policies-field_policy-forbid_if-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy-forbid_if-name){: #field_policies-field_policy-forbid_if-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## field_policies.field_policy.authorize_unless +```elixir +authorize_unless check +``` + + +If the check is false, the request is authorized, otherwise run remaining checks. + + + +### Examples +``` +authorize_unless not_logged_in() +``` + +``` +authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy-authorize_unless-check){: #field_policies-field_policy-authorize_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy-authorize_unless-name){: #field_policies-field_policy-authorize_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + +## field_policies.field_policy.forbid_unless +```elixir +forbid_unless check +``` + + +If the check is true, the request is forbidden, otherwise run remaining checks. + + + +### Examples +``` +forbid_unless logged_in() +``` + +``` +forbid_unless actor_attribute_matches_record(:group, :group) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`check`](#field_policies-field_policy-forbid_unless-check){: #field_policies-field_policy-forbid_unless-check .spark-required} | ``any`` | | The check to run. See `Ash.Policy.Check` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#field_policies-field_policy-forbid_unless-name){: #field_policies-field_policy-forbid_unless-name } | `String.t` | | A short name or description for the check, used when explaining authorization results | + + + + + +### Introspection + +Target: `Ash.Policy.Check` + + + + +### Introspection + +Target: `Ash.Policy.FieldPolicy` + + + + + + diff --git a/documentation/dsls/DSL:-Ash.Registry.cheatmd b/documentation/dsls/DSL:-Ash.Registry.cheatmd deleted file mode 100644 index af7a6243b..000000000 --- a/documentation/dsls/DSL:-Ash.Registry.cheatmd +++ /dev/null @@ -1,132 +0,0 @@ - -# DSL: Ash.Registry.Dsl - -A small DSL for declaring an `Ash.Registry`. Not generally necessary any longer. - -`Ash.Registry` can be used generically, but the main way it is used in Ash is to provide a compile-time registry for an Ash Api. - - -## entries -List the entries present in this registry - -### Nested DSLs - * [entry](#entries-entry) - - -### Examples -``` -entries do - entry MyApp.User - entry MyApp.Post - entry MyApp.Comment -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - warn_on_empty? - - - - - boolean - - true - - Set to `false` to ignore warnings about an empty registry -
- - - -## entries.entry -```elixir -entry entry -``` - - -A reference to an ash module (typically a resource) - - - -### Examples -``` -entry MyApp.User -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - entry - - - * - - - atom - - - - The referenced module -
- - - - - - -### Introspection - -Target: `Ash.Registry.Entry` - - - - diff --git a/documentation/dsls/DSL:-Ash.Registry.md b/documentation/dsls/DSL:-Ash.Registry.md new file mode 100644 index 000000000..e67ca2d04 --- /dev/null +++ b/documentation/dsls/DSL:-Ash.Registry.md @@ -0,0 +1,75 @@ + +# DSL: Ash.Registry.Dsl + +A small DSL for declaring an `Ash.Registry`. Not generally necessary any longer. + +`Ash.Registry` can be used generically, but the main way it is used in Ash is to provide a compile-time registry for an Ash Api. + + +## entries +List the entries present in this registry + +### Nested DSLs + * [entry](#entries-entry) + + +### Examples +``` +entries do + entry MyApp.User + entry MyApp.Post + entry MyApp.Comment +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`warn_on_empty?`](#entries-warn_on_empty?){: #entries-warn_on_empty? } | `boolean` | `true` | Set to `false` to ignore warnings about an empty registry | + + + +## entries.entry +```elixir +entry entry +``` + + +A reference to an ash module (typically a resource) + + + +### Examples +``` +entry MyApp.User +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`entry`](#entries-entry-entry){: #entries-entry-entry .spark-required} | `atom` | | The referenced module | + + + + + + +### Introspection + +Target: `Ash.Registry.Entry` + + + + + + diff --git a/documentation/dsls/DSL:-Ash.Resource.cheatmd b/documentation/dsls/DSL:-Ash.Resource.cheatmd deleted file mode 100644 index 598493473..000000000 --- a/documentation/dsls/DSL:-Ash.Resource.cheatmd +++ /dev/null @@ -1,13614 +0,0 @@ - -# DSL: Ash.Resource.Dsl - - - -## attributes -A section for declaring attributes on the resource. - - -### Nested DSLs - * [attribute](#attributes-attribute) - * [create_timestamp](#attributes-create_timestamp) - * [update_timestamp](#attributes-update_timestamp) - * [integer_primary_key](#attributes-integer_primary_key) - * [uuid_primary_key](#attributes-uuid_primary_key) - - -### Examples -``` -attributes do - uuid_primary_key :id - - attribute :first_name, :string do - allow_nil? false - end - - attribute :last_name, :string do - allow_nil? false - end - - attribute :email, :string do - allow_nil? false - - constraints [ - match: ~r/^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/ - ] - end - - attribute :type, :atom do - constraints [ - one_of: [:admin, :teacher, :student] - ] - end - - create_timestamp :inserted_at - update_timestamp :updated_at -end - -``` - - - - -## attributes.attribute -```elixir -attribute name, type -``` - - -Declares an attribute on the resource. - - - - -### Examples -``` -attribute :name, :string do - allow_nil? false -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the attribute. -
- - - type - - - * - - - module - - - - The type of the attribute. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - - - Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). - -
- - - description - - - - - String.t - - - - An optional description for the attribute. -
- - - sensitive? - - - - - boolean - - false - - Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. - -
- - - source - - - - - atom - - - - If the field should be mapped to a different name in the data layer. Support varies by data layer. - -
- - - always_select? - - - - - boolean - - false - - Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. - -
- - - primary_key? - - - - - boolean - - false - - Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. - -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the attribute can be set to nil. If nil value is given error is raised. - -
- - - generated? - - - - - boolean - - false - - Whether or not the value may be generated by the data layer. - -
- - - writable? - - - - - boolean - - true - - Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. - -
- - - private? - - - - - boolean - - false - - The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - (-> any) | mfa | any() - - - - A value to be set on all creates, unless a value is being provided already. -
- - - update_default - - - - - (-> any) | mfa | any() - - - - A value to be set on all updates, unless a value is being provided already. -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the attribute can be referenced in filters. - -
- - - match_other_defaults? - - - - - boolean - - false - - Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Attribute` - -## attributes.create_timestamp -```elixir -create_timestamp name -``` - - -Declares a non-writable attribute with a create default of `&DateTime.utc_now/0` - -Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except it sets -the following different defaults: - -writable? false -private? true -default &DateTime.utc_now/0 -match_other_defaults? true -type Ash.Type.UTCDatetimeUsec -allow_nil? false - - - - -### Examples -``` -create_timestamp :inserted_at -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the attribute. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - type - - - - - module - - Ash.Type.UtcDatetimeUsec - - The type of the attribute. See `Ash.Type` for more. -
- - - constraints - - - - - Keyword.t - - - - Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). - -
- - - description - - - - - String.t - - - - An optional description for the attribute. -
- - - sensitive? - - - - - boolean - - false - - Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. - -
- - - source - - - - - atom - - - - If the field should be mapped to a different name in the data layer. Support varies by data layer. - -
- - - always_select? - - - - - boolean - - false - - Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. - -
- - - primary_key? - - - - - boolean - - false - - Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. - -
- - - allow_nil? - - - - - boolean - - false - - Whether or not the attribute can be set to nil. If nil value is given error is raised. - -
- - - generated? - - - - - boolean - - false - - Whether or not the value may be generated by the data layer. - -
- - - writable? - - - - - boolean - - false - - Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. - -
- - - private? - - - - - boolean - - true - - The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - (-> any) | mfa | any() - - &DateTime.utc_now/0 - - A value to be set on all creates, unless a value is being provided already. -
- - - update_default - - - - - (-> any) | mfa | any() - - - - A value to be set on all updates, unless a value is being provided already. -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the attribute can be referenced in filters. - -
- - - match_other_defaults? - - - - - boolean - - true - - Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Attribute` - -## attributes.update_timestamp -```elixir -update_timestamp name -``` - - -Declares a non-writable attribute with a create and update default of `&DateTime.utc_now/0` - -Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except it sets -the following different defaults: - -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 :updated_at -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the attribute. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - type - - - - - module - - Ash.Type.UtcDatetimeUsec - - The type of the attribute. See `Ash.Type` for more. -
- - - constraints - - - - - Keyword.t - - - - Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). - -
- - - description - - - - - String.t - - - - An optional description for the attribute. -
- - - sensitive? - - - - - boolean - - false - - Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. - -
- - - source - - - - - atom - - - - If the field should be mapped to a different name in the data layer. Support varies by data layer. - -
- - - always_select? - - - - - boolean - - false - - Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. - -
- - - primary_key? - - - - - boolean - - false - - Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. - -
- - - allow_nil? - - - - - boolean - - false - - Whether or not the attribute can be set to nil. If nil value is given error is raised. - -
- - - generated? - - - - - boolean - - false - - Whether or not the value may be generated by the data layer. - -
- - - writable? - - - - - boolean - - false - - Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. - -
- - - private? - - - - - boolean - - true - - The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - (-> any) | mfa | any() - - &DateTime.utc_now/0 - - A value to be set on all creates, unless a value is being provided already. -
- - - update_default - - - - - (-> any) | mfa | any() - - &DateTime.utc_now/0 - - A value to be set on all updates, unless a value is being provided already. -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the attribute can be referenced in filters. - -
- - - match_other_defaults? - - - - - boolean - - true - - Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Attribute` - -## attributes.integer_primary_key -```elixir -integer_primary_key name -``` - - -Declares a generated, non writable, non-nil, primary key column of type integer. - -Generated integer primary keys must be supported by the data layer. - -Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except for `allow_nil?`, but it sets -the following different defaults: - -writable? false -primary_key? true -generated? true -type :integer - - - - -### Examples -``` -integer_primary_key :id -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the attribute. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - type - - - - - module - - :integer - - The type of the attribute. See `Ash.Type` for more. -
- - - constraints - - - - - Keyword.t - - - - Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). - -
- - - description - - - - - String.t - - - - An optional description for the attribute. -
- - - sensitive? - - - - - boolean - - false - - Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. - -
- - - source - - - - - atom - - - - If the field should be mapped to a different name in the data layer. Support varies by data layer. - -
- - - always_select? - - - - - boolean - - false - - Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. - -
- - - primary_key? - - - - - boolean - - true - - Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. - -
- - - generated? - - - - - boolean - - true - - Whether or not the value may be generated by the data layer. - -
- - - writable? - - - - - boolean - - false - - Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. - -
- - - private? - - - - - boolean - - false - - The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - (-> any) | mfa | any() - - - - A value to be set on all creates, unless a value is being provided already. -
- - - update_default - - - - - (-> any) | mfa | any() - - - - A value to be set on all updates, unless a value is being provided already. -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the attribute can be referenced in filters. - -
- - - match_other_defaults? - - - - - boolean - - false - - Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Attribute` - -## attributes.uuid_primary_key -```elixir -uuid_primary_key name -``` - - -Declares a non writable, non-nil, primary key column of type `uuid`, which defaults to `Ash.UUID.generate/0`. - -Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except for `allow_nil?`, but it sets -the following different defaults: - -writable? false -default &Ash.UUID.generate/0 -primary_key? true -generated? true -type :uuid - - - - -### Examples -``` -uuid_primary_key :id -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the attribute. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - type - - - - - module - - :uuid - - The type of the attribute. See `Ash.Type` for more. -
- - - constraints - - - - - Keyword.t - - - - Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). - -
- - - description - - - - - String.t - - - - An optional description for the attribute. -
- - - sensitive? - - - - - boolean - - false - - Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. - -
- - - source - - - - - atom - - - - If the field should be mapped to a different name in the data layer. Support varies by data layer. - -
- - - always_select? - - - - - boolean - - false - - Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. - -
- - - primary_key? - - - - - boolean - - true - - Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. - -
- - - generated? - - - - - boolean - - false - - Whether or not the value may be generated by the data layer. - -
- - - writable? - - - - - boolean - - false - - Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. - -
- - - private? - - - - - boolean - - false - - The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - (-> any) | mfa | any() - - &Ash.UUID.generate/0 - - A value to be set on all creates, unless a value is being provided already. -
- - - update_default - - - - - (-> any) | mfa | any() - - - - A value to be set on all updates, unless a value is being provided already. -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the attribute can be referenced in filters. - -
- - - match_other_defaults? - - - - - boolean - - false - - Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Attribute` - - - - -## relationships -A section for declaring relationships on the resource. - -Relationships are a core component of resource oriented design. Many components of Ash -will use these relationships. A simple use case is loading relationships (done via the `Ash.Query.load/2`). - -See the [relationships guide](/documentation/topics/relationships.md) for more. - - -### Nested DSLs - * [has_one](#relationships-has_one) - * [has_many](#relationships-has_many) - * [many_to_many](#relationships-many_to_many) - * [belongs_to](#relationships-belongs_to) - - -### Examples -``` -relationships do - belongs_to :post, MyApp.Post do - primary_key? true - end - - belongs_to :category, MyApp.Category do - primary_key? true - end -end - -``` - -``` -relationships do - belongs_to :author, MyApp.Author - - many_to_many :categories, MyApp.Category do - through MyApp.PostCategory - destination_attribute_on_join_resource :category_id - source_attribute_on_join_resource :post_id - end -end - -``` - -``` -relationships do - has_many :posts, MyApp.Post do - destination_attribute :author_id - end - - has_many :composite_key_posts, MyApp.CompositeKeyPost do - destination_attribute :author_id - end -end - -``` - - - - -## relationships.has_one -```elixir -has_one name, destination -``` - - -Declares a `has_one` relationship. In a relational database, the foreign key would be on the *other* table. - -Generally speaking, a `has_one` also implies that the destination table is unique on that foreign key. - -See the [relationships guide](/documentation/topics/relationships.md) for more. - - - - -### Examples -``` -# In a resource called `Word` -has_one :dictionary_entry, DictionaryEntry do - source_attribute :text - destination_attribute :word_text -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - atom - - - - The name of the relationship -
- - - destination - - - - - module - - - - The destination resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - manual - - - - - (any, any -> any) | module - - - - A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. - -
- - - no_attributes? - - - - - boolean - - - - All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/relationships.md) for more. - -
- - - allow_nil? - - - - - boolean - - true - - Marks the relationship as required. Has no effect on validations, but can inform extensions that there will always be a related entity. - -
- - - from_many? - - - - - boolean - - false - - Signal that this relationship is actually a `has_many` where the first record is given via the `sort`. This will allow data layers to properly deduplicate when necessary. - -
- - - description - - - - - String.t - - - - An optional description for the relationship -
- - - destination_attribute - - - - - atom - - - - The attribute on the related resource that should match the `source_attribute` configured on this resource. -
- - - validate_destination_attribute? - - - - - boolean - - true - - Whether or not to validate that the destination field exists on the destination resource -
- - - source_attribute - - - - - atom - - :id - - The field on this resource that should match the `destination_attribute` on the related resource. -
- - - relationship_context - - - - - `any` - - - - Context to be set on any queries or changesets generated for managing or querying this relationship. - -
- - - private? - - - - - boolean - - false - - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. - -
- - - not_found_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. - -
- - - writable? - - - - - boolean - - true - - Whether or not the relationship may be managed. - -
- - - read_action - - - - - atom - - - - The read action on the destination resource to use when loading data and filtering. - -
- - - api - - - - - atom - - - - The API module to use when working with the related entity. - -
- - - filter - - - - - `any` - - - - A filter to be applied when reading the relationship. - -
- - - filterable? - - - - - boolean - - true - - If set to `false`, the relationship will not be usable in filters. -
- - - sort - - - - - `any` - - - - A sort statement to be applied when loading the relationship. - -
- - - could_be_related_at_creation? - - - - - boolean - - false - - Whether or not related values may exist for this relationship at creation. - -
- - - violation_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on destroy. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Relationships.HasOne` - -## relationships.has_many -```elixir -has_many name, destination -``` - - -Declares a `has_many` relationship. There can be any number of related entities. - -See the [relationships guide](/documentation/topics/relationships.md) for more. - - - - -### Examples -``` -# In a resource called `Word` -has_many :definitions, DictionaryDefinition do - source_attribute :text - destination_attribute :word_text -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - atom - - - - The name of the relationship -
- - - destination - - - - - module - - - - The destination resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - manual - - - - - (any, any -> any) | module - - - - A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. - -
- - - no_attributes? - - - - - boolean - - - - All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/relationships.md) for more. - -
- - - description - - - - - String.t - - - - An optional description for the relationship -
- - - destination_attribute - - - - - atom - - - - The attribute on the related resource that should match the `source_attribute` configured on this resource. -
- - - validate_destination_attribute? - - - - - boolean - - true - - Whether or not to validate that the destination field exists on the destination resource -
- - - source_attribute - - - - - atom - - :id - - The field on this resource that should match the `destination_attribute` on the related resource. -
- - - relationship_context - - - - - `any` - - - - Context to be set on any queries or changesets generated for managing or querying this relationship. - -
- - - private? - - - - - boolean - - false - - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. - -
- - - not_found_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. - -
- - - writable? - - - - - boolean - - true - - Whether or not the relationship may be managed. - -
- - - read_action - - - - - atom - - - - The read action on the destination resource to use when loading data and filtering. - -
- - - api - - - - - atom - - - - The API module to use when working with the related entity. - -
- - - filter - - - - - `any` - - - - A filter to be applied when reading the relationship. - -
- - - filterable? - - - - - boolean - - true - - If set to `false`, the relationship will not be usable in filters. -
- - - sort - - - - - `any` - - - - A sort statement to be applied when loading the relationship. - -
- - - could_be_related_at_creation? - - - - - boolean - - false - - Whether or not related values may exist for this relationship at creation. - -
- - - violation_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on destroy. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Relationships.HasMany` - -## relationships.many_to_many -```elixir -many_to_many name, destination -``` - - -Declares a `many_to_many` relationship. Many to many relationships require a join resource. - -A join resource is a resource that consists of a relationship to the source and destination of the many to many. - -See the [relationships guide](/documentation/topics/relationships.md) for more. - - - - -### Examples -``` -# In a resource called `Word` -many_to_many :books, Book do - through BookWord - source_attribute :text - source_attribute_on_join_resource :word_text - destination_attribute :id - destination_attribute_on_join_resource :book_id -end - -# And in `BookWord` (the join resource) -belongs_to :book, Book, primary_key?: true, allow_nil?: false -belongs_to :word, Word, primary_key?: true, allow_nil?: false - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - atom - - - - The name of the relationship -
- - - destination - - - - - module - - - - The destination resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - through - - - * - - - module - - - - The resource to use as the join resource. -
- - - source_attribute_on_join_resource - - - - - atom - - - - The attribute on the join resource that should line up with `source_attribute` on this resource. Defaults to `_id`. -
- - - destination_attribute_on_join_resource - - - - - atom - - - - The attribute on the join resource that should line up with `destination_attribute` on the related resource. Defaults to `_id`. -
- - - join_relationship - - - - - atom - - - - The has_many relationship to the join resource. Defaults to `_join_assoc`. -
- - - description - - - - - String.t - - - - An optional description for the relationship -
- - - destination_attribute - - - - - atom - - :id - - The attribute on the related resource that should match the `source_attribute` configured on this resource. -
- - - validate_destination_attribute? - - - - - boolean - - true - - Whether or not to validate that the destination field exists on the destination resource -
- - - source_attribute - - - - - atom - - :id - - The field on this resource that should match the `destination_attribute` on the related resource. -
- - - relationship_context - - - - - `any` - - - - Context to be set on any queries or changesets generated for managing or querying this relationship. - -
- - - private? - - - - - boolean - - false - - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. - -
- - - not_found_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. - -
- - - writable? - - - - - boolean - - true - - Whether or not the relationship may be managed. - -
- - - read_action - - - - - atom - - - - The read action on the destination resource to use when loading data and filtering. - -
- - - api - - - - - atom - - - - The API module to use when working with the related entity. - -
- - - filter - - - - - `any` - - - - A filter to be applied when reading the relationship. - -
- - - filterable? - - - - - boolean - - true - - If set to `false`, the relationship will not be usable in filters. -
- - - sort - - - - - `any` - - - - A sort statement to be applied when loading the relationship. - -
- - - could_be_related_at_creation? - - - - - boolean - - false - - Whether or not related values may exist for this relationship at creation. - -
- - - violation_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on destroy. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Relationships.ManyToMany` - -## relationships.belongs_to -```elixir -belongs_to name, destination -``` - - -Declares a `belongs_to` relationship. In a relational database, the foreign key would be on the *source* table. - -This creates a field on the resource with the corresponding name and type, unless `define_attribute?: false` is provided. - -See the [relationships guide](/documentation/topics/relationships.md) for more. - - - - -### Examples -``` -# In a resource called `Word` -belongs_to :dictionary_entry, DictionaryEntry do - source_attribute :text, - destination_attribute :word_text -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - - - atom - - - - The name of the relationship -
- - - destination - - - - - module - - - - The destination resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - primary_key? - - - - - boolean - - false - - Whether the generated attribute is, or is part of, the primary key of a resource. -
- - - allow_nil? - - - - - boolean - - true - - Whether this relationship must always be present, e.g: must be included on creation, and never removed (it may be modified). The generated attribute will not allow nil values. -
- - - attribute_writable? - - - - - boolean - - false - - Whether the generated attribute will be marked as public & writable. - -
- - - define_attribute? - - - - - boolean - - true - - If set to `false` an attribute is not created on the resource for this relationship, and one must be manually added in `attributes`, invalidating many other options. -
- - - attribute_type - - - - - `any` - - :uuid - - The type of the generated created attribute. See `Ash.Type` for more. -
- - - description - - - - - String.t - - - - An optional description for the relationship -
- - - destination_attribute - - - - - atom - - :id - - The attribute on the related resource that should match the `source_attribute` configured on this resource. -
- - - validate_destination_attribute? - - - - - boolean - - true - - Whether or not to validate that the destination field exists on the destination resource -
- - - source_attribute - - - - - atom - - - - The field on this resource that should match the `destination_attribute` on the related resource. - Defaults to _id -
- - - relationship_context - - - - - `any` - - - - Context to be set on any queries or changesets generated for managing or querying this relationship. - -
- - - private? - - - - - boolean - - false - - Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. - -
- - - not_found_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. - -
- - - writable? - - - - - boolean - - true - - Whether or not the relationship may be managed. - -
- - - read_action - - - - - atom - - - - The read action on the destination resource to use when loading data and filtering. - -
- - - api - - - - - atom - - - - The API module to use when working with the related entity. - -
- - - filter - - - - - `any` - - - - A filter to be applied when reading the relationship. - -
- - - filterable? - - - - - boolean - - true - - If set to `false`, the relationship will not be usable in filters. -
- - - sort - - - - - `any` - - - - A sort statement to be applied when loading the relationship. - -
- - - violation_message - - - - - String.t - - - - A message to show if there is a conflict with this relationship in the database on destroy. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Relationships.BelongsTo` - - - - -## actions -A section for declaring resource actions. - -All manipulation of data through the underlying data layer happens through actions. -There are four types of action: `create`, `read`, `update`, and `destroy`. You may -recognize these from the acronym `CRUD`. You can have multiple actions of the same -type, as long as they have different names. This is the primary mechanism for customizing -your resources to conform to your business logic. It is normal and expected to have -multiple actions of each type in a large application. - - -### Nested DSLs - * [action](#actions-action) - * argument - * [create](#actions-create) - * change - * validate - * argument - * metadata - * [read](#actions-read) - * argument - * prepare - * pagination - * metadata - * [update](#actions-update) - * change - * validate - * metadata - * argument - * [destroy](#actions-destroy) - * change - * validate - * metadata - * argument - - -### Examples -``` -actions do - create :signup do - argument :password, :string - argument :password_confirmation, :string - validate confirm(:password, :password_confirmation) - change {MyApp.HashPassword, []} # A custom implemented Change - end - - read :me do - # An action that auto filters to only return the user for the current user - filter [id: actor(:id)] - end - - update :update do - accept [:first_name, :last_name] - end - - destroy do - change set_attribute(:deleted_at, &DateTime.utc_now/0) - # This tells it that even though this is a delete action, it - # should be treated like an update because `deleted_at` is set. - # This should be coupled with a `base_filter` on the resource - # or with the read actions having a `filter` for `is_nil: :deleted_at` - soft? true - end -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - defaults - - - - - list(:create | :read | :update | :destroy) - - - - Creates a simple action of each specified type, with the same name as the type. These will be `primary?` unless one already exists for that type. Embedded resources, however, have a default of all resource types. - -
- - - default_accept - - - - - list(atom) - - - - A default value for the `accept` option for each action. Defaults to all public attributes. -
- - - -## actions.action -```elixir -action name, returns -``` - - -Declares a generic action. A combination of arguments, a return type and a run function. - -For calling this action, see the `Ash.Api` documentation. - - -### Nested DSLs - * [argument](#actions-action-argument) - - -### Examples -``` -action :top_user_emails, {:array, :string} do - argument :limit, :integer, default: 10, allow_nil?: false - run fn input, context -> - with {:ok, top_users} <- top_users(input.limit) do - {:ok, Enum.map(top_users, &(&1.email))} - end - end -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the action -
- - - returns - - - - - module - - - - The return type of the action. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - - - Constraints for the return type. See the [constriants topic](/documentation/topics/constraints.md) for more. - -
- - - allow_nil? - - - - - boolean - - false - - Whether or not the action can return nil. Unlike attributes & arguments, this defaults to `false`. - -
- - - run - - - - - (any, any -> any) | module - - - - -
- - - primary? - - - - - boolean - - false - - Whether or not this action should be used when no action is specified by the caller. -
- - - description - - - - - String.t - - - - An optional description for the action -
- - - transaction? - - - - - boolean - - - - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources that the action may touch, used when building transactions. - -
- - -## actions.action.argument -```elixir -argument name, type -``` - - -Declares an argument on the action - - - - -### Examples -``` -argument :password_confirmation, :string -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - An optional description for the argument. -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). - -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. - -
- - - private? - - - - - boolean - - false - - Whether or not the argument should be suppliable by the client. - -
- - - sensitive? - - - - - boolean - - false - - Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - `any` - - - - The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Argument` - - - - -### Introspection - -Target: `Ash.Resource.Actions.Action` - -## actions.create -```elixir -create name -``` - - -Declares a `create` action. For calling this action, see the `Ash.Api` documentation. - - -### Nested DSLs - * [change](#actions-create-change) - * [validate](#actions-create-validate) - * [argument](#actions-create-argument) - * [metadata](#actions-create-metadata) - - -### Examples -``` -create :register do - primary? true -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the action -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - allow_nil_input - - - - - list(atom) - - - - A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the record is created. - -
- - - manual - - - - - (any, any -> any) | module - - - - Override the creation behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - - upsert? - - - - - boolean - - false - - Forces all uses of this action to be treated as an upsert. - -
- - - upsert_identity - - - - - atom - - - - The identity to use for the upsert. Cannot be overriden by the caller. Ignored if `upsert?` is not set to `true`. - -
- - - upsert_fields - - - - - :replace_all | {:replace, atom | list(atom)} | {:replace_all_except, atom | list(atom)} | atom | list(atom) - - - - The fields to overwrite in the case of an upsert. If not provided, all fields except for fields set by defaults will be overwritten. - -
- - - primary? - - - - - boolean - - false - - Whether or not this action should be used when no action is specified by the caller. -
- - - description - - - - - String.t - - - - An optional description for the action -
- - - transaction? - - - - - boolean - - - - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources that the action may touch, used when building transactions. - -
- - - accept - - - - - :all | list(atom) - - - - The list of attributes to accept. Defaults to all attributes on the resource -
- - - delay_global_validations? - - - - - boolean - - false - - If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. - -
- - - skip_global_validations? - - - - - boolean - - false - - If true, global validations will be skipped. Useful for manual actions. - -
- - - reject - - - - - :all | list(atom) - - - - A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. - -
- - - require_attributes - - - - - list(atom) - - - - A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? - -
- - - error_handler - - - - - mfa - - - - Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more -
- - - manual? - - - - - boolean - - - - Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - -## actions.create.change -```elixir -change change -``` - - -A change to be applied to the changeset. - -See `Ash.Resource.Change` for more. - - - - -### Examples -``` -change relate_actor(:reporter) -``` - -``` -change {MyCustomChange, :foo} -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - change - - - * - - - (any, any -> any) | module - - - - The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - only_when_valid? - - - - - boolean - - false - - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. - -
- - - description - - - - - String.t - - - - An optional description for the change -
- - - where - - - - - list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. - -
- - - always_atomic? - - - - - boolean - - false - - By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Change` - -## actions.create.validate -```elixir -validate validation -``` - - -Declares a validation to be applied to the changeset. - -See `Ash.Resource.Validation` for more. - - - - -### Examples -``` -validate changing(:email) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - validation - - - * - - - (any -> any) | module - - - - The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - where - - - - - (any -> any) | module | list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. - -
- - - only_when_valid? - - - - - boolean - - false - - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. -
- - - message - - - - - String.t - - - - If provided, overrides any message set by the validation error -
- - - description - - - - - String.t - - - - An optional description for the validation -
- - - before_action? - - - - - boolean - - false - - If set to `true`, the validation will be run in a before_action hook -
- - - always_atomic? - - - - - boolean - - false - - By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Validation` - -## actions.create.argument -```elixir -argument name, type -``` - - -Declares an argument on the action - - - - -### Examples -``` -argument :password_confirmation, :string -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - An optional description for the argument. -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). - -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. - -
- - - private? - - - - - boolean - - false - - Whether or not the argument should be suppliable by the client. - -
- - - sensitive? - - - - - boolean - - false - - Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - `any` - - - - The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Argument` - -## actions.create.metadata -```elixir -metadata name, type -``` - - -A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom -change via `Ash.Resource.Info.put_metadata/3`. - - - - -### Examples -``` -metadata :api_token, :string, allow_nil?: false - -``` - -``` -metadata :operation_id, :string, allow_nil?: false - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the metadata -
- - - type - - - * - - - `any` - - - - The type of the metadata. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - [] - - Type constraints on the metadata -
- - - description - - - - - String.t - - - - An optional description for the metadata. -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the metadata may return `nil` -
- - - default - - - - - `any` - - - - The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Metadata` - - - - -### Introspection - -Target: `Ash.Resource.Actions.Create` - -## actions.read -```elixir -read name -``` - - -Declares a `read` action. For calling this action, see the `Ash.Api` documentation. - - -### Nested DSLs - * [argument](#actions-read-argument) - * [prepare](#actions-read-prepare) - * [pagination](#actions-read-pagination) - * [metadata](#actions-read-metadata) - - -### Examples -``` -read :read_all do - primary? true -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the action -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - filter - - - - - `any` - - - - A filter template that will be applied whenever the action is used. See `Ash.Filter` for more on templates -
- - - manual - - - - - (any, any, any -> any) | module - - - - Delegates running of the query to the provided module. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - - get? - - - - - boolean - - false - - Expresses that this action innately only returns a single result. Used by extensions to validate and/or modify behavior. Causes code interfaces to return a single value instead of a list. See the [code interface guide](/documentation/topics/code-interface.md) for more. - -
- - - modify_query - - - - - mfa | (any, any -> any) - - - - Allows direct manipulation of the data layer query via an MFA. The ash query and the data layer query will be provided as additional arguments. The result must be `{:ok, new_data_layer_query} | {:error, error}`. - -
- - - get_by - - - - - atom | list(atom) - - - - A helper to automatically generate a "get by X" action. Sets `get?` to true, add args for each of the specified fields, and adds a filter for each of the arguments. - -
- - - primary? - - - - - boolean - - false - - Whether or not this action should be used when no action is specified by the caller. -
- - - description - - - - - String.t - - - - An optional description for the action -
- - - transaction? - - - - - boolean - - - - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources that the action may touch, used when building transactions. - -
- - -## actions.read.argument -```elixir -argument name, type -``` - - -Declares an argument on the action - - - - -### Examples -``` -argument :password_confirmation, :string -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - An optional description for the argument. -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). - -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. - -
- - - private? - - - - - boolean - - false - - Whether or not the argument should be suppliable by the client. - -
- - - sensitive? - - - - - boolean - - false - - Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - `any` - - - - The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Argument` - -## actions.read.prepare -```elixir -prepare preparation -``` - - -Declares a preparation, which can be used to prepare a query for a read action. - - - - -### Examples -``` -prepare build(sort: [:foo, :bar]) - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - preparation - - - * - - - (any, any -> any) | module - - - - The module and options for a preparation. Also accepts functions take the query and the context. - -
- - - - - - -### Introspection - -Target: `Ash.Resource.Preparation` - -## actions.read.pagination - - -Adds pagination options to a resource - - - - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - keyset? - - - - - boolean - - false - - Whether or not keyset based pagination is supported -
- - - offset? - - - - - boolean - - false - - Whether or not offset based pagination is supported -
- - - default_limit - - - - - pos_integer - - - - The default page size to apply, if one is not supplied -
- - - countable - - - - - true | false | :by_default - - false - - Whether not a returned page will have a full count of all records. Use `:by_default` to do it automatically. -
- - - max_page_size - - - - - pos_integer - - 250 - - The maximum amount of records that can be requested in a single page -
- - - required? - - - - - boolean - - true - - Whether or not pagination can be disabled. Only relevant if some pagination configuration is supplied. -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Read.Pagination` - -## actions.read.metadata -```elixir -metadata name, type -``` - - -A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom -change via `Ash.Resource.Info.put_metadata/3`. - - - - -### Examples -``` -metadata :api_token, :string, allow_nil?: false - -``` - -``` -metadata :operation_id, :string, allow_nil?: false - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the metadata -
- - - type - - - * - - - `any` - - - - The type of the metadata. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - [] - - Type constraints on the metadata -
- - - description - - - - - String.t - - - - An optional description for the metadata. -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the metadata may return `nil` -
- - - default - - - - - `any` - - - - The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Metadata` - - - - -### Introspection - -Target: `Ash.Resource.Actions.Read` - -## actions.update -```elixir -update name -``` - - -Declares a `update` action. For calling this action, see the `Ash.Api` documentation. - - -### Nested DSLs - * [change](#actions-update-change) - * [validate](#actions-update-validate) - * [metadata](#actions-update-metadata) - * [argument](#actions-update-argument) - - -### Examples -``` -update :flag_for_review, primary?: true -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the action -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - manual - - - - - (any, any -> any) | module - - - - Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - - primary? - - - - - boolean - - false - - Whether or not this action should be used when no action is specified by the caller. -
- - - description - - - - - String.t - - - - An optional description for the action -
- - - transaction? - - - - - boolean - - - - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources that the action may touch, used when building transactions. - -
- - - accept - - - - - :all | list(atom) - - - - The list of attributes to accept. Defaults to all attributes on the resource -
- - - delay_global_validations? - - - - - boolean - - false - - If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. - -
- - - skip_global_validations? - - - - - boolean - - false - - If true, global validations will be skipped. Useful for manual actions. - -
- - - reject - - - - - :all | list(atom) - - - - A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. - -
- - - require_attributes - - - - - list(atom) - - - - A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? - -
- - - error_handler - - - - - mfa - - - - Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more -
- - - manual? - - - - - boolean - - - - Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - -## actions.update.change -```elixir -change change -``` - - -A change to be applied to the changeset. - -See `Ash.Resource.Change` for more. - - - - -### Examples -``` -change relate_actor(:reporter) -``` - -``` -change {MyCustomChange, :foo} -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - change - - - * - - - (any, any -> any) | module - - - - The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - only_when_valid? - - - - - boolean - - false - - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. - -
- - - description - - - - - String.t - - - - An optional description for the change -
- - - where - - - - - list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. - -
- - - always_atomic? - - - - - boolean - - false - - By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Change` - -## actions.update.validate -```elixir -validate validation -``` - - -Declares a validation to be applied to the changeset. - -See `Ash.Resource.Validation` for more. - - - - -### Examples -``` -validate changing(:email) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - validation - - - * - - - (any -> any) | module - - - - The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - where - - - - - (any -> any) | module | list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. - -
- - - only_when_valid? - - - - - boolean - - false - - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. -
- - - message - - - - - String.t - - - - If provided, overrides any message set by the validation error -
- - - description - - - - - String.t - - - - An optional description for the validation -
- - - before_action? - - - - - boolean - - false - - If set to `true`, the validation will be run in a before_action hook -
- - - always_atomic? - - - - - boolean - - false - - By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Validation` - -## actions.update.metadata -```elixir -metadata name, type -``` - - -A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom -change via `Ash.Resource.Info.put_metadata/3`. - - - - -### Examples -``` -metadata :api_token, :string, allow_nil?: false - -``` - -``` -metadata :operation_id, :string, allow_nil?: false - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the metadata -
- - - type - - - * - - - `any` - - - - The type of the metadata. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - [] - - Type constraints on the metadata -
- - - description - - - - - String.t - - - - An optional description for the metadata. -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the metadata may return `nil` -
- - - default - - - - - `any` - - - - The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Metadata` - -## actions.update.argument -```elixir -argument name, type -``` - - -Declares an argument on the action - - - - -### Examples -``` -argument :password_confirmation, :string -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - An optional description for the argument. -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). - -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. - -
- - - private? - - - - - boolean - - false - - Whether or not the argument should be suppliable by the client. - -
- - - sensitive? - - - - - boolean - - false - - Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - `any` - - - - The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Argument` - - - - -### Introspection - -Target: `Ash.Resource.Actions.Update` - -## actions.destroy -```elixir -destroy name -``` - - -Declares a `destroy` action. For calling this action, see the `Ash.Api` documentation. - - -### Nested DSLs - * [change](#actions-destroy-change) - * [validate](#actions-destroy-validate) - * [metadata](#actions-destroy-metadata) - * [argument](#actions-destroy-argument) - - -### Examples -``` -destroy :soft_delete do - primary? true -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the action -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - soft? - - - - - atom - - false - - If specified, the destroy action behaves as an update internally -
- - - manual - - - - - (any, any -> any) | module - - - - Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - - primary? - - - - - boolean - - false - - Whether or not this action should be used when no action is specified by the caller. -
- - - description - - - - - String.t - - - - An optional description for the action -
- - - transaction? - - - - - boolean - - - - Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. - -
- - - touches_resources - - - - - list(atom) - - - - A list of resources that the action may touch, used when building transactions. - -
- - - accept - - - - - :all | list(atom) - - - - The list of attributes to accept. Defaults to all attributes on the resource -
- - - delay_global_validations? - - - - - boolean - - false - - If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. - -
- - - skip_global_validations? - - - - - boolean - - false - - If true, global validations will be skipped. Useful for manual actions. - -
- - - reject - - - - - :all | list(atom) - - - - A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. - -
- - - require_attributes - - - - - list(atom) - - - - A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? - -
- - - error_handler - - - - - mfa - - - - Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more -
- - - manual? - - - - - boolean - - - - Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. - -
- - -## actions.destroy.change -```elixir -change change -``` - - -A change to be applied to the changeset. - -See `Ash.Resource.Change` for more. - - - - -### Examples -``` -change relate_actor(:reporter) -``` - -``` -change {MyCustomChange, :foo} -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - change - - - * - - - (any, any -> any) | module - - - - The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - only_when_valid? - - - - - boolean - - false - - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. - -
- - - description - - - - - String.t - - - - An optional description for the change -
- - - where - - - - - list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. - -
- - - always_atomic? - - - - - boolean - - false - - By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Change` - -## actions.destroy.validate -```elixir -validate validation -``` - - -Declares a validation to be applied to the changeset. - -See `Ash.Resource.Validation` for more. - - - - -### Examples -``` -validate changing(:email) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - validation - - - * - - - (any -> any) | module - - - - The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - where - - - - - (any -> any) | module | list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. - -
- - - only_when_valid? - - - - - boolean - - false - - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. -
- - - message - - - - - String.t - - - - If provided, overrides any message set by the validation error -
- - - description - - - - - String.t - - - - An optional description for the validation -
- - - before_action? - - - - - boolean - - false - - If set to `true`, the validation will be run in a before_action hook -
- - - always_atomic? - - - - - boolean - - false - - By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Validation` - -## actions.destroy.metadata -```elixir -metadata name, type -``` - - -A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom -change via `Ash.Resource.Info.put_metadata/3`. - - - - -### Examples -``` -metadata :api_token, :string, allow_nil?: false - -``` - -``` -metadata :operation_id, :string, allow_nil?: false - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the metadata -
- - - type - - - * - - - `any` - - - - The type of the metadata. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - [] - - Type constraints on the metadata -
- - - description - - - - - String.t - - - - An optional description for the metadata. -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the metadata may return `nil` -
- - - default - - - - - `any` - - - - The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Metadata` - -## actions.destroy.argument -```elixir -argument name, type -``` - - -Declares an argument on the action - - - - -### Examples -``` -argument :password_confirmation, :string -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - An optional description for the argument. -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). - -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. - -
- - - private? - - - - - boolean - - false - - Whether or not the argument should be suppliable by the client. - -
- - - sensitive? - - - - - boolean - - false - - Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. - -
- - - default - - - - - `any` - - - - The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value -
- - - - - -### Introspection - -Target: `Ash.Resource.Actions.Argument` - - - - -### Introspection - -Target: `Ash.Resource.Actions.Destroy` - - - - -## code_interface -Functions that will be defined on the Api module to interact with this resource. See the [code interface guide](/documentation/topics/code-interface.md) for more. - - -### Nested DSLs - * [define](#code_interface-define) - * [define_calculation](#code_interface-define_calculation) - - -### Examples -``` -code_interface do - define_for MyApp.Api - define :create_user, action: :create - define :get_user_by_id, action: :get_by_id, args: [:id], get?: true -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - define_for - - - - - module - - false - - Defines the code interface on the resource module directly, using the provided Api. -
- - - -## code_interface.define -```elixir -define name -``` - - -Defines a function with the corresponding name and arguments. See the [code interface guide](/documentation/topics/code-interface.md) for more. - - - - -### Examples -``` -define :get_user_by_id, action: :get_by_id, args: [:id], get?: true -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the function that will be defined -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - action - - - - - atom - - - - The name of the action that will be called. Defaults to the same name as the function. -
- - - args - - - - - list(atom | {:optional, atom}) - - - - Map specific arguments to named inputs. Can provide any argument/attributes that the action allows. - -
- - - not_found_error? - - - - - boolean - - true - - If the action or interface is configured with `get?: true`, this determines whether or not an error is raised or `nil` is returned. -
- - - get? - - - - - boolean - - - - Expects to only receive a single result from a read action, and returns a single result instead of a list. Ignored for other action types. - -
- - - get_by - - - - - atom | list(atom) - - - - Takes a list of fields and adds those fields as arguments, which will then be used to filter. Sets `get?` to true automatically. Ignored for non-read actions. - -
- - - get_by_identity - - - - - atom - - - - Only relevant for read actions. Takes an identity, and gets its field list, performing the same logic as `get_by` once it has the list of fields. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Interface` - -## code_interface.define_calculation -```elixir -define_calculation name -``` - - -Defines a function with the corresponding name and arguments, that evaluates a calculation. Use `:_record` to take an instance of a record. See the [code interface guide](/documentation/topics/code-interface.md) for more. - - - - -### Examples -``` -define_calculation :referral_link, args: [:id] -``` - -``` -define_calculation :referral_link, args: [{:arg, :id}, {:ref, :id}] -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the function that will be defined -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - calculation - - - - - atom - - - - The name of the calculation that will be evaluated. Defaults to the same name as the function. -
- - - args - - - - - `any` - - [] - - Supply field or argument values referenced by the calculation, in the form of :name, `{:arg, :name}` and/or `{:ref, :name}`. See the [code interface guide](/documentation/topics/code-interface.md) for more. - -
- - - - - -### Introspection - -Target: `Ash.Resource.CalculationInterface` - - - - -## resource -General resource configuration - - - - -### Examples -``` -resource do - description "A description of this resource" - base_filter [is_nil: :deleted_at] -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - description - - - - - String.t - - - - A human readable description of the resource, to be used in generated documentation -
- - - base_filter - - - - - `any` - - - - A filter statement to be applied to any queries on the resource -
- - - default_context - - - - - `any` - - - - Default context to apply to any queries/changesets generated for this resource. -
- - - trace_name - - - - - String.t - - - - The name to use in traces. Defaults to the short_name stringified. See the [monitoring guide](/documentation/topics/monitoring.md) for more. - -
- - - short_name - - - - - atom - - - - A short identifier for the resource, which should be unique. See the [monitoring guide](/documentation/topics/monitoring.md) for more. - -
- - - plural_name - - - - - atom - - - - A pluralized version of the resource short_name. May be used by generators or automated tooling. - -
- - - simple_notifiers - - - - - list(module) - - - - A list of notifiers that require no DSL. Can be used to avoid compile time dependencies on notifiers -
- - - require_primary_key? - - - - - boolean - - true - - Allow the resource to be used without any primary key fields. Warning: this option is experimental, and should not be used unless you know what you're doing. - -
- - - - - - -## identities -Unique identifiers for the resource - - -### Nested DSLs - * [identity](#identities-identity) - - -### Examples -``` -identities do - identity :full_name, [:first_name, :last_name] - identity :email, [:email] -end - -``` - - - - -## identities.identity -```elixir -identity name, keys -``` - - -Represents a unique constraint on the resource. - -See the [identities guide](/documentation/topics/identities.md) for more. - - - - -### Examples -``` -identity :name, [:name] -``` - -``` -identity :full_name, [:first_name, :last_name] -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the identity. -
- - - keys - - - * - - - atom | list(atom) - - - - The names of the attributes that uniquely identify this resource. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - eager_check_with - - - - - module - - - - Validates that the unique identity provided is unique at validation time, outside of any transactions, using the api module provided. - -
- - - pre_check_with - - - - - module - - - - Validates that the unique identity provided is unique in a before_action hook. - -
- - - description - - - - - String.t - - - - An optional description for the identity -
- - - message - - - - - String.t - - - - An error message to use when the unique identity would be violated -
- - - - - -### Introspection - -Target: `Ash.Resource.Identity` - - - - -## changes -Declare changes that occur on create/update/destroy actions against the resource - -See `Ash.Resource.Change` for more. - - -### Nested DSLs - * [change](#changes-change) - - -### Examples -``` -changes do - change {Mod, [foo: :bar]} - change set_context(%{some: :context}) -end - -``` - - - - -## changes.change -```elixir -change change -``` - - -A change to be applied to the changeset. - -See `Ash.Resource.Change` for more. - - - - -### Examples -``` -change relate_actor(:reporter) -``` - -``` -change {MyCustomChange, :foo} -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - change - - - * - - - (any, any -> any) | module - - - - The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - on - - - - - :create | :update | :destroy | list(:create | :update | :destroy) - - [:create, :update] - - The action types the validation should run on. Destroy actions are omitted by default as most changes don't make sense for a destroy. - -
- - - only_when_valid? - - - - - boolean - - false - - If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. - -
- - - description - - - - - String.t - - - - An optional description for the change -
- - - where - - - - - list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. - -
- - - always_atomic? - - - - - boolean - - false - - By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Change` - - - - -## preparations -Declare preparations that occur on all read actions for a given resource - - -### Nested DSLs - * [prepare](#preparations-prepare) - - -### Examples -``` -preparations do - prepare {Mod, [foo: :bar]} - prepare set_context(%{some: :context}) -end - -``` - - - - -## preparations.prepare -```elixir -prepare preparation -``` - - -Declares a preparation, which can be used to prepare a query for a read action. - - - - -### Examples -``` -prepare build(sort: [:foo, :bar]) - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - preparation - - - * - - - (any, any -> any) | module - - - - The module and options for a preparation. Also accepts functions take the query and the context. - -
- - - - - - -### Introspection - -Target: `Ash.Resource.Preparation` - - - - -## validations -Declare validations prior to performing actions against the resource - - -### Nested DSLs - * [validate](#validations-validate) - - -### Examples -``` -validations do - validate {Mod, [foo: :bar]} - validate at_least_one_of_present([:first_name, :last_name]) -end - -``` - - - - -## validations.validate -```elixir -validate validation -``` - - -Declares a validation for creates and updates. - -See `Ash.Resource.Change` for more. - - - - -### Examples -``` -validate {Mod, [foo: :bar]} -``` - -``` -validate at_least_one_of_present([:first_name, :last_name]) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - validation - - - * - - - (any -> any) | module - - - - The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - where - - - - - (any -> any) | module | list((any -> any) | module) - - [] - - Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. - -
- - - on - - - - - :create | :update | :destroy | list(:create | :update | :destroy) - - [:create, :update] - - The action types the validation should run on. Many validations don't make sense in the context of deletion, so by default it is not included. - -
- - - only_when_valid? - - - - - boolean - - false - - If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. -
- - - message - - - - - String.t - - - - If provided, overrides any message set by the validation error -
- - - description - - - - - String.t - - - - An optional description for the validation -
- - - before_action? - - - - - boolean - - false - - If set to `true`, the validation will be run in a before_action hook -
- - - always_atomic? - - - - - boolean - - false - - By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. -
- - - - - -### Introspection - -Target: `Ash.Resource.Validation` - - - - -## aggregates -Declare named aggregates on the resource. - -These are aggregates that can be loaded only by name using `Ash.Query.load/2`. -They are also available as top level fields on the resource. - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - -### Nested DSLs - * [count](#aggregates-count) - * [exists](#aggregates-exists) - * [first](#aggregates-first) - * [sum](#aggregates-sum) - * [list](#aggregates-list) - * [max](#aggregates-max) - * [min](#aggregates-min) - * [avg](#aggregates-avg) - * [custom](#aggregates-custom) - - -### Examples -``` -aggregates do - count :assigned_ticket_count, :reported_tickets do - filter [active: true] - end -end - -``` - - - - -## aggregates.count -```elixir -count name, relationship_path -``` - - -Declares a named count aggregate on the resource - -Supports `filter`, but not `sort` (because that wouldn't affect the count) - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -count :assigned_ticket_count, :assigned_tickets do - filter [active: true] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - uniq? - - - - - boolean - - false - - Whether or not to count unique values only -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.exists -```elixir -exists name, relationship_path -``` - - -Declares a named `exists` aggregate on the resource - -Supports `filter`, but not `sort` (because that wouldn't affect if something exists) - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -exists :has_ticket, :assigned_tickets - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.first -```elixir -first name, relationship_path, field -``` - - -Declares a named `first` aggregate on the resource - -First aggregates return the first value of the related record -that matches. Supports both `filter` and `sort`. - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -first :first_assigned_ticket_subject, :assigned_tickets, :subject do - filter [active: true] - sort [:subject] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - sort - - - - - `any` - - - - A sort to be applied to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.sum -```elixir -sum name, relationship_path, field -``` - - -Declares a named `sum` aggregate on the resource - -Supports `filter`, but not `sort` (because that wouldn't affect the sum) - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -sum :assigned_ticket_price_sum, :assigned_tickets, :price do - filter [active: true] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.list -```elixir -list name, relationship_path, field -``` - - -Declares a named `list` aggregate on the resource. - -A list aggregate selects the list of all values for the given field -and relationship combination. - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -list :assigned_ticket_prices, :assigned_tickets, :price do - filter [active: true] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - uniq? - - - - - boolean - - false - - Whether or not to count unique values only -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - sort - - - - - `any` - - - - A sort to be applied to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.max -```elixir -max name, relationship_path, field -``` - - -Declares a named `max` aggregate on the resource - -Supports `filter`, but not `sort` (because that wouldn't affect the max) - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -max :first_assigned_ticket_subject, :assigned_tickets, :severity do - filter [active: true] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.min -```elixir -min name, relationship_path, field -``` - - -Declares a named `min` aggregate on the resource - -Supports `filter`, but not `sort` (because that wouldn't affect the min) - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -min :first_assigned_ticket_subject, :assigned_tickets, :severity do - filter [active: true] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.avg -```elixir -avg name, relationship_path, field -``` - - -Declares a named `avg` aggregate on the resource - -Supports `filter`, but not `sort` (because that wouldn't affect the avg) - -See the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -avg :assigned_ticket_price_sum, :assigned_tickets, :price do - filter [active: true] -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - -## aggregates.custom -```elixir -custom name, relationship_path, type -``` - - -Declares a named `custom` aggregate on the resource - -Supports `filter` and `sort`. - -Custom aggregates provide an `implementation` which must implement data layer specific callbacks. - -See the relevant data layer documentation and the [aggregates guide](/documentation/topics/aggregates.md) for more. - - - - -### Examples -``` -custom :author_names, :authors, :string do - implementation {StringAgg, delimiter: ","} -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field to place the aggregate in -
- - - relationship_path - - - * - - - atom | list(atom) - - - - The relationship or relationship path to use for the aggregate -
- - - type - - - * - - - module - - - - The type of the value returned by the aggregate -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - implementation - - - * - - - module - - - - The module that implements the relevant data layer callbacks -
- - - kind - - - * - - - :count | :first | :sum | :list | :avg | :max | :min | :exists | :custom | {:custom, module} - - - - The kind of the aggregate -
- - - read_action - - - - - atom - - - - The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. - -
- - - field - - - - - atom - - - - The field to aggregate. Defaults to the first field in the primary key of the resource -
- - - filter - - - - - `any` - - [] - - A filter to apply to the aggregate -
- - - sort - - - - - `any` - - - - A sort to be applied to the aggregate -
- - - description - - - - - String.t - - - - An optional description for the aggregate -
- - - default - - - - - `any` - - - - A default value to use in cases where nil would be used. Count defaults to `0`. -
- - - private? - - - - - boolean - - false - - Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the aggregate should be usable in filters. -
- - - authorize? - - - - - boolean - - true - - Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. - -
- - - - - -### Introspection - -Target: `Ash.Resource.Aggregate` - - - - -## calculations -Declare named calculations on the resource. - -These are calculations that can be loaded only by name using `Ash.Query.load/2`. -They are also available as top level fields on the resource. - -See the [calculations guide](/documentation/topics/calculations.md) for more. - - -### Nested DSLs - * [calculate](#calculations-calculate) - * argument - - -### Examples -``` -calculations do - calculate :full_name, :string, MyApp.MyResource.FullName -end - -``` - - - - -## calculations.calculate -```elixir -calculate name, type, calculation \ nil -``` - - -Declares a named calculation on the resource. - -Takes a module that must adopt the `Ash.Calculation` behaviour. See that module -for more information. - -To ensure that the necessary fields are selected: - -1.) Specifying the `select` option on a calculation in the resource. -2.) Define a `select/2` callback in the calculation module -3.) Set `always_select?` on the attribute in question - -See the [calculations guide](/documentation/topics/calculations.md) for more. - - -### Nested DSLs - * [argument](#calculations-calculate-argument) - - -### Examples -`Ash.Calculation` implementation example: -``` -calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}, select: [:first_name, :last_name] -``` - -`expr/1` example: -``` -calculate :full_name, :string, expr(first_name <> " " <> last_name) -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The field name to use for the calculation value -
- - - type - - - * - - - `any` - - - - The type of the calculation. See `Ash.Type` for more. -
- - - calculation - - - * - - - (any, any -> any) | module | `any` - - - - The `module`, `{module, opts}` or `expr(...)` to use for the calculation. Also accepts a function that takes *a single record* and produces the result. - -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type. See `Ash.Type` for more. -
- - - description - - - - - String.t - - - - An optional description for the calculation -
- - - private? - - - - - boolean - - false - - Whether or not the calculation will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. - -
- - - select - - - - - list(atom) - - [] - - A list of fields to ensure selected if the calculation is used. -
- - - load - - - - - `any` - - [] - - A load statement to be applied if the calculation is used. -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the calculation can return nil. -
- - - filterable? - - - - - boolean | :simple_equality - - true - - Whether or not the calculation should be usable in filters. -
- - -## calculations.calculate.argument -```elixir -argument name, type -``` - - -An argument to be passed into the calculation's arguments map - -See the [calculations guide](/documentation/topics/calculations.md) for more. - - - - -### Examples -``` -argument :params, :map do - default %{} -end - -``` - -``` -argument :retries, :integer do - allow_nil? false -end - -``` - - - -### Arguments - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - name - - - * - - - atom - - - - The name of the argument -
- - - type - - - * - - - module - - - - The type of the argument. See `Ash.Type` for more. -
-### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - default - - - - - (-> any) | mfa | any() - - - - A default value to use for the argument if not provided -
- - - allow_nil? - - - - - boolean - - true - - Whether or not the argument value may be nil (or may be not provided) -
- - - allow_expr? - - - - - boolean - - false - - Allow passing expressions as argument values. Expressions cannot be type validated. -
- - - constraints - - - - - Keyword.t - - [] - - Constraints to provide to the type when casting the value. See the type's documentation and `Ash.Type` for more. -
- - - - - -### Introspection - -Target: `Ash.Resource.Calculation.Argument` - - - - -### Introspection - -Target: `Ash.Resource.Calculation` - - - - -## multitenancy -Options for configuring the multitenancy behavior of a resource. - -To specify a tenant, use `Ash.Query.set_tenant/2` or -`Ash.Changeset.set_tenant/2` before passing it to an operation. - -See the [multitenancy guide](/documentation/topics/multitenancy.md) - - - - -### Examples -``` -multitenancy do - strategy :attribute - attribute :organization_id - global? true -end - -``` - - - - -### Options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDocs
- - - strategy - - - - - :context | :attribute - - :context - - Determine if multitenancy is performed with attribute filters or using data layer features. - -
- - - attribute - - - - - atom - - - - If using the `attribute` strategy, the attribute to use, e.g `org_id` - -
- - - global? - - - - - boolean - - false - - Whether or not the data also exists outside of each tenant. - -
- - - parse_attribute - - - - - mfa - - {Ash.Resource.Dsl, :identity, []} - - An mfa ({module, function, args}) pointing to a function that takes a tenant and returns the attribute value -
- - - - - - diff --git a/documentation/dsls/DSL:-Ash.Resource.md b/documentation/dsls/DSL:-Ash.Resource.md new file mode 100644 index 000000000..db225b539 --- /dev/null +++ b/documentation/dsls/DSL:-Ash.Resource.md @@ -0,0 +1,2913 @@ + +# DSL: Ash.Resource.Dsl + + + +## attributes +A section for declaring attributes on the resource. + + +### Nested DSLs + * [attribute](#attributes-attribute) + * [create_timestamp](#attributes-create_timestamp) + * [update_timestamp](#attributes-update_timestamp) + * [integer_primary_key](#attributes-integer_primary_key) + * [uuid_primary_key](#attributes-uuid_primary_key) + + +### Examples +``` +attributes do + uuid_primary_key :id + + attribute :first_name, :string do + allow_nil? false + end + + attribute :last_name, :string do + allow_nil? false + end + + attribute :email, :string do + allow_nil? false + + constraints [ + match: ~r/^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/ + ] + end + + attribute :type, :atom do + constraints [ + one_of: [:admin, :teacher, :student] + ] + end + + create_timestamp :inserted_at + update_timestamp :updated_at +end + +``` + + + + +## attributes.attribute +```elixir +attribute name, type +``` + + +Declares an attribute on the resource. + + + + +### Examples +``` +attribute :name, :string do + allow_nil? false +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#attributes-attribute-name){: #attributes-attribute-name .spark-required} | `atom` | | The name of the attribute. | +| [`type`](#attributes-attribute-type){: #attributes-attribute-type .spark-required} | `module` | | The type of the attribute. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#attributes-attribute-constraints){: #attributes-attribute-constraints } | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). | +| [`description`](#attributes-attribute-description){: #attributes-attribute-description } | `String.t` | | An optional description for the attribute. | +| [`sensitive?`](#attributes-attribute-sensitive?){: #attributes-attribute-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. | +| [`source`](#attributes-attribute-source){: #attributes-attribute-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. | +| [`always_select?`](#attributes-attribute-always_select?){: #attributes-attribute-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. | +| [`primary_key?`](#attributes-attribute-primary_key?){: #attributes-attribute-primary_key? } | `boolean` | `false` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. | +| [`allow_nil?`](#attributes-attribute-allow_nil?){: #attributes-attribute-allow_nil? } | `boolean` | `true` | Whether or not the attribute can be set to nil. If nil value is given error is raised. | +| [`generated?`](#attributes-attribute-generated?){: #attributes-attribute-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. | +| [`writable?`](#attributes-attribute-writable?){: #attributes-attribute-writable? } | `boolean` | `true` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. | +| [`private?`](#attributes-attribute-private?){: #attributes-attribute-private? } | `boolean` | `false` | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#attributes-attribute-default){: #attributes-attribute-default } | `(-> any) \| mfa \| any()` | | A value to be set on all creates, unless a value is being provided already. | +| [`update_default`](#attributes-attribute-update_default){: #attributes-attribute-update_default } | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. | +| [`filterable?`](#attributes-attribute-filterable?){: #attributes-attribute-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the attribute can be referenced in filters. | +| [`match_other_defaults?`](#attributes-attribute-match_other_defaults?){: #attributes-attribute-match_other_defaults? } | `boolean` | `false` | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. | + + + + + +### Introspection + +Target: `Ash.Resource.Attribute` + +## attributes.create_timestamp +```elixir +create_timestamp name +``` + + +Declares a non-writable attribute with a create default of `&DateTime.utc_now/0` + +Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except it sets +the following different defaults: + +writable? false +private? true +default &DateTime.utc_now/0 +match_other_defaults? true +type Ash.Type.UTCDatetimeUsec +allow_nil? false + + + + +### Examples +``` +create_timestamp :inserted_at +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#attributes-create_timestamp-name){: #attributes-create_timestamp-name .spark-required} | `atom` | | The name of the attribute. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`type`](#attributes-create_timestamp-type){: #attributes-create_timestamp-type } | `module` | `Ash.Type.UtcDatetimeUsec` | The type of the attribute. See `Ash.Type` for more. | +| [`constraints`](#attributes-create_timestamp-constraints){: #attributes-create_timestamp-constraints } | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). | +| [`description`](#attributes-create_timestamp-description){: #attributes-create_timestamp-description } | `String.t` | | An optional description for the attribute. | +| [`sensitive?`](#attributes-create_timestamp-sensitive?){: #attributes-create_timestamp-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. | +| [`source`](#attributes-create_timestamp-source){: #attributes-create_timestamp-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. | +| [`always_select?`](#attributes-create_timestamp-always_select?){: #attributes-create_timestamp-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. | +| [`primary_key?`](#attributes-create_timestamp-primary_key?){: #attributes-create_timestamp-primary_key? } | `boolean` | `false` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. | +| [`allow_nil?`](#attributes-create_timestamp-allow_nil?){: #attributes-create_timestamp-allow_nil? } | `boolean` | `false` | Whether or not the attribute can be set to nil. If nil value is given error is raised. | +| [`generated?`](#attributes-create_timestamp-generated?){: #attributes-create_timestamp-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. | +| [`writable?`](#attributes-create_timestamp-writable?){: #attributes-create_timestamp-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. | +| [`private?`](#attributes-create_timestamp-private?){: #attributes-create_timestamp-private? } | `boolean` | `true` | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#attributes-create_timestamp-default){: #attributes-create_timestamp-default } | `(-> any) \| mfa \| any()` | `&DateTime.utc_now/0` | A value to be set on all creates, unless a value is being provided already. | +| [`update_default`](#attributes-create_timestamp-update_default){: #attributes-create_timestamp-update_default } | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. | +| [`filterable?`](#attributes-create_timestamp-filterable?){: #attributes-create_timestamp-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the attribute can be referenced in filters. | +| [`match_other_defaults?`](#attributes-create_timestamp-match_other_defaults?){: #attributes-create_timestamp-match_other_defaults? } | `boolean` | `true` | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. | + + + + + +### Introspection + +Target: `Ash.Resource.Attribute` + +## attributes.update_timestamp +```elixir +update_timestamp name +``` + + +Declares a non-writable attribute with a create and update default of `&DateTime.utc_now/0` + +Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except it sets +the following different defaults: + +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 :updated_at +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#attributes-update_timestamp-name){: #attributes-update_timestamp-name .spark-required} | `atom` | | The name of the attribute. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`type`](#attributes-update_timestamp-type){: #attributes-update_timestamp-type } | `module` | `Ash.Type.UtcDatetimeUsec` | The type of the attribute. See `Ash.Type` for more. | +| [`constraints`](#attributes-update_timestamp-constraints){: #attributes-update_timestamp-constraints } | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). | +| [`description`](#attributes-update_timestamp-description){: #attributes-update_timestamp-description } | `String.t` | | An optional description for the attribute. | +| [`sensitive?`](#attributes-update_timestamp-sensitive?){: #attributes-update_timestamp-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. | +| [`source`](#attributes-update_timestamp-source){: #attributes-update_timestamp-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. | +| [`always_select?`](#attributes-update_timestamp-always_select?){: #attributes-update_timestamp-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. | +| [`primary_key?`](#attributes-update_timestamp-primary_key?){: #attributes-update_timestamp-primary_key? } | `boolean` | `false` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. | +| [`allow_nil?`](#attributes-update_timestamp-allow_nil?){: #attributes-update_timestamp-allow_nil? } | `boolean` | `false` | Whether or not the attribute can be set to nil. If nil value is given error is raised. | +| [`generated?`](#attributes-update_timestamp-generated?){: #attributes-update_timestamp-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. | +| [`writable?`](#attributes-update_timestamp-writable?){: #attributes-update_timestamp-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. | +| [`private?`](#attributes-update_timestamp-private?){: #attributes-update_timestamp-private? } | `boolean` | `true` | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#attributes-update_timestamp-default){: #attributes-update_timestamp-default } | `(-> any) \| mfa \| any()` | `&DateTime.utc_now/0` | A value to be set on all creates, unless a value is being provided already. | +| [`update_default`](#attributes-update_timestamp-update_default){: #attributes-update_timestamp-update_default } | `(-> any) \| mfa \| any()` | `&DateTime.utc_now/0` | A value to be set on all updates, unless a value is being provided already. | +| [`filterable?`](#attributes-update_timestamp-filterable?){: #attributes-update_timestamp-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the attribute can be referenced in filters. | +| [`match_other_defaults?`](#attributes-update_timestamp-match_other_defaults?){: #attributes-update_timestamp-match_other_defaults? } | `boolean` | `true` | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. | + + + + + +### Introspection + +Target: `Ash.Resource.Attribute` + +## attributes.integer_primary_key +```elixir +integer_primary_key name +``` + + +Declares a generated, non writable, non-nil, primary key column of type integer. + +Generated integer primary keys must be supported by the data layer. + +Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except for `allow_nil?`, but it sets +the following different defaults: + +writable? false +primary_key? true +generated? true +type :integer + + + + +### Examples +``` +integer_primary_key :id +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#attributes-integer_primary_key-name){: #attributes-integer_primary_key-name .spark-required} | `atom` | | The name of the attribute. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`type`](#attributes-integer_primary_key-type){: #attributes-integer_primary_key-type } | `module` | `:integer` | The type of the attribute. See `Ash.Type` for more. | +| [`constraints`](#attributes-integer_primary_key-constraints){: #attributes-integer_primary_key-constraints } | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). | +| [`description`](#attributes-integer_primary_key-description){: #attributes-integer_primary_key-description } | `String.t` | | An optional description for the attribute. | +| [`sensitive?`](#attributes-integer_primary_key-sensitive?){: #attributes-integer_primary_key-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. | +| [`source`](#attributes-integer_primary_key-source){: #attributes-integer_primary_key-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. | +| [`always_select?`](#attributes-integer_primary_key-always_select?){: #attributes-integer_primary_key-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. | +| [`primary_key?`](#attributes-integer_primary_key-primary_key?){: #attributes-integer_primary_key-primary_key? } | `boolean` | `true` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. | +| [`generated?`](#attributes-integer_primary_key-generated?){: #attributes-integer_primary_key-generated? } | `boolean` | `true` | Whether or not the value may be generated by the data layer. | +| [`writable?`](#attributes-integer_primary_key-writable?){: #attributes-integer_primary_key-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. | +| [`private?`](#attributes-integer_primary_key-private?){: #attributes-integer_primary_key-private? } | `boolean` | `false` | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#attributes-integer_primary_key-default){: #attributes-integer_primary_key-default } | `(-> any) \| mfa \| any()` | | A value to be set on all creates, unless a value is being provided already. | +| [`update_default`](#attributes-integer_primary_key-update_default){: #attributes-integer_primary_key-update_default } | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. | +| [`filterable?`](#attributes-integer_primary_key-filterable?){: #attributes-integer_primary_key-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the attribute can be referenced in filters. | +| [`match_other_defaults?`](#attributes-integer_primary_key-match_other_defaults?){: #attributes-integer_primary_key-match_other_defaults? } | `boolean` | `false` | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. | + + + + + +### Introspection + +Target: `Ash.Resource.Attribute` + +## attributes.uuid_primary_key +```elixir +uuid_primary_key name +``` + + +Declares a non writable, non-nil, primary key column of type `uuid`, which defaults to `Ash.UUID.generate/0`. + +Accepts all the same options as `d:Ash.Resource.Dsl.attributes.attribute`, except for `allow_nil?`, but it sets +the following different defaults: + +writable? false +default &Ash.UUID.generate/0 +primary_key? true +generated? true +type :uuid + + + + +### Examples +``` +uuid_primary_key :id +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#attributes-uuid_primary_key-name){: #attributes-uuid_primary_key-name .spark-required} | `atom` | | The name of the attribute. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`type`](#attributes-uuid_primary_key-type){: #attributes-uuid_primary_key-type } | `module` | `:uuid` | The type of the attribute. See `Ash.Type` for more. | +| [`constraints`](#attributes-uuid_primary_key-constraints){: #attributes-uuid_primary_key-constraints } | `Keyword.t` | | Constraints to provide to the type when casting the value. For more, see the [constraints topic](/documentation/topics/constraints.md). | +| [`description`](#attributes-uuid_primary_key-description){: #attributes-uuid_primary_key-description } | `String.t` | | An optional description for the attribute. | +| [`sensitive?`](#attributes-uuid_primary_key-sensitive?){: #attributes-uuid_primary_key-sensitive? } | `boolean` | `false` | Whether or not the attribute value contains sensitive information, like PII. See the [Security guide](/documentation/topics/security.md) for more. | +| [`source`](#attributes-uuid_primary_key-source){: #attributes-uuid_primary_key-source } | `atom` | | If the field should be mapped to a different name in the data layer. Support varies by data layer. | +| [`always_select?`](#attributes-uuid_primary_key-always_select?){: #attributes-uuid_primary_key-always_select? } | `boolean` | `false` | Whether or not to ensure this attribute is always selected when reading from the database, regardless of applied select statements. | +| [`primary_key?`](#attributes-uuid_primary_key-primary_key?){: #attributes-uuid_primary_key-primary_key? } | `boolean` | `true` | Whether the attribute is the primary key. Composite primary key is also possible by using `primary_key? true` in more than one attribute. If primary_key? is true, allow_nil? must be false. | +| [`generated?`](#attributes-uuid_primary_key-generated?){: #attributes-uuid_primary_key-generated? } | `boolean` | `false` | Whether or not the value may be generated by the data layer. | +| [`writable?`](#attributes-uuid_primary_key-writable?){: #attributes-uuid_primary_key-writable? } | `boolean` | `false` | Whether or not the value can be written to. Non-writable attributes can still be written with `Ash.Changeset.force_change_attribute/3`. | +| [`private?`](#attributes-uuid_primary_key-private?){: #attributes-uuid_primary_key-private? } | `boolean` | `false` | The attribute is not publically writable, and should not be exposed over any public interfaces. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#attributes-uuid_primary_key-default){: #attributes-uuid_primary_key-default } | `(-> any) \| mfa \| any()` | `&Ash.UUID.generate/0` | A value to be set on all creates, unless a value is being provided already. | +| [`update_default`](#attributes-uuid_primary_key-update_default){: #attributes-uuid_primary_key-update_default } | `(-> any) \| mfa \| any()` | | A value to be set on all updates, unless a value is being provided already. | +| [`filterable?`](#attributes-uuid_primary_key-filterable?){: #attributes-uuid_primary_key-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the attribute can be referenced in filters. | +| [`match_other_defaults?`](#attributes-uuid_primary_key-match_other_defaults?){: #attributes-uuid_primary_key-match_other_defaults? } | `boolean` | `false` | Ensures that other attributes that use the same "lazy" default (a function or an mfa), use the same default value. Has no effect unless `default` is a zero argument function. | + + + + + +### Introspection + +Target: `Ash.Resource.Attribute` + + + + +## relationships +A section for declaring relationships on the resource. + +Relationships are a core component of resource oriented design. Many components of Ash +will use these relationships. A simple use case is loading relationships (done via the `Ash.Query.load/2`). + +See the [relationships guide](/documentation/topics/relationships.md) for more. + + +### Nested DSLs + * [has_one](#relationships-has_one) + * [has_many](#relationships-has_many) + * [many_to_many](#relationships-many_to_many) + * [belongs_to](#relationships-belongs_to) + + +### Examples +``` +relationships do + belongs_to :post, MyApp.Post do + primary_key? true + end + + belongs_to :category, MyApp.Category do + primary_key? true + end +end + +``` + +``` +relationships do + belongs_to :author, MyApp.Author + + many_to_many :categories, MyApp.Category do + through MyApp.PostCategory + destination_attribute_on_join_resource :category_id + source_attribute_on_join_resource :post_id + end +end + +``` + +``` +relationships do + has_many :posts, MyApp.Post do + destination_attribute :author_id + end + + has_many :composite_key_posts, MyApp.CompositeKeyPost do + destination_attribute :author_id + end +end + +``` + + + + +## relationships.has_one +```elixir +has_one name, destination +``` + + +Declares a `has_one` relationship. In a relational database, the foreign key would be on the *other* table. + +Generally speaking, a `has_one` also implies that the destination table is unique on that foreign key. + +See the [relationships guide](/documentation/topics/relationships.md) for more. + + + + +### Examples +``` +# In a resource called `Word` +has_one :dictionary_entry, DictionaryEntry do + source_attribute :text + destination_attribute :word_text +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#relationships-has_one-name){: #relationships-has_one-name } | `atom` | | The name of the relationship | +| [`destination`](#relationships-has_one-destination){: #relationships-has_one-destination } | `module` | | The destination resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`manual`](#relationships-has_one-manual){: #relationships-has_one-manual } | `(any, any -> any) \| module` | | A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. | +| [`no_attributes?`](#relationships-has_one-no_attributes?){: #relationships-has_one-no_attributes? } | `boolean` | | All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/relationships.md) for more. | +| [`allow_nil?`](#relationships-has_one-allow_nil?){: #relationships-has_one-allow_nil? } | `boolean` | `true` | Marks the relationship as required. Has no effect on validations, but can inform extensions that there will always be a related entity. | +| [`from_many?`](#relationships-has_one-from_many?){: #relationships-has_one-from_many? } | `boolean` | `false` | Signal that this relationship is actually a `has_many` where the first record is given via the `sort`. This will allow data layers to properly deduplicate when necessary. | +| [`description`](#relationships-has_one-description){: #relationships-has_one-description } | `String.t` | | An optional description for the relationship | +| [`destination_attribute`](#relationships-has_one-destination_attribute){: #relationships-has_one-destination_attribute } | `atom` | | The attribute on the related resource that should match the `source_attribute` configured on this resource. | +| [`validate_destination_attribute?`](#relationships-has_one-validate_destination_attribute?){: #relationships-has_one-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource | +| [`source_attribute`](#relationships-has_one-source_attribute){: #relationships-has_one-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. | +| [`relationship_context`](#relationships-has_one-relationship_context){: #relationships-has_one-relationship_context } | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. | +| [`private?`](#relationships-has_one-private?){: #relationships-has_one-private? } | `boolean` | `false` | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. | +| [`not_found_message`](#relationships-has_one-not_found_message){: #relationships-has_one-not_found_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. | +| [`writable?`](#relationships-has_one-writable?){: #relationships-has_one-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. | +| [`read_action`](#relationships-has_one-read_action){: #relationships-has_one-read_action } | `atom` | | The read action on the destination resource to use when loading data and filtering. | +| [`api`](#relationships-has_one-api){: #relationships-has_one-api } | `atom` | | The API module to use when working with the related entity. | +| [`filter`](#relationships-has_one-filter){: #relationships-has_one-filter } | ``any`` | | A filter to be applied when reading the relationship. | +| [`filterable?`](#relationships-has_one-filterable?){: #relationships-has_one-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. | +| [`sort`](#relationships-has_one-sort){: #relationships-has_one-sort } | ``any`` | | A sort statement to be applied when loading the relationship. | +| [`could_be_related_at_creation?`](#relationships-has_one-could_be_related_at_creation?){: #relationships-has_one-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. | +| [`violation_message`](#relationships-has_one-violation_message){: #relationships-has_one-violation_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. | + + + + + +### Introspection + +Target: `Ash.Resource.Relationships.HasOne` + +## relationships.has_many +```elixir +has_many name, destination +``` + + +Declares a `has_many` relationship. There can be any number of related entities. + +See the [relationships guide](/documentation/topics/relationships.md) for more. + + + + +### Examples +``` +# In a resource called `Word` +has_many :definitions, DictionaryDefinition do + source_attribute :text + destination_attribute :word_text +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#relationships-has_many-name){: #relationships-has_many-name } | `atom` | | The name of the relationship | +| [`destination`](#relationships-has_many-destination){: #relationships-has_many-destination } | `module` | | The destination resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`manual`](#relationships-has_many-manual){: #relationships-has_many-manual } | `(any, any -> any) \| module` | | A module that implements `Ash.Resource.ManualRelationship`. Also accepts a 2 argument function that takes the source records and the context. | +| [`no_attributes?`](#relationships-has_many-no_attributes?){: #relationships-has_many-no_attributes? } | `boolean` | | All existing entities are considered related, i.e this relationship is not based on any fields, and `source_attribute` and `destination_attribute` are ignored. See the See the [relationships guide](/documentation/topics/relationships.md) for more. | +| [`description`](#relationships-has_many-description){: #relationships-has_many-description } | `String.t` | | An optional description for the relationship | +| [`destination_attribute`](#relationships-has_many-destination_attribute){: #relationships-has_many-destination_attribute } | `atom` | | The attribute on the related resource that should match the `source_attribute` configured on this resource. | +| [`validate_destination_attribute?`](#relationships-has_many-validate_destination_attribute?){: #relationships-has_many-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource | +| [`source_attribute`](#relationships-has_many-source_attribute){: #relationships-has_many-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. | +| [`relationship_context`](#relationships-has_many-relationship_context){: #relationships-has_many-relationship_context } | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. | +| [`private?`](#relationships-has_many-private?){: #relationships-has_many-private? } | `boolean` | `false` | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. | +| [`not_found_message`](#relationships-has_many-not_found_message){: #relationships-has_many-not_found_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. | +| [`writable?`](#relationships-has_many-writable?){: #relationships-has_many-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. | +| [`read_action`](#relationships-has_many-read_action){: #relationships-has_many-read_action } | `atom` | | The read action on the destination resource to use when loading data and filtering. | +| [`api`](#relationships-has_many-api){: #relationships-has_many-api } | `atom` | | The API module to use when working with the related entity. | +| [`filter`](#relationships-has_many-filter){: #relationships-has_many-filter } | ``any`` | | A filter to be applied when reading the relationship. | +| [`filterable?`](#relationships-has_many-filterable?){: #relationships-has_many-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. | +| [`sort`](#relationships-has_many-sort){: #relationships-has_many-sort } | ``any`` | | A sort statement to be applied when loading the relationship. | +| [`could_be_related_at_creation?`](#relationships-has_many-could_be_related_at_creation?){: #relationships-has_many-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. | +| [`violation_message`](#relationships-has_many-violation_message){: #relationships-has_many-violation_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. | + + + + + +### Introspection + +Target: `Ash.Resource.Relationships.HasMany` + +## relationships.many_to_many +```elixir +many_to_many name, destination +``` + + +Declares a `many_to_many` relationship. Many to many relationships require a join resource. + +A join resource is a resource that consists of a relationship to the source and destination of the many to many. + +See the [relationships guide](/documentation/topics/relationships.md) for more. + + + + +### Examples +``` +# In a resource called `Word` +many_to_many :books, Book do + through BookWord + source_attribute :text + source_attribute_on_join_resource :word_text + destination_attribute :id + destination_attribute_on_join_resource :book_id +end + +# And in `BookWord` (the join resource) +belongs_to :book, Book, primary_key?: true, allow_nil?: false +belongs_to :word, Word, primary_key?: true, allow_nil?: false + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#relationships-many_to_many-name){: #relationships-many_to_many-name } | `atom` | | The name of the relationship | +| [`destination`](#relationships-many_to_many-destination){: #relationships-many_to_many-destination } | `module` | | The destination resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`through`](#relationships-many_to_many-through){: #relationships-many_to_many-through .spark-required} | `module` | | The resource to use as the join resource. | +| [`source_attribute_on_join_resource`](#relationships-many_to_many-source_attribute_on_join_resource){: #relationships-many_to_many-source_attribute_on_join_resource } | `atom` | | The attribute on the join resource that should line up with `source_attribute` on this resource. Defaults to `_id`. | +| [`destination_attribute_on_join_resource`](#relationships-many_to_many-destination_attribute_on_join_resource){: #relationships-many_to_many-destination_attribute_on_join_resource } | `atom` | | The attribute on the join resource that should line up with `destination_attribute` on the related resource. Defaults to `_id`. | +| [`join_relationship`](#relationships-many_to_many-join_relationship){: #relationships-many_to_many-join_relationship } | `atom` | | The has_many relationship to the join resource. Defaults to `_join_assoc`. | +| [`description`](#relationships-many_to_many-description){: #relationships-many_to_many-description } | `String.t` | | An optional description for the relationship | +| [`destination_attribute`](#relationships-many_to_many-destination_attribute){: #relationships-many_to_many-destination_attribute } | `atom` | `:id` | The attribute on the related resource that should match the `source_attribute` configured on this resource. | +| [`validate_destination_attribute?`](#relationships-many_to_many-validate_destination_attribute?){: #relationships-many_to_many-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource | +| [`source_attribute`](#relationships-many_to_many-source_attribute){: #relationships-many_to_many-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. | +| [`relationship_context`](#relationships-many_to_many-relationship_context){: #relationships-many_to_many-relationship_context } | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. | +| [`private?`](#relationships-many_to_many-private?){: #relationships-many_to_many-private? } | `boolean` | `false` | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. | +| [`not_found_message`](#relationships-many_to_many-not_found_message){: #relationships-many_to_many-not_found_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. | +| [`writable?`](#relationships-many_to_many-writable?){: #relationships-many_to_many-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. | +| [`read_action`](#relationships-many_to_many-read_action){: #relationships-many_to_many-read_action } | `atom` | | The read action on the destination resource to use when loading data and filtering. | +| [`api`](#relationships-many_to_many-api){: #relationships-many_to_many-api } | `atom` | | The API module to use when working with the related entity. | +| [`filter`](#relationships-many_to_many-filter){: #relationships-many_to_many-filter } | ``any`` | | A filter to be applied when reading the relationship. | +| [`filterable?`](#relationships-many_to_many-filterable?){: #relationships-many_to_many-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. | +| [`sort`](#relationships-many_to_many-sort){: #relationships-many_to_many-sort } | ``any`` | | A sort statement to be applied when loading the relationship. | +| [`could_be_related_at_creation?`](#relationships-many_to_many-could_be_related_at_creation?){: #relationships-many_to_many-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. | +| [`violation_message`](#relationships-many_to_many-violation_message){: #relationships-many_to_many-violation_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. | + + + + + +### Introspection + +Target: `Ash.Resource.Relationships.ManyToMany` + +## relationships.belongs_to +```elixir +belongs_to name, destination +``` + + +Declares a `belongs_to` relationship. In a relational database, the foreign key would be on the *source* table. + +This creates a field on the resource with the corresponding name and type, unless `define_attribute?: false` is provided. + +See the [relationships guide](/documentation/topics/relationships.md) for more. + + + + +### Examples +``` +# In a resource called `Word` +belongs_to :dictionary_entry, DictionaryEntry do + source_attribute :text, + destination_attribute :word_text +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#relationships-belongs_to-name){: #relationships-belongs_to-name } | `atom` | | The name of the relationship | +| [`destination`](#relationships-belongs_to-destination){: #relationships-belongs_to-destination } | `module` | | The destination resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`primary_key?`](#relationships-belongs_to-primary_key?){: #relationships-belongs_to-primary_key? } | `boolean` | `false` | Whether the generated attribute is, or is part of, the primary key of a resource. | +| [`allow_nil?`](#relationships-belongs_to-allow_nil?){: #relationships-belongs_to-allow_nil? } | `boolean` | `true` | Whether this relationship must always be present, e.g: must be included on creation, and never removed (it may be modified). The generated attribute will not allow nil values. | +| [`attribute_writable?`](#relationships-belongs_to-attribute_writable?){: #relationships-belongs_to-attribute_writable? } | `boolean` | `false` | Whether the generated attribute will be marked as public & writable. | +| [`define_attribute?`](#relationships-belongs_to-define_attribute?){: #relationships-belongs_to-define_attribute? } | `boolean` | `true` | If set to `false` an attribute is not created on the resource for this relationship, and one must be manually added in `attributes`, invalidating many other options. | +| [`attribute_type`](#relationships-belongs_to-attribute_type){: #relationships-belongs_to-attribute_type } | ``any`` | `:uuid` | The type of the generated created attribute. See `Ash.Type` for more. | +| [`description`](#relationships-belongs_to-description){: #relationships-belongs_to-description } | `String.t` | | An optional description for the relationship | +| [`destination_attribute`](#relationships-belongs_to-destination_attribute){: #relationships-belongs_to-destination_attribute } | `atom` | `:id` | The attribute on the related resource that should match the `source_attribute` configured on this resource. | +| [`validate_destination_attribute?`](#relationships-belongs_to-validate_destination_attribute?){: #relationships-belongs_to-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource | +| [`source_attribute`](#relationships-belongs_to-source_attribute){: #relationships-belongs_to-source_attribute } | `atom` | | The field on this resource that should match the `destination_attribute` on the related resource. - Defaults to _id | +| [`relationship_context`](#relationships-belongs_to-relationship_context){: #relationships-belongs_to-relationship_context } | ``any`` | | Context to be set on any queries or changesets generated for managing or querying this relationship. | +| [`private?`](#relationships-belongs_to-private?){: #relationships-belongs_to-private? } | `boolean` | `false` | Whether or not the relationship will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. | +| [`not_found_message`](#relationships-belongs_to-not_found_message){: #relationships-belongs_to-not_found_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on update or create, or when managing relationships. | +| [`writable?`](#relationships-belongs_to-writable?){: #relationships-belongs_to-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. | +| [`read_action`](#relationships-belongs_to-read_action){: #relationships-belongs_to-read_action } | `atom` | | The read action on the destination resource to use when loading data and filtering. | +| [`api`](#relationships-belongs_to-api){: #relationships-belongs_to-api } | `atom` | | The API module to use when working with the related entity. | +| [`filter`](#relationships-belongs_to-filter){: #relationships-belongs_to-filter } | ``any`` | | A filter to be applied when reading the relationship. | +| [`filterable?`](#relationships-belongs_to-filterable?){: #relationships-belongs_to-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. | +| [`sort`](#relationships-belongs_to-sort){: #relationships-belongs_to-sort } | ``any`` | | A sort statement to be applied when loading the relationship. | +| [`violation_message`](#relationships-belongs_to-violation_message){: #relationships-belongs_to-violation_message } | `String.t` | | A message to show if there is a conflict with this relationship in the database on destroy. | + + + + + +### Introspection + +Target: `Ash.Resource.Relationships.BelongsTo` + + + + +## actions +A section for declaring resource actions. + +All manipulation of data through the underlying data layer happens through actions. +There are four types of action: `create`, `read`, `update`, and `destroy`. You may +recognize these from the acronym `CRUD`. You can have multiple actions of the same +type, as long as they have different names. This is the primary mechanism for customizing +your resources to conform to your business logic. It is normal and expected to have +multiple actions of each type in a large application. + + +### Nested DSLs + * [action](#actions-action) + * argument + * [create](#actions-create) + * change + * validate + * argument + * metadata + * [read](#actions-read) + * argument + * prepare + * pagination + * metadata + * [update](#actions-update) + * change + * validate + * metadata + * argument + * [destroy](#actions-destroy) + * change + * validate + * metadata + * argument + + +### Examples +``` +actions do + create :signup do + argument :password, :string + argument :password_confirmation, :string + validate confirm(:password, :password_confirmation) + change {MyApp.HashPassword, []} # A custom implemented Change + end + + read :me do + # An action that auto filters to only return the user for the current user + filter [id: actor(:id)] + end + + update :update do + accept [:first_name, :last_name] + end + + destroy do + change set_attribute(:deleted_at, &DateTime.utc_now/0) + # This tells it that even though this is a delete action, it + # should be treated like an update because `deleted_at` is set. + # This should be coupled with a `base_filter` on the resource + # or with the read actions having a `filter` for `is_nil: :deleted_at` + soft? true + end +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`defaults`](#actions-defaults){: #actions-defaults } | `list(:create \| :read \| :update \| :destroy)` | | Creates a simple action of each specified type, with the same name as the type. These will be `primary?` unless one already exists for that type. Embedded resources, however, have a default of all resource types. | +| [`default_accept`](#actions-default_accept){: #actions-default_accept } | `list(atom)` | | A default value for the `accept` option for each action. Defaults to all public attributes. | + + + +## actions.action +```elixir +action name, returns +``` + + +Declares a generic action. A combination of arguments, a return type and a run function. + +For calling this action, see the `Ash.Api` documentation. + + +### Nested DSLs + * [argument](#actions-action-argument) + + +### Examples +``` +action :top_user_emails, {:array, :string} do + argument :limit, :integer, default: 10, allow_nil?: false + run fn input, context -> + with {:ok, top_users} <- top_users(input.limit) do + {:ok, Enum.map(top_users, &(&1.email))} + end + end +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-action-name){: #actions-action-name .spark-required} | `atom` | | The name of the action | +| [`returns`](#actions-action-returns){: #actions-action-returns } | `module` | | The return type of the action. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#actions-action-constraints){: #actions-action-constraints } | `Keyword.t` | | Constraints for the return type. See the [constriants topic](/documentation/topics/constraints.md) for more. | +| [`allow_nil?`](#actions-action-allow_nil?){: #actions-action-allow_nil? } | `boolean` | `false` | Whether or not the action can return nil. Unlike attributes & arguments, this defaults to `false`. | +| [`run`](#actions-action-run){: #actions-action-run } | `(any, any -> any) \| module` | | | +| [`primary?`](#actions-action-primary?){: #actions-action-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. | +| [`description`](#actions-action-description){: #actions-action-description } | `String.t` | | An optional description for the action | +| [`transaction?`](#actions-action-transaction?){: #actions-action-transaction? } | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. | +| [`touches_resources`](#actions-action-touches_resources){: #actions-action-touches_resources } | `list(atom)` | | A list of resources that the action may touch, used when building transactions. | + + +## actions.action.argument +```elixir +argument name, type +``` + + +Declares an argument on the action + + + + +### Examples +``` +argument :password_confirmation, :string +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-action-argument-name){: #actions-action-argument-name .spark-required} | `atom` | | The name of the argument | +| [`type`](#actions-action-argument-type){: #actions-action-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#actions-action-argument-description){: #actions-action-argument-description } | `String.t` | | An optional description for the argument. | +| [`constraints`](#actions-action-argument-constraints){: #actions-action-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). | +| [`allow_nil?`](#actions-action-argument-allow_nil?){: #actions-action-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. | +| [`private?`](#actions-action-argument-private?){: #actions-action-argument-private? } | `boolean` | `false` | Whether or not the argument should be suppliable by the client. | +| [`sensitive?`](#actions-action-argument-sensitive?){: #actions-action-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#actions-action-argument-default){: #actions-action-argument-default } | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Argument` + + + + +### Introspection + +Target: `Ash.Resource.Actions.Action` + +## actions.create +```elixir +create name +``` + + +Declares a `create` action. For calling this action, see the `Ash.Api` documentation. + + +### Nested DSLs + * [change](#actions-create-change) + * [validate](#actions-create-validate) + * [argument](#actions-create-argument) + * [metadata](#actions-create-metadata) + + +### Examples +``` +create :register do + primary? true +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-create-name){: #actions-create-name .spark-required} | `atom` | | The name of the action | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`allow_nil_input`](#actions-create-allow_nil_input){: #actions-create-allow_nil_input } | `list(atom)` | | A list of attributes that would normally be required, but should not be for this action. They will still be validated just before the record is created. | +| [`manual`](#actions-create-manual){: #actions-create-manual } | `(any, any -> any) \| module` | | Override the creation behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | +| [`upsert?`](#actions-create-upsert?){: #actions-create-upsert? } | `boolean` | `false` | Forces all uses of this action to be treated as an upsert. | +| [`upsert_identity`](#actions-create-upsert_identity){: #actions-create-upsert_identity } | `atom` | | The identity to use for the upsert. Cannot be overriden by the caller. Ignored if `upsert?` is not set to `true`. | +| [`upsert_fields`](#actions-create-upsert_fields){: #actions-create-upsert_fields } | `:replace_all \| {:replace, atom \| list(atom)} \| {:replace_all_except, atom \| list(atom)} \| atom \| list(atom)` | | The fields to overwrite in the case of an upsert. If not provided, all fields except for fields set by defaults will be overwritten. | +| [`primary?`](#actions-create-primary?){: #actions-create-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. | +| [`description`](#actions-create-description){: #actions-create-description } | `String.t` | | An optional description for the action | +| [`transaction?`](#actions-create-transaction?){: #actions-create-transaction? } | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. | +| [`touches_resources`](#actions-create-touches_resources){: #actions-create-touches_resources } | `list(atom)` | | A list of resources that the action may touch, used when building transactions. | +| [`accept`](#actions-create-accept){: #actions-create-accept } | `:all \| list(atom)` | | The list of attributes to accept. Defaults to all attributes on the resource | +| [`delay_global_validations?`](#actions-create-delay_global_validations?){: #actions-create-delay_global_validations? } | `boolean` | `false` | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. | +| [`skip_global_validations?`](#actions-create-skip_global_validations?){: #actions-create-skip_global_validations? } | `boolean` | `false` | If true, global validations will be skipped. Useful for manual actions. | +| [`reject`](#actions-create-reject){: #actions-create-reject } | `:all \| list(atom)` | | A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. | +| [`require_attributes`](#actions-create-require_attributes){: #actions-create-require_attributes } | `list(atom)` | | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? | +| [`error_handler`](#actions-create-error_handler){: #actions-create-error_handler } | `mfa` | | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more | +| [`manual?`](#actions-create-manual?){: #actions-create-manual? } | `boolean` | | Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | + + +## actions.create.change +```elixir +change change +``` + + +A change to be applied to the changeset. + +See `Ash.Resource.Change` for more. + + + + +### Examples +``` +change relate_actor(:reporter) +``` + +``` +change {MyCustomChange, :foo} +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`change`](#actions-create-change-change){: #actions-create-change-change .spark-required} | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`only_when_valid?`](#actions-create-change-only_when_valid?){: #actions-create-change-only_when_valid? } | `boolean` | `false` | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. | +| [`description`](#actions-create-change-description){: #actions-create-change-description } | `String.t` | | An optional description for the change | +| [`where`](#actions-create-change-where){: #actions-create-change-where } | `list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. | +| [`always_atomic?`](#actions-create-change-always_atomic?){: #actions-create-change-always_atomic? } | `boolean` | `false` | By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Change` + +## actions.create.validate +```elixir +validate validation +``` + + +Declares a validation to be applied to the changeset. + +See `Ash.Resource.Validation` for more. + + + + +### Examples +``` +validate changing(:email) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`validation`](#actions-create-validate-validation){: #actions-create-validate-validation .spark-required} | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`where`](#actions-create-validate-where){: #actions-create-validate-where } | `(any -> any) \| module \| list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. | +| [`only_when_valid?`](#actions-create-validate-only_when_valid?){: #actions-create-validate-only_when_valid? } | `boolean` | `false` | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. | +| [`message`](#actions-create-validate-message){: #actions-create-validate-message } | `String.t` | | If provided, overrides any message set by the validation error | +| [`description`](#actions-create-validate-description){: #actions-create-validate-description } | `String.t` | | An optional description for the validation | +| [`before_action?`](#actions-create-validate-before_action?){: #actions-create-validate-before_action? } | `boolean` | `false` | If set to `true`, the validation will be run in a before_action hook | +| [`always_atomic?`](#actions-create-validate-always_atomic?){: #actions-create-validate-always_atomic? } | `boolean` | `false` | By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Validation` + +## actions.create.argument +```elixir +argument name, type +``` + + +Declares an argument on the action + + + + +### Examples +``` +argument :password_confirmation, :string +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-create-argument-name){: #actions-create-argument-name .spark-required} | `atom` | | The name of the argument | +| [`type`](#actions-create-argument-type){: #actions-create-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#actions-create-argument-description){: #actions-create-argument-description } | `String.t` | | An optional description for the argument. | +| [`constraints`](#actions-create-argument-constraints){: #actions-create-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). | +| [`allow_nil?`](#actions-create-argument-allow_nil?){: #actions-create-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. | +| [`private?`](#actions-create-argument-private?){: #actions-create-argument-private? } | `boolean` | `false` | Whether or not the argument should be suppliable by the client. | +| [`sensitive?`](#actions-create-argument-sensitive?){: #actions-create-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#actions-create-argument-default){: #actions-create-argument-default } | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Argument` + +## actions.create.metadata +```elixir +metadata name, type +``` + + +A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom +change via `Ash.Resource.Info.put_metadata/3`. + + + + +### Examples +``` +metadata :api_token, :string, allow_nil?: false + +``` + +``` +metadata :operation_id, :string, allow_nil?: false + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-create-metadata-name){: #actions-create-metadata-name .spark-required} | `atom` | | The name of the metadata | +| [`type`](#actions-create-metadata-type){: #actions-create-metadata-type .spark-required} | ``any`` | | The type of the metadata. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#actions-create-metadata-constraints){: #actions-create-metadata-constraints } | `Keyword.t` | `[]` | Type constraints on the metadata | +| [`description`](#actions-create-metadata-description){: #actions-create-metadata-description } | `String.t` | | An optional description for the metadata. | +| [`allow_nil?`](#actions-create-metadata-allow_nil?){: #actions-create-metadata-allow_nil? } | `boolean` | `true` | Whether or not the metadata may return `nil` | +| [`default`](#actions-create-metadata-default){: #actions-create-metadata-default } | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Metadata` + + + + +### Introspection + +Target: `Ash.Resource.Actions.Create` + +## actions.read +```elixir +read name +``` + + +Declares a `read` action. For calling this action, see the `Ash.Api` documentation. + + +### Nested DSLs + * [argument](#actions-read-argument) + * [prepare](#actions-read-prepare) + * [pagination](#actions-read-pagination) + * [metadata](#actions-read-metadata) + + +### Examples +``` +read :read_all do + primary? true +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-read-name){: #actions-read-name .spark-required} | `atom` | | The name of the action | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`filter`](#actions-read-filter){: #actions-read-filter } | ``any`` | | A filter template that will be applied whenever the action is used. See `Ash.Filter` for more on templates | +| [`manual`](#actions-read-manual){: #actions-read-manual } | `(any, any, any -> any) \| module` | | Delegates running of the query to the provided module. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | +| [`get?`](#actions-read-get?){: #actions-read-get? } | `boolean` | `false` | Expresses that this action innately only returns a single result. Used by extensions to validate and/or modify behavior. Causes code interfaces to return a single value instead of a list. See the [code interface guide](/documentation/topics/code-interface.md) for more. | +| [`modify_query`](#actions-read-modify_query){: #actions-read-modify_query } | `mfa \| (any, any -> any)` | | Allows direct manipulation of the data layer query via an MFA. The ash query and the data layer query will be provided as additional arguments. The result must be `{:ok, new_data_layer_query} \| {:error, error}`. | +| [`get_by`](#actions-read-get_by){: #actions-read-get_by } | `atom \| list(atom)` | | A helper to automatically generate a "get by X" action. Sets `get?` to true, add args for each of the specified fields, and adds a filter for each of the arguments. | +| [`primary?`](#actions-read-primary?){: #actions-read-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. | +| [`description`](#actions-read-description){: #actions-read-description } | `String.t` | | An optional description for the action | +| [`transaction?`](#actions-read-transaction?){: #actions-read-transaction? } | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. | +| [`touches_resources`](#actions-read-touches_resources){: #actions-read-touches_resources } | `list(atom)` | | A list of resources that the action may touch, used when building transactions. | + + +## actions.read.argument +```elixir +argument name, type +``` + + +Declares an argument on the action + + + + +### Examples +``` +argument :password_confirmation, :string +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-read-argument-name){: #actions-read-argument-name .spark-required} | `atom` | | The name of the argument | +| [`type`](#actions-read-argument-type){: #actions-read-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#actions-read-argument-description){: #actions-read-argument-description } | `String.t` | | An optional description for the argument. | +| [`constraints`](#actions-read-argument-constraints){: #actions-read-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). | +| [`allow_nil?`](#actions-read-argument-allow_nil?){: #actions-read-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. | +| [`private?`](#actions-read-argument-private?){: #actions-read-argument-private? } | `boolean` | `false` | Whether or not the argument should be suppliable by the client. | +| [`sensitive?`](#actions-read-argument-sensitive?){: #actions-read-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#actions-read-argument-default){: #actions-read-argument-default } | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Argument` + +## actions.read.prepare +```elixir +prepare preparation +``` + + +Declares a preparation, which can be used to prepare a query for a read action. + + + + +### Examples +``` +prepare build(sort: [:foo, :bar]) + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`preparation`](#actions-read-prepare-preparation){: #actions-read-prepare-preparation .spark-required} | `(any, any -> any) \| module` | | The module and options for a preparation. Also accepts functions take the query and the context. | + + + + + + +### Introspection + +Target: `Ash.Resource.Preparation` + +## actions.read.pagination + + +Adds pagination options to a resource + + + + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`keyset?`](#actions-read-pagination-keyset?){: #actions-read-pagination-keyset? } | `boolean` | `false` | Whether or not keyset based pagination is supported | +| [`offset?`](#actions-read-pagination-offset?){: #actions-read-pagination-offset? } | `boolean` | `false` | Whether or not offset based pagination is supported | +| [`default_limit`](#actions-read-pagination-default_limit){: #actions-read-pagination-default_limit } | `pos_integer` | | The default page size to apply, if one is not supplied | +| [`countable`](#actions-read-pagination-countable){: #actions-read-pagination-countable } | `true \| false \| :by_default` | `false` | Whether not a returned page will have a full count of all records. Use `:by_default` to do it automatically. | +| [`max_page_size`](#actions-read-pagination-max_page_size){: #actions-read-pagination-max_page_size } | `pos_integer` | `250` | The maximum amount of records that can be requested in a single page | +| [`required?`](#actions-read-pagination-required?){: #actions-read-pagination-required? } | `boolean` | `true` | Whether or not pagination can be disabled. Only relevant if some pagination configuration is supplied. | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Read.Pagination` + +## actions.read.metadata +```elixir +metadata name, type +``` + + +A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom +change via `Ash.Resource.Info.put_metadata/3`. + + + + +### Examples +``` +metadata :api_token, :string, allow_nil?: false + +``` + +``` +metadata :operation_id, :string, allow_nil?: false + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-read-metadata-name){: #actions-read-metadata-name .spark-required} | `atom` | | The name of the metadata | +| [`type`](#actions-read-metadata-type){: #actions-read-metadata-type .spark-required} | ``any`` | | The type of the metadata. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#actions-read-metadata-constraints){: #actions-read-metadata-constraints } | `Keyword.t` | `[]` | Type constraints on the metadata | +| [`description`](#actions-read-metadata-description){: #actions-read-metadata-description } | `String.t` | | An optional description for the metadata. | +| [`allow_nil?`](#actions-read-metadata-allow_nil?){: #actions-read-metadata-allow_nil? } | `boolean` | `true` | Whether or not the metadata may return `nil` | +| [`default`](#actions-read-metadata-default){: #actions-read-metadata-default } | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Metadata` + + + + +### Introspection + +Target: `Ash.Resource.Actions.Read` + +## actions.update +```elixir +update name +``` + + +Declares a `update` action. For calling this action, see the `Ash.Api` documentation. + + +### Nested DSLs + * [change](#actions-update-change) + * [validate](#actions-update-validate) + * [metadata](#actions-update-metadata) + * [argument](#actions-update-argument) + + +### Examples +``` +update :flag_for_review, primary?: true +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-update-name){: #actions-update-name .spark-required} | `atom` | | The name of the action | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`manual`](#actions-update-manual){: #actions-update-manual } | `(any, any -> any) \| module` | | Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | +| [`primary?`](#actions-update-primary?){: #actions-update-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. | +| [`description`](#actions-update-description){: #actions-update-description } | `String.t` | | An optional description for the action | +| [`transaction?`](#actions-update-transaction?){: #actions-update-transaction? } | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. | +| [`touches_resources`](#actions-update-touches_resources){: #actions-update-touches_resources } | `list(atom)` | | A list of resources that the action may touch, used when building transactions. | +| [`accept`](#actions-update-accept){: #actions-update-accept } | `:all \| list(atom)` | | The list of attributes to accept. Defaults to all attributes on the resource | +| [`delay_global_validations?`](#actions-update-delay_global_validations?){: #actions-update-delay_global_validations? } | `boolean` | `false` | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. | +| [`skip_global_validations?`](#actions-update-skip_global_validations?){: #actions-update-skip_global_validations? } | `boolean` | `false` | If true, global validations will be skipped. Useful for manual actions. | +| [`reject`](#actions-update-reject){: #actions-update-reject } | `:all \| list(atom)` | | A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. | +| [`require_attributes`](#actions-update-require_attributes){: #actions-update-require_attributes } | `list(atom)` | | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? | +| [`error_handler`](#actions-update-error_handler){: #actions-update-error_handler } | `mfa` | | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more | +| [`manual?`](#actions-update-manual?){: #actions-update-manual? } | `boolean` | | Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | + + +## actions.update.change +```elixir +change change +``` + + +A change to be applied to the changeset. + +See `Ash.Resource.Change` for more. + + + + +### Examples +``` +change relate_actor(:reporter) +``` + +``` +change {MyCustomChange, :foo} +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`change`](#actions-update-change-change){: #actions-update-change-change .spark-required} | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`only_when_valid?`](#actions-update-change-only_when_valid?){: #actions-update-change-only_when_valid? } | `boolean` | `false` | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. | +| [`description`](#actions-update-change-description){: #actions-update-change-description } | `String.t` | | An optional description for the change | +| [`where`](#actions-update-change-where){: #actions-update-change-where } | `list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. | +| [`always_atomic?`](#actions-update-change-always_atomic?){: #actions-update-change-always_atomic? } | `boolean` | `false` | By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Change` + +## actions.update.validate +```elixir +validate validation +``` + + +Declares a validation to be applied to the changeset. + +See `Ash.Resource.Validation` for more. + + + + +### Examples +``` +validate changing(:email) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`validation`](#actions-update-validate-validation){: #actions-update-validate-validation .spark-required} | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`where`](#actions-update-validate-where){: #actions-update-validate-where } | `(any -> any) \| module \| list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. | +| [`only_when_valid?`](#actions-update-validate-only_when_valid?){: #actions-update-validate-only_when_valid? } | `boolean` | `false` | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. | +| [`message`](#actions-update-validate-message){: #actions-update-validate-message } | `String.t` | | If provided, overrides any message set by the validation error | +| [`description`](#actions-update-validate-description){: #actions-update-validate-description } | `String.t` | | An optional description for the validation | +| [`before_action?`](#actions-update-validate-before_action?){: #actions-update-validate-before_action? } | `boolean` | `false` | If set to `true`, the validation will be run in a before_action hook | +| [`always_atomic?`](#actions-update-validate-always_atomic?){: #actions-update-validate-always_atomic? } | `boolean` | `false` | By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Validation` + +## actions.update.metadata +```elixir +metadata name, type +``` + + +A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom +change via `Ash.Resource.Info.put_metadata/3`. + + + + +### Examples +``` +metadata :api_token, :string, allow_nil?: false + +``` + +``` +metadata :operation_id, :string, allow_nil?: false + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-update-metadata-name){: #actions-update-metadata-name .spark-required} | `atom` | | The name of the metadata | +| [`type`](#actions-update-metadata-type){: #actions-update-metadata-type .spark-required} | ``any`` | | The type of the metadata. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#actions-update-metadata-constraints){: #actions-update-metadata-constraints } | `Keyword.t` | `[]` | Type constraints on the metadata | +| [`description`](#actions-update-metadata-description){: #actions-update-metadata-description } | `String.t` | | An optional description for the metadata. | +| [`allow_nil?`](#actions-update-metadata-allow_nil?){: #actions-update-metadata-allow_nil? } | `boolean` | `true` | Whether or not the metadata may return `nil` | +| [`default`](#actions-update-metadata-default){: #actions-update-metadata-default } | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Metadata` + +## actions.update.argument +```elixir +argument name, type +``` + + +Declares an argument on the action + + + + +### Examples +``` +argument :password_confirmation, :string +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-update-argument-name){: #actions-update-argument-name .spark-required} | `atom` | | The name of the argument | +| [`type`](#actions-update-argument-type){: #actions-update-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#actions-update-argument-description){: #actions-update-argument-description } | `String.t` | | An optional description for the argument. | +| [`constraints`](#actions-update-argument-constraints){: #actions-update-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). | +| [`allow_nil?`](#actions-update-argument-allow_nil?){: #actions-update-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. | +| [`private?`](#actions-update-argument-private?){: #actions-update-argument-private? } | `boolean` | `false` | Whether or not the argument should be suppliable by the client. | +| [`sensitive?`](#actions-update-argument-sensitive?){: #actions-update-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#actions-update-argument-default){: #actions-update-argument-default } | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Argument` + + + + +### Introspection + +Target: `Ash.Resource.Actions.Update` + +## actions.destroy +```elixir +destroy name +``` + + +Declares a `destroy` action. For calling this action, see the `Ash.Api` documentation. + + +### Nested DSLs + * [change](#actions-destroy-change) + * [validate](#actions-destroy-validate) + * [metadata](#actions-destroy-metadata) + * [argument](#actions-destroy-argument) + + +### Examples +``` +destroy :soft_delete do + primary? true +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-destroy-name){: #actions-destroy-name .spark-required} | `atom` | | The name of the action | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`soft?`](#actions-destroy-soft?){: #actions-destroy-soft? } | `atom` | `false` | If specified, the destroy action behaves as an update internally | +| [`manual`](#actions-destroy-manual){: #actions-destroy-manual } | `(any, any -> any) \| module` | | Override the update behavior. Accepts a module or module and opts, or a function that takes the changeset and context. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | +| [`primary?`](#actions-destroy-primary?){: #actions-destroy-primary? } | `boolean` | `false` | Whether or not this action should be used when no action is specified by the caller. | +| [`description`](#actions-destroy-description){: #actions-destroy-description } | `String.t` | | An optional description for the action | +| [`transaction?`](#actions-destroy-transaction?){: #actions-destroy-transaction? } | `boolean` | | Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`. | +| [`touches_resources`](#actions-destroy-touches_resources){: #actions-destroy-touches_resources } | `list(atom)` | | A list of resources that the action may touch, used when building transactions. | +| [`accept`](#actions-destroy-accept){: #actions-destroy-accept } | `:all \| list(atom)` | | The list of attributes to accept. Defaults to all attributes on the resource | +| [`delay_global_validations?`](#actions-destroy-delay_global_validations?){: #actions-destroy-delay_global_validations? } | `boolean` | `false` | If true, global validations will be done in a `before_action` hook, regardless of their configuration on the resource. | +| [`skip_global_validations?`](#actions-destroy-skip_global_validations?){: #actions-destroy-skip_global_validations? } | `boolean` | `false` | If true, global validations will be skipped. Useful for manual actions. | +| [`reject`](#actions-destroy-reject){: #actions-destroy-reject } | `:all \| list(atom)` | | A list of attributes not to accept. If this is specified along with `accept`, these are removed from the `accept` list. | +| [`require_attributes`](#actions-destroy-require_attributes){: #actions-destroy-require_attributes } | `list(atom)` | | A list of attributes that would normally `allow_nil?`, to require for this action. No need to include attributes that already do not allow nil? | +| [`error_handler`](#actions-destroy-error_handler){: #actions-destroy-error_handler } | `mfa` | | Sets the error handler on the changeset. See `Ash.Changeset.handle_errors/2` for more | +| [`manual?`](#actions-destroy-manual?){: #actions-destroy-manual? } | `boolean` | | Instructs Ash to *skip* the actual update/create/destroy step at the data layer. See the [manual actions guide](/documentation/topics/manual-actions.md) for more. | + + +## actions.destroy.change +```elixir +change change +``` + + +A change to be applied to the changeset. + +See `Ash.Resource.Change` for more. + + + + +### Examples +``` +change relate_actor(:reporter) +``` + +``` +change {MyCustomChange, :foo} +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`change`](#actions-destroy-change-change){: #actions-destroy-change-change .spark-required} | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`only_when_valid?`](#actions-destroy-change-only_when_valid?){: #actions-destroy-change-only_when_valid? } | `boolean` | `false` | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. | +| [`description`](#actions-destroy-change-description){: #actions-destroy-change-description } | `String.t` | | An optional description for the change | +| [`where`](#actions-destroy-change-where){: #actions-destroy-change-where } | `list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. | +| [`always_atomic?`](#actions-destroy-change-always_atomic?){: #actions-destroy-change-always_atomic? } | `boolean` | `false` | By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Change` + +## actions.destroy.validate +```elixir +validate validation +``` + + +Declares a validation to be applied to the changeset. + +See `Ash.Resource.Validation` for more. + + + + +### Examples +``` +validate changing(:email) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`validation`](#actions-destroy-validate-validation){: #actions-destroy-validate-validation .spark-required} | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`where`](#actions-destroy-validate-where){: #actions-destroy-validate-where } | `(any -> any) \| module \| list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. | +| [`only_when_valid?`](#actions-destroy-validate-only_when_valid?){: #actions-destroy-validate-only_when_valid? } | `boolean` | `false` | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. | +| [`message`](#actions-destroy-validate-message){: #actions-destroy-validate-message } | `String.t` | | If provided, overrides any message set by the validation error | +| [`description`](#actions-destroy-validate-description){: #actions-destroy-validate-description } | `String.t` | | An optional description for the validation | +| [`before_action?`](#actions-destroy-validate-before_action?){: #actions-destroy-validate-before_action? } | `boolean` | `false` | If set to `true`, the validation will be run in a before_action hook | +| [`always_atomic?`](#actions-destroy-validate-always_atomic?){: #actions-destroy-validate-always_atomic? } | `boolean` | `false` | By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Validation` + +## actions.destroy.metadata +```elixir +metadata name, type +``` + + +A special kind of attribute that is only added to specific actions. Nothing sets this value, it must be set in a custom +change via `Ash.Resource.Info.put_metadata/3`. + + + + +### Examples +``` +metadata :api_token, :string, allow_nil?: false + +``` + +``` +metadata :operation_id, :string, allow_nil?: false + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-destroy-metadata-name){: #actions-destroy-metadata-name .spark-required} | `atom` | | The name of the metadata | +| [`type`](#actions-destroy-metadata-type){: #actions-destroy-metadata-type .spark-required} | ``any`` | | The type of the metadata. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#actions-destroy-metadata-constraints){: #actions-destroy-metadata-constraints } | `Keyword.t` | `[]` | Type constraints on the metadata | +| [`description`](#actions-destroy-metadata-description){: #actions-destroy-metadata-description } | `String.t` | | An optional description for the metadata. | +| [`allow_nil?`](#actions-destroy-metadata-allow_nil?){: #actions-destroy-metadata-allow_nil? } | `boolean` | `true` | Whether or not the metadata may return `nil` | +| [`default`](#actions-destroy-metadata-default){: #actions-destroy-metadata-default } | ``any`` | | The default value for the metadata to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Metadata` + +## actions.destroy.argument +```elixir +argument name, type +``` + + +Declares an argument on the action + + + + +### Examples +``` +argument :password_confirmation, :string +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#actions-destroy-argument-name){: #actions-destroy-argument-name .spark-required} | `atom` | | The name of the argument | +| [`type`](#actions-destroy-argument-type){: #actions-destroy-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#actions-destroy-argument-description){: #actions-destroy-argument-description } | `String.t` | | An optional description for the argument. | +| [`constraints`](#actions-destroy-argument-constraints){: #actions-destroy-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. For more information, see [the constraints topic](/documentation/topics/constraints.md). | +| [`allow_nil?`](#actions-destroy-argument-allow_nil?){: #actions-destroy-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided). If nil value is given error is raised. | +| [`private?`](#actions-destroy-argument-private?){: #actions-destroy-argument-private? } | `boolean` | `false` | Whether or not the argument should be suppliable by the client. | +| [`sensitive?`](#actions-destroy-argument-sensitive?){: #actions-destroy-argument-sensitive? } | `boolean` | `false` | Whether or not the argument value contains sensitive information, like PII. See the [security guide](/documentation/topics/security.md) for more. | +| [`default`](#actions-destroy-argument-default){: #actions-destroy-argument-default } | ``any`` | | The default value for the argument to take. It can be a zero argument function e.g `&MyMod.my_fun/0` or a value | + + + + + +### Introspection + +Target: `Ash.Resource.Actions.Argument` + + + + +### Introspection + +Target: `Ash.Resource.Actions.Destroy` + + + + +## code_interface +Functions that will be defined on the Api module to interact with this resource. See the [code interface guide](/documentation/topics/code-interface.md) for more. + + +### Nested DSLs + * [define](#code_interface-define) + * [define_calculation](#code_interface-define_calculation) + + +### Examples +``` +code_interface do + define_for MyApp.Api + define :create_user, action: :create + define :get_user_by_id, action: :get_by_id, args: [:id], get?: true +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`define_for`](#code_interface-define_for){: #code_interface-define_for } | `module` | `false` | Defines the code interface on the resource module directly, using the provided Api. | + + + +## code_interface.define +```elixir +define name +``` + + +Defines a function with the corresponding name and arguments. See the [code interface guide](/documentation/topics/code-interface.md) for more. + + + + +### Examples +``` +define :get_user_by_id, action: :get_by_id, args: [:id], get?: true +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#code_interface-define-name){: #code_interface-define-name .spark-required} | `atom` | | The name of the function that will be defined | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`action`](#code_interface-define-action){: #code_interface-define-action } | `atom` | | The name of the action that will be called. Defaults to the same name as the function. | +| [`args`](#code_interface-define-args){: #code_interface-define-args } | `list(atom \| {:optional, atom})` | | Map specific arguments to named inputs. Can provide any argument/attributes that the action allows. | +| [`not_found_error?`](#code_interface-define-not_found_error?){: #code_interface-define-not_found_error? } | `boolean` | `true` | If the action or interface is configured with `get?: true`, this determines whether or not an error is raised or `nil` is returned. | +| [`get?`](#code_interface-define-get?){: #code_interface-define-get? } | `boolean` | | Expects to only receive a single result from a read action, and returns a single result instead of a list. Ignored for other action types. | +| [`get_by`](#code_interface-define-get_by){: #code_interface-define-get_by } | `atom \| list(atom)` | | Takes a list of fields and adds those fields as arguments, which will then be used to filter. Sets `get?` to true automatically. Ignored for non-read actions. | +| [`get_by_identity`](#code_interface-define-get_by_identity){: #code_interface-define-get_by_identity } | `atom` | | Only relevant for read actions. Takes an identity, and gets its field list, performing the same logic as `get_by` once it has the list of fields. | + + + + + +### Introspection + +Target: `Ash.Resource.Interface` + +## code_interface.define_calculation +```elixir +define_calculation name +``` + + +Defines a function with the corresponding name and arguments, that evaluates a calculation. Use `:_record` to take an instance of a record. See the [code interface guide](/documentation/topics/code-interface.md) for more. + + + + +### Examples +``` +define_calculation :referral_link, args: [:id] +``` + +``` +define_calculation :referral_link, args: [{:arg, :id}, {:ref, :id}] +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#code_interface-define_calculation-name){: #code_interface-define_calculation-name .spark-required} | `atom` | | The name of the function that will be defined | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`calculation`](#code_interface-define_calculation-calculation){: #code_interface-define_calculation-calculation } | `atom` | | The name of the calculation that will be evaluated. Defaults to the same name as the function. | +| [`args`](#code_interface-define_calculation-args){: #code_interface-define_calculation-args } | ``any`` | `[]` | Supply field or argument values referenced by the calculation, in the form of :name, `{:arg, :name}` and/or `{:ref, :name}`. See the [code interface guide](/documentation/topics/code-interface.md) for more. | + + + + + +### Introspection + +Target: `Ash.Resource.CalculationInterface` + + + + +## resource +General resource configuration + + + + +### Examples +``` +resource do + description "A description of this resource" + base_filter [is_nil: :deleted_at] +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`description`](#resource-description){: #resource-description } | `String.t` | | A human readable description of the resource, to be used in generated documentation | +| [`base_filter`](#resource-base_filter){: #resource-base_filter } | ``any`` | | A filter statement to be applied to any queries on the resource | +| [`default_context`](#resource-default_context){: #resource-default_context } | ``any`` | | Default context to apply to any queries/changesets generated for this resource. | +| [`trace_name`](#resource-trace_name){: #resource-trace_name } | `String.t` | | The name to use in traces. Defaults to the short_name stringified. See the [monitoring guide](/documentation/topics/monitoring.md) for more. | +| [`short_name`](#resource-short_name){: #resource-short_name } | `atom` | | A short identifier for the resource, which should be unique. See the [monitoring guide](/documentation/topics/monitoring.md) for more. | +| [`plural_name`](#resource-plural_name){: #resource-plural_name } | `atom` | | A pluralized version of the resource short_name. May be used by generators or automated tooling. | +| [`simple_notifiers`](#resource-simple_notifiers){: #resource-simple_notifiers } | `list(module)` | | A list of notifiers that require no DSL. Can be used to avoid compile time dependencies on notifiers | +| [`require_primary_key?`](#resource-require_primary_key?){: #resource-require_primary_key? } | `boolean` | `true` | Allow the resource to be used without any primary key fields. Warning: this option is experimental, and should not be used unless you know what you're doing. | + + + + + + +## identities +Unique identifiers for the resource + + +### Nested DSLs + * [identity](#identities-identity) + + +### Examples +``` +identities do + identity :full_name, [:first_name, :last_name] + identity :email, [:email] +end + +``` + + + + +## identities.identity +```elixir +identity name, keys +``` + + +Represents a unique constraint on the resource. + +See the [identities guide](/documentation/topics/identities.md) for more. + + + + +### Examples +``` +identity :name, [:name] +``` + +``` +identity :full_name, [:first_name, :last_name] +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#identities-identity-name){: #identities-identity-name .spark-required} | `atom` | | The name of the identity. | +| [`keys`](#identities-identity-keys){: #identities-identity-keys .spark-required} | `atom \| list(atom)` | | The names of the attributes that uniquely identify this resource. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`eager_check_with`](#identities-identity-eager_check_with){: #identities-identity-eager_check_with } | `module` | | Validates that the unique identity provided is unique at validation time, outside of any transactions, using the api module provided. | +| [`pre_check_with`](#identities-identity-pre_check_with){: #identities-identity-pre_check_with } | `module` | | Validates that the unique identity provided is unique in a before_action hook. | +| [`description`](#identities-identity-description){: #identities-identity-description } | `String.t` | | An optional description for the identity | +| [`message`](#identities-identity-message){: #identities-identity-message } | `String.t` | | An error message to use when the unique identity would be violated | + + + + + +### Introspection + +Target: `Ash.Resource.Identity` + + + + +## changes +Declare changes that occur on create/update/destroy actions against the resource + +See `Ash.Resource.Change` for more. + + +### Nested DSLs + * [change](#changes-change) + + +### Examples +``` +changes do + change {Mod, [foo: :bar]} + change set_context(%{some: :context}) +end + +``` + + + + +## changes.change +```elixir +change change +``` + + +A change to be applied to the changeset. + +See `Ash.Resource.Change` for more. + + + + +### Examples +``` +change relate_actor(:reporter) +``` + +``` +change {MyCustomChange, :foo} +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`change`](#changes-change-change){: #changes-change-change .spark-required} | `(any, any -> any) \| module` | | The module and options for a change. Also accepts a function that takes the changeset and the context. See `Ash.Resource.Change.Builtins` for builtin changes. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`on`](#changes-change-on){: #changes-change-on } | `:create \| :update \| :destroy \| list(:create \| :update \| :destroy)` | `[:create, :update]` | The action types the validation should run on. Destroy actions are omitted by default as most changes don't make sense for a destroy. | +| [`only_when_valid?`](#changes-change-only_when_valid?){: #changes-change-only_when_valid? } | `boolean` | `false` | If the change should only be run on valid changes. By default, all changes are run unless stated otherwise here. | +| [`description`](#changes-change-description){: #changes-change-description } | `String.t` | | An optional description for the change | +| [`where`](#changes-change-where){: #changes-change-where } | `list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. These validations failing will result in this validation being ignored. | +| [`always_atomic?`](#changes-change-always_atomic?){: #changes-change-always_atomic? } | `boolean` | `false` | By default, changes are only run atomically if all changes will be run atomically or if there is no `change/3` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Change` + + + + +## preparations +Declare preparations that occur on all read actions for a given resource + + +### Nested DSLs + * [prepare](#preparations-prepare) + + +### Examples +``` +preparations do + prepare {Mod, [foo: :bar]} + prepare set_context(%{some: :context}) +end + +``` + + + + +## preparations.prepare +```elixir +prepare preparation +``` + + +Declares a preparation, which can be used to prepare a query for a read action. + + + + +### Examples +``` +prepare build(sort: [:foo, :bar]) + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`preparation`](#preparations-prepare-preparation){: #preparations-prepare-preparation .spark-required} | `(any, any -> any) \| module` | | The module and options for a preparation. Also accepts functions take the query and the context. | + + + + + + +### Introspection + +Target: `Ash.Resource.Preparation` + + + + +## validations +Declare validations prior to performing actions against the resource + + +### Nested DSLs + * [validate](#validations-validate) + + +### Examples +``` +validations do + validate {Mod, [foo: :bar]} + validate at_least_one_of_present([:first_name, :last_name]) +end + +``` + + + + +## validations.validate +```elixir +validate validation +``` + + +Declares a validation for creates and updates. + +See `Ash.Resource.Change` for more. + + + + +### Examples +``` +validate {Mod, [foo: :bar]} +``` + +``` +validate at_least_one_of_present([:first_name, :last_name]) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`validation`](#validations-validate-validation){: #validations-validate-validation .spark-required} | `(any -> any) \| module` | | The module (or module and opts) that implements the `Ash.Resource.Validation` behaviour. Also accepts a one argument function that takes the changeset. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`where`](#validations-validate-where){: #validations-validate-where } | `(any -> any) \| module \| list((any -> any) \| module)` | `[]` | Validations that should pass in order for this validation to apply. Any of these validations failing will result in this validation being ignored. | +| [`on`](#validations-validate-on){: #validations-validate-on } | `:create \| :update \| :destroy \| list(:create \| :update \| :destroy)` | `[:create, :update]` | The action types the validation should run on. Many validations don't make sense in the context of deletion, so by default it is not included. | +| [`only_when_valid?`](#validations-validate-only_when_valid?){: #validations-validate-only_when_valid? } | `boolean` | `false` | If the validation should only run on valid changes. Useful for expensive validations or validations that depend on valid data. | +| [`message`](#validations-validate-message){: #validations-validate-message } | `String.t` | | If provided, overrides any message set by the validation error | +| [`description`](#validations-validate-description){: #validations-validate-description } | `String.t` | | An optional description for the validation | +| [`before_action?`](#validations-validate-before_action?){: #validations-validate-before_action? } | `boolean` | `false` | If set to `true`, the validation will be run in a before_action hook | +| [`always_atomic?`](#validations-validate-always_atomic?){: #validations-validate-always_atomic? } | `boolean` | `false` | By default, validations are only run atomically if all changes will be run atomically or if there is no `validate/2` callback defined. Set this to `true` to run it atomically always. | + + + + + +### Introspection + +Target: `Ash.Resource.Validation` + + + + +## aggregates +Declare named aggregates on the resource. + +These are aggregates that can be loaded only by name using `Ash.Query.load/2`. +They are also available as top level fields on the resource. + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + +### Nested DSLs + * [count](#aggregates-count) + * [exists](#aggregates-exists) + * [first](#aggregates-first) + * [sum](#aggregates-sum) + * [list](#aggregates-list) + * [max](#aggregates-max) + * [min](#aggregates-min) + * [avg](#aggregates-avg) + * [custom](#aggregates-custom) + + +### Examples +``` +aggregates do + count :assigned_ticket_count, :reported_tickets do + filter [active: true] + end +end + +``` + + + + +## aggregates.count +```elixir +count name, relationship_path +``` + + +Declares a named count aggregate on the resource + +Supports `filter`, but not `sort` (because that wouldn't affect the count) + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +count :assigned_ticket_count, :assigned_tickets do + filter [active: true] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-count-name){: #aggregates-count-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-count-relationship_path){: #aggregates-count-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-count-kind){: #aggregates-count-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`uniq?`](#aggregates-count-uniq?){: #aggregates-count-uniq? } | `boolean` | `false` | Whether or not to count unique values only | +| [`read_action`](#aggregates-count-read_action){: #aggregates-count-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`field`](#aggregates-count-field){: #aggregates-count-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +| [`filter`](#aggregates-count-filter){: #aggregates-count-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`description`](#aggregates-count-description){: #aggregates-count-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-count-default){: #aggregates-count-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-count-private?){: #aggregates-count-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-count-filterable?){: #aggregates-count-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-count-authorize?){: #aggregates-count-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.exists +```elixir +exists name, relationship_path +``` + + +Declares a named `exists` aggregate on the resource + +Supports `filter`, but not `sort` (because that wouldn't affect if something exists) + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +exists :has_ticket, :assigned_tickets + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-exists-name){: #aggregates-exists-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-exists-relationship_path){: #aggregates-exists-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-exists-kind){: #aggregates-exists-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-exists-read_action){: #aggregates-exists-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-exists-filter){: #aggregates-exists-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`description`](#aggregates-exists-description){: #aggregates-exists-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-exists-default){: #aggregates-exists-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-exists-private?){: #aggregates-exists-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-exists-filterable?){: #aggregates-exists-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-exists-authorize?){: #aggregates-exists-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.first +```elixir +first name, relationship_path, field +``` + + +Declares a named `first` aggregate on the resource + +First aggregates return the first value of the related record +that matches. Supports both `filter` and `sort`. + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +first :first_assigned_ticket_subject, :assigned_tickets, :subject do + filter [active: true] + sort [:subject] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-first-name){: #aggregates-first-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-first-relationship_path){: #aggregates-first-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`field`](#aggregates-first-field){: #aggregates-first-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-first-kind){: #aggregates-first-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-first-read_action){: #aggregates-first-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-first-filter){: #aggregates-first-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`sort`](#aggregates-first-sort){: #aggregates-first-sort } | ``any`` | | A sort to be applied to the aggregate | +| [`description`](#aggregates-first-description){: #aggregates-first-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-first-default){: #aggregates-first-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-first-private?){: #aggregates-first-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-first-filterable?){: #aggregates-first-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-first-authorize?){: #aggregates-first-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.sum +```elixir +sum name, relationship_path, field +``` + + +Declares a named `sum` aggregate on the resource + +Supports `filter`, but not `sort` (because that wouldn't affect the sum) + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +sum :assigned_ticket_price_sum, :assigned_tickets, :price do + filter [active: true] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-sum-name){: #aggregates-sum-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-sum-relationship_path){: #aggregates-sum-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`field`](#aggregates-sum-field){: #aggregates-sum-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-sum-kind){: #aggregates-sum-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-sum-read_action){: #aggregates-sum-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-sum-filter){: #aggregates-sum-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`description`](#aggregates-sum-description){: #aggregates-sum-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-sum-default){: #aggregates-sum-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-sum-private?){: #aggregates-sum-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-sum-filterable?){: #aggregates-sum-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-sum-authorize?){: #aggregates-sum-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.list +```elixir +list name, relationship_path, field +``` + + +Declares a named `list` aggregate on the resource. + +A list aggregate selects the list of all values for the given field +and relationship combination. + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +list :assigned_ticket_prices, :assigned_tickets, :price do + filter [active: true] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-list-name){: #aggregates-list-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-list-relationship_path){: #aggregates-list-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`field`](#aggregates-list-field){: #aggregates-list-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-list-kind){: #aggregates-list-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`uniq?`](#aggregates-list-uniq?){: #aggregates-list-uniq? } | `boolean` | `false` | Whether or not to count unique values only | +| [`read_action`](#aggregates-list-read_action){: #aggregates-list-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-list-filter){: #aggregates-list-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`sort`](#aggregates-list-sort){: #aggregates-list-sort } | ``any`` | | A sort to be applied to the aggregate | +| [`description`](#aggregates-list-description){: #aggregates-list-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-list-default){: #aggregates-list-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-list-private?){: #aggregates-list-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-list-filterable?){: #aggregates-list-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-list-authorize?){: #aggregates-list-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.max +```elixir +max name, relationship_path, field +``` + + +Declares a named `max` aggregate on the resource + +Supports `filter`, but not `sort` (because that wouldn't affect the max) + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +max :first_assigned_ticket_subject, :assigned_tickets, :severity do + filter [active: true] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-max-name){: #aggregates-max-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-max-relationship_path){: #aggregates-max-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`field`](#aggregates-max-field){: #aggregates-max-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-max-kind){: #aggregates-max-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-max-read_action){: #aggregates-max-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-max-filter){: #aggregates-max-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`description`](#aggregates-max-description){: #aggregates-max-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-max-default){: #aggregates-max-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-max-private?){: #aggregates-max-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-max-filterable?){: #aggregates-max-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-max-authorize?){: #aggregates-max-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.min +```elixir +min name, relationship_path, field +``` + + +Declares a named `min` aggregate on the resource + +Supports `filter`, but not `sort` (because that wouldn't affect the min) + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +min :first_assigned_ticket_subject, :assigned_tickets, :severity do + filter [active: true] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-min-name){: #aggregates-min-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-min-relationship_path){: #aggregates-min-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`field`](#aggregates-min-field){: #aggregates-min-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-min-kind){: #aggregates-min-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-min-read_action){: #aggregates-min-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-min-filter){: #aggregates-min-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`description`](#aggregates-min-description){: #aggregates-min-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-min-default){: #aggregates-min-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-min-private?){: #aggregates-min-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-min-filterable?){: #aggregates-min-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-min-authorize?){: #aggregates-min-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.avg +```elixir +avg name, relationship_path, field +``` + + +Declares a named `avg` aggregate on the resource + +Supports `filter`, but not `sort` (because that wouldn't affect the avg) + +See the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +avg :assigned_ticket_price_sum, :assigned_tickets, :price do + filter [active: true] +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-avg-name){: #aggregates-avg-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-avg-relationship_path){: #aggregates-avg-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`field`](#aggregates-avg-field){: #aggregates-avg-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`kind`](#aggregates-avg-kind){: #aggregates-avg-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-avg-read_action){: #aggregates-avg-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`filter`](#aggregates-avg-filter){: #aggregates-avg-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`description`](#aggregates-avg-description){: #aggregates-avg-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-avg-default){: #aggregates-avg-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-avg-private?){: #aggregates-avg-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-avg-filterable?){: #aggregates-avg-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-avg-authorize?){: #aggregates-avg-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + +## aggregates.custom +```elixir +custom name, relationship_path, type +``` + + +Declares a named `custom` aggregate on the resource + +Supports `filter` and `sort`. + +Custom aggregates provide an `implementation` which must implement data layer specific callbacks. + +See the relevant data layer documentation and the [aggregates guide](/documentation/topics/aggregates.md) for more. + + + + +### Examples +``` +custom :author_names, :authors, :string do + implementation {StringAgg, delimiter: ","} +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#aggregates-custom-name){: #aggregates-custom-name .spark-required} | `atom` | | The field to place the aggregate in | +| [`relationship_path`](#aggregates-custom-relationship_path){: #aggregates-custom-relationship_path .spark-required} | `atom \| list(atom)` | | The relationship or relationship path to use for the aggregate | +| [`type`](#aggregates-custom-type){: #aggregates-custom-type .spark-required} | `module` | | The type of the value returned by the aggregate | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`implementation`](#aggregates-custom-implementation){: #aggregates-custom-implementation .spark-required} | `module` | | The module that implements the relevant data layer callbacks | +| [`kind`](#aggregates-custom-kind){: #aggregates-custom-kind .spark-required} | `:count \| :first \| :sum \| :list \| :avg \| :max \| :min \| :exists \| :custom \| {:custom, module}` | | The kind of the aggregate | +| [`read_action`](#aggregates-custom-read_action){: #aggregates-custom-read_action } | `atom` | | The read action to use when building the aggregate. Defaults to the primary read action. Keep in mind this action must not have any required arguments. | +| [`field`](#aggregates-custom-field){: #aggregates-custom-field } | `atom` | | The field to aggregate. Defaults to the first field in the primary key of the resource | +| [`filter`](#aggregates-custom-filter){: #aggregates-custom-filter } | ``any`` | `[]` | A filter to apply to the aggregate | +| [`sort`](#aggregates-custom-sort){: #aggregates-custom-sort } | ``any`` | | A sort to be applied to the aggregate | +| [`description`](#aggregates-custom-description){: #aggregates-custom-description } | `String.t` | | An optional description for the aggregate | +| [`default`](#aggregates-custom-default){: #aggregates-custom-default } | ``any`` | | A default value to use in cases where nil would be used. Count defaults to `0`. | +| [`private?`](#aggregates-custom-private?){: #aggregates-custom-private? } | `boolean` | `false` | Whether or not the aggregate will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql | +| [`filterable?`](#aggregates-custom-filterable?){: #aggregates-custom-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the aggregate should be usable in filters. | +| [`authorize?`](#aggregates-custom-authorize?){: #aggregates-custom-authorize? } | `boolean` | `true` | Whether or not the aggregate query should authorize based on the target action, if the parent query is authorized. Requires filter checks on the target action. | + + + + + +### Introspection + +Target: `Ash.Resource.Aggregate` + + + + +## calculations +Declare named calculations on the resource. + +These are calculations that can be loaded only by name using `Ash.Query.load/2`. +They are also available as top level fields on the resource. + +See the [calculations guide](/documentation/topics/calculations.md) for more. + + +### Nested DSLs + * [calculate](#calculations-calculate) + * argument + + +### Examples +``` +calculations do + calculate :full_name, :string, MyApp.MyResource.FullName +end + +``` + + + + +## calculations.calculate +```elixir +calculate name, type, calculation \\ nil +``` + + +Declares a named calculation on the resource. + +Takes a module that must adopt the `Ash.Calculation` behaviour. See that module +for more information. + +To ensure that the necessary fields are selected: + +1.) Specifying the `select` option on a calculation in the resource. +2.) Define a `select/2` callback in the calculation module +3.) Set `always_select?` on the attribute in question + +See the [calculations guide](/documentation/topics/calculations.md) for more. + + +### Nested DSLs + * [argument](#calculations-calculate-argument) + + +### Examples +`Ash.Calculation` implementation example: +``` +calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}, select: [:first_name, :last_name] +``` + +`expr/1` example: +``` +calculate :full_name, :string, expr(first_name <> " " <> last_name) +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#calculations-calculate-name){: #calculations-calculate-name .spark-required} | `atom` | | The field name to use for the calculation value | +| [`type`](#calculations-calculate-type){: #calculations-calculate-type .spark-required} | ``any`` | | The type of the calculation. See `Ash.Type` for more. | +| [`calculation`](#calculations-calculate-calculation){: #calculations-calculate-calculation .spark-required} | `(any, any -> any) \| module \| `any`` | | The `module`, `{module, opts}` or `expr(...)` to use for the calculation. Also accepts a function that takes *a single record* and produces the result. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`constraints`](#calculations-calculate-constraints){: #calculations-calculate-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type. See `Ash.Type` for more. | +| [`description`](#calculations-calculate-description){: #calculations-calculate-description } | `String.t` | | An optional description for the calculation | +| [`private?`](#calculations-calculate-private?){: #calculations-calculate-private? } | `boolean` | `false` | Whether or not the calculation will appear in any interfaces created off of this resource, e.g AshJsonApi and AshGraphql See the [security guide](/documentation/topics/security.md) for more. | +| [`select`](#calculations-calculate-select){: #calculations-calculate-select } | `list(atom)` | `[]` | A list of fields to ensure selected if the calculation is used. | +| [`load`](#calculations-calculate-load){: #calculations-calculate-load } | ``any`` | `[]` | A load statement to be applied if the calculation is used. | +| [`allow_nil?`](#calculations-calculate-allow_nil?){: #calculations-calculate-allow_nil? } | `boolean` | `true` | Whether or not the calculation can return nil. | +| [`filterable?`](#calculations-calculate-filterable?){: #calculations-calculate-filterable? } | `boolean \| :simple_equality` | `true` | Whether or not the calculation should be usable in filters. | + + +## calculations.calculate.argument +```elixir +argument name, type +``` + + +An argument to be passed into the calculation's arguments map + +See the [calculations guide](/documentation/topics/calculations.md) for more. + + + + +### Examples +``` +argument :params, :map do + default %{} +end + +``` + +``` +argument :retries, :integer do + allow_nil? false +end + +``` + + + +### Arguments + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`name`](#calculations-calculate-argument-name){: #calculations-calculate-argument-name .spark-required} | `atom` | | The name of the argument | +| [`type`](#calculations-calculate-argument-type){: #calculations-calculate-argument-type .spark-required} | `module` | | The type of the argument. See `Ash.Type` for more. | +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`default`](#calculations-calculate-argument-default){: #calculations-calculate-argument-default } | `(-> any) \| mfa \| any()` | | A default value to use for the argument if not provided | +| [`allow_nil?`](#calculations-calculate-argument-allow_nil?){: #calculations-calculate-argument-allow_nil? } | `boolean` | `true` | Whether or not the argument value may be nil (or may be not provided) | +| [`allow_expr?`](#calculations-calculate-argument-allow_expr?){: #calculations-calculate-argument-allow_expr? } | `boolean` | `false` | Allow passing expressions as argument values. Expressions cannot be type validated. | +| [`constraints`](#calculations-calculate-argument-constraints){: #calculations-calculate-argument-constraints } | `Keyword.t` | `[]` | Constraints to provide to the type when casting the value. See the type's documentation and `Ash.Type` for more. | + + + + + +### Introspection + +Target: `Ash.Resource.Calculation.Argument` + + + + +### Introspection + +Target: `Ash.Resource.Calculation` + + + + +## multitenancy +Options for configuring the multitenancy behavior of a resource. + +To specify a tenant, use `Ash.Query.set_tenant/2` or +`Ash.Changeset.set_tenant/2` before passing it to an operation. + +See the [multitenancy guide](/documentation/topics/multitenancy.md) + + + + +### Examples +``` +multitenancy do + strategy :attribute + attribute :organization_id + global? true +end + +``` + + + + +### Options + +| Name | Type | Default | Docs | +|------|------|---------|------| +| [`strategy`](#multitenancy-strategy){: #multitenancy-strategy } | `:context \| :attribute` | `:context` | Determine if multitenancy is performed with attribute filters or using data layer features. | +| [`attribute`](#multitenancy-attribute){: #multitenancy-attribute } | `atom` | | If using the `attribute` strategy, the attribute to use, e.g `org_id` | +| [`global?`](#multitenancy-global?){: #multitenancy-global? } | `boolean` | `false` | Whether or not the data also exists outside of each tenant. | +| [`parse_attribute`](#multitenancy-parse_attribute){: #multitenancy-parse_attribute } | `mfa` | `{Ash.Resource.Dsl, :identity, []}` | An mfa ({module, function, args}) pointing to a function that takes a tenant and returns the attribute value | + + + + + + + + diff --git a/lib/ash/action_input.ex b/lib/ash/action_input.ex index 174629aba..185a4d13d 100644 --- a/lib/ash/action_input.ex +++ b/lib/ash/action_input.ex @@ -11,6 +11,7 @@ defmodule Ash.ActionInput do :action, :api, :resource, + :tenant, invalid_keys: MapSet.new(), arguments: %{}, params: %{}, @@ -22,6 +23,7 @@ defmodule Ash.ActionInput do @type t :: %__MODULE__{ arguments: map(), params: map(), + tenant: String.t() | nil, action: Ash.Resource.Actions.Action.t() | nil, resource: Ash.Resource.t(), invalid_keys: MapSet.t(), @@ -61,6 +63,11 @@ defmodule Ash.ActionInput do |> require_arguments() end + @spec set_tenant(t(), String.t() | nil) :: t() + def set_tenant(input, tenant) do + %{input | tenant: tenant} + end + defp require_arguments(input) do input.action.arguments |> Enum.filter(&(&1.allow_nil? == false)) diff --git a/lib/ash/actions/aggregate.ex b/lib/ash/actions/aggregate.ex index fb5b55c3c..91d29863f 100644 --- a/lib/ash/actions/aggregate.ex +++ b/lib/ash/actions/aggregate.ex @@ -8,116 +8,113 @@ defmodule Ash.Actions.Aggregate do action = query.action || Ash.Resource.Info.primary_action!(query.resource, :read) opts = Keyword.put_new(opts, :read_action, action.name) - case validate_aggregates(query, aggregates, opts) do - {:ok, aggregates} -> - aggregates - |> Enum.group_by(fn aggregate -> - agg_authorize? = aggregate.authorize? && opts[:authorize?] - - read_action = - aggregate.read_action || - Ash.Resource.Info.primary_action!(query.resource, :read).name - - {agg_authorize?, read_action} - end) - |> Enum.reduce_while({:ok, %{}}, fn {{agg_authorize?, read_action}, aggregates}, - {:ok, acc} -> - Ash.Tracer.span :action, - Ash.Api.Info.span_name(query.api, query.resource, :aggregate), - opts[:tracer] do - metadata = %{ - api: query.api, - resource: query.resource, - resource_short_name: Ash.Resource.Info.short_name(query.resource), - aggregates: List.wrap(aggregates), - actor: opts[:actor], - tenant: opts[:tenant], - action: action.name, - authorize?: opts[:authorize?] - } - - Ash.Tracer.telemetry_span [:ash, Ash.Api.Info.short_name(query.api), :aggregate], - metadata do - Ash.Tracer.set_metadata(opts[:tracer], :action, metadata) - query = Map.put(query, :aggregates, Map.new(aggregates, &{&1.name, &1})) - - {aggregate_auth_requests, [], aggregates_in_query} = - Ash.Query.Aggregate.requests( - query, - true, - opts[:authorize?], - [], - [] - ) - - query = %{query | aggregates: %{}} - resource = query.resource - - case aggregate_auth_requests do - [] -> - case Ash.Query.data_layer_query(query) do - {:ok, query} -> - case Ash.DataLayer.run_aggregate_query(query, aggregates_in_query, resource) do - {:ok, result} -> - {:cont, {:ok, Map.merge(acc, result)}} - - other -> - {:halt, other} - end - - {:error, error} -> - {:halt, {:error, error}} - end - - requests -> - case Ash.Engine.run(requests, - verbose?: opts[:verbose?], - actor: opts[:actor], - authorize?: opts[:authorize?], - api: query.api, - resource: query.resource, - tracer: opts[:tracer], - query: query - ) do - {:ok, - %{ - data: %{ - aggregate: %{ - [] => %{{^agg_authorize?, ^read_action} => filter} - } + with {:ok, aggregates} <- validate_aggregates(query, aggregates, opts), + %{valid?: true} = query <- Ash.Actions.Read.handle_attribute_multitenancy(query) do + aggregates + |> Enum.group_by(fn aggregate -> + agg_authorize? = aggregate.authorize? && opts[:authorize?] + + read_action = + aggregate.read_action || + Ash.Resource.Info.primary_action!(query.resource, :read).name + + {agg_authorize?, read_action} + end) + |> Enum.reduce_while({:ok, %{}}, fn {{agg_authorize?, read_action}, aggregates}, + {:ok, acc} -> + Ash.Tracer.span :action, + Ash.Api.Info.span_name(query.api, query.resource, :aggregate), + opts[:tracer] do + metadata = %{ + api: query.api, + resource: query.resource, + resource_short_name: Ash.Resource.Info.short_name(query.resource), + aggregates: List.wrap(aggregates), + actor: opts[:actor], + tenant: opts[:tenant], + action: action.name, + authorize?: opts[:authorize?] + } + + Ash.Tracer.telemetry_span [:ash, Ash.Api.Info.short_name(query.api), :aggregate], + metadata do + Ash.Tracer.set_metadata(opts[:tracer], :action, metadata) + query = Map.put(query, :aggregates, Map.new(aggregates, &{&1.name, &1})) + + {aggregate_auth_requests, [], aggregates_in_query} = + Ash.Query.Aggregate.requests( + query, + true, + opts[:authorize?], + [], + [] + ) + + query = %{query | aggregates: %{}} + resource = query.resource + + case aggregate_auth_requests do + [] -> + case Ash.Query.data_layer_query(query) do + {:ok, query} -> + case Ash.DataLayer.run_aggregate_query(query, aggregates_in_query, resource) do + {:ok, result} -> + {:cont, {:ok, Map.merge(acc, result)}} + + other -> + {:halt, other} + end + + {:error, error} -> + {:halt, {:error, error}} + end + + requests -> + case Ash.Engine.run(requests, + verbose?: opts[:verbose?], + actor: opts[:actor], + authorize?: opts[:authorize?], + api: query.api, + resource: query.resource, + tracer: opts[:tracer], + query: query + ) do + {:ok, + %{ + data: %{ + aggregate: %{ + [] => %{{^agg_authorize?, ^read_action} => filter} } - }} -> - query - |> Ash.Query.do_filter(filter) - |> Ash.Query.data_layer_query() - |> case do - {:ok, query} -> - case Ash.DataLayer.run_aggregate_query( - query, - aggregates_in_query, - resource - ) do - {:ok, results} -> - {:cont, {:ok, Map.merge(acc, results)}} - - other -> - {:halt, other} - end - - {:error, error} -> - {:halt, {:error, error}} - end - - {:error, error} -> - {:halt, {:error, Ash.Error.to_ash_error(error)}} - end - end + } + }} -> + query + |> Ash.Query.do_filter(filter) + |> Ash.Query.data_layer_query() + |> case do + {:ok, query} -> + case Ash.DataLayer.run_aggregate_query( + query, + aggregates_in_query, + resource + ) do + {:ok, results} -> + {:cont, {:ok, Map.merge(acc, results)}} + + other -> + {:halt, other} + end + + {:error, error} -> + {:halt, {:error, error}} + end + + {:error, error} -> + {:halt, {:error, Ash.Error.to_ash_error(error)}} + end end end - end) - - {:error, error} -> - {:error, error} + end + end) end end diff --git a/lib/ash/actions/helpers.ex b/lib/ash/actions/helpers.ex index 9b8acf67e..255308e23 100644 --- a/lib/ash/actions/helpers.ex +++ b/lib/ash/actions/helpers.ex @@ -104,11 +104,13 @@ defmodule Ash.Actions.Helpers do query_or_changeset |> Ash.ActionInput.set_context(context) |> Ash.ActionInput.set_context(%{private: private_context}) + |> Ash.ActionInput.set_tenant(query_or_changeset.tenant || opts[:tenant]) %{__struct__: Ash.Query} -> query_or_changeset |> Ash.Query.set_context(context) |> Ash.Query.set_context(%{private: private_context}) + |> Ash.Query.set_tenant(query_or_changeset.tenant || opts[:tenant]) %{__struct__: Ash.Changeset} -> query_or_changeset @@ -116,6 +118,7 @@ defmodule Ash.Actions.Helpers do |> Ash.Changeset.set_context(%{ private: private_context }) + |> Ash.Changeset.set_tenant(query_or_changeset.tenant || opts[:tenant]) end end diff --git a/lib/ash/actions/read.ex b/lib/ash/actions/read.ex index 29b2687ab..0f70b3612 100644 --- a/lib/ash/actions/read.ex +++ b/lib/ash/actions/read.ex @@ -828,7 +828,8 @@ defmodule Ash.Actions.Read do |> Keyword.put(:verbose?, verbose?) end - defp handle_attribute_multitenancy(query) do + @doc false + def handle_attribute_multitenancy(query) do multitenancy_attribute = Ash.Resource.Info.multitenancy_attribute(query.resource) if multitenancy_attribute && query.tenant do diff --git a/test/actions/aggregate_test.exs b/test/actions/aggregate_test.exs index 07fa03e46..dfe0cc865 100644 --- a/test/actions/aggregate_test.exs +++ b/test/actions/aggregate_test.exs @@ -56,6 +56,14 @@ defmodule Ash.Test.Actions.AggregateTest do attribute :public, :boolean do default false end + + attribute :tenant, :string + end + + multitenancy do + global? true + strategy :attribute + attribute :tenant end aggregates do @@ -117,6 +125,27 @@ defmodule Ash.Test.Actions.AggregateTest do assert %{count: 2} = Api.aggregate!(Post, {:count, :count}) end + test "honors tenant" do + assert %{count: 0} = Api.aggregate!(Post, {:count, :count}) + + Post + |> Ash.Changeset.for_create(:create, %{title: "title", tenant: "foo"}) + |> Api.create!() + + assert %{count: 1} = Api.aggregate!(Post, {:count, :count}, tenant: "foo") + + Post + |> Ash.Changeset.for_create(:create, %{title: "title", tenant: "foo"}) + |> Api.create!() + + Post + |> Ash.Changeset.for_create(:create, %{title: "title", tenant: "bar"}) + |> Api.create!() + + assert %{count: 2} = Api.aggregate!(Post, {:count, :count}, tenant: "foo") + assert %{count: 3} = Api.aggregate!(Post, {:count, :count}) + end + test "runs authorization" do assert %{count: 0} = Api.aggregate!(Post, {:count, :count}, authorize?: true)