documentation/dsls/DSL-Ash.Domain.md

Select File:
documentation/dsls/DSL-Ash.Domain.md

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



## domain
General domain configuration



### Examples
```
domain do
  description """
  Resources related to the flux capacitor.
  """
end

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`description`](#domain-description){: #domain-description } | `String.t` |  | A description for the domain. |






## resources
List the resources of this domain

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


### 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 domain will support only registered entries or not. |



### resources.resource
```elixir
resource resource
```


A resource present in the domain

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


### Examples
```
resource Foo
```



### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`resource`](#resources-resource-resource){: #resources-resource-resource .spark-required} | `module` |  |  |



### resources.resource.define
```elixir
define name
```


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


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


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



### Arguments

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

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


### resources.resource.define.custom_input
```elixir
custom_input name, type
```


Define or customize an input to the action.

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


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


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

  constraints instance_of: Artist
end

```



### Arguments

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

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


### resources.resource.define.custom_input.transform


A transformation to be applied to the custom input.




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

```

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

```




### Options

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





### Introspection

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




### Introspection

Target: `Ash.Resource.Interface.CustomInput`




### Introspection

Target: `Ash.Resource.Interface`

### resources.resource.define_calculation
```elixir
define_calculation name
```


Defines a function with the corresponding name and arguments, that evaluates a calculation. Use `:_record` to take an instance of a record. See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.


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


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

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



### Arguments

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

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


### resources.resource.define_calculation.custom_input
```elixir
custom_input name, type
```


Define or customize an input to the action.

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


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


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

  constraints instance_of: Artist
end

```



### Arguments

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

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


### resources.resource.define_calculation.custom_input.transform


A transformation to be applied to the custom input.




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

```

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

```




### Options

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





### Introspection

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




### Introspection

Target: `Ash.Resource.Interface.CustomInput`




### Introspection

Target: `Ash.Resource.CalculationInterface`




### Introspection

Target: `Ash.Domain.Dsl.ResourceReference`




## execution
Options for how requests are executed using this domain



### Examples
```
execution do
  timeout :timer.seconds(30)
end

```




### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`timeout`](#execution-timeout){: #execution-timeout } | `timeout` | `:infinity` | The default timeout in milliseconds to use for requests using this domain. 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 domain. See the [Sensitive Data guide](/documentation/topics/security/sensitive-data.md) for more.




### Examples
```
authorization do
  authorize :always
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` | `:by_default` | When to run authorization for a given request. |







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