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

Adds `belongs_to_versioned`, `has_one_versioned`, and `has_many_versioned` to the
`relationships` section of any resource for relationships _to_ `AshVersioned.Resource`
resources.

```elixir
use Ash.Resource,
  extensions: [AshVersioned.Relationships]

relationships do
  belongs_to_versioned :project, MyApp.Project
end
```

`AshVersioned.Resource` adds this extension automatically, so it only needs to be
added on non-versioned resources.

Each is equivalent to the same Ash relationship that:

- filters on the latest version of the destination (in loads, aggregates, `exists`,
  and data layer joins alike);
- reads through the destination's `__ash_versioned_read__` action by default, which
  includes archived records, so a relationship to an archived record still resolves; and
- for `belongs_to_versioned`, joins on the destination's identity attribute
  (`:resource_id` by default) and never creates a foreign key.

A destination with a non-default `identity` name requires `destination_attribute` on
`belongs_to_versioned` (except for self-referential relationships, which use the
resource's own identity), which is checked once the resources are compiled.

When the source resource is versioned, `has_one_versioned` and `has_many_versioned`
should set `source_attribute` to the source's identity attribute, since the
destination's `belongs_to_versioned` holds the identity rather than the primary key.


### relationships.belongs_to_versioned
```elixir
belongs_to_versioned name, destination
```


Declares a `belongs_to` relationship to the latest version of a versioned resource,
joined on the destination's identity attribute. No foreign key is created, as the
identity attribute is not unique across versions.

Takes the same options as `belongs_to`, except `validate_destination_attribute?`.


### Nested DSLs
 * [filter](#relationships-belongs_to_versioned-filter)


### Examples
```
belongs_to_versioned :project, MyApp.Project
```

```
belongs_to_versioned :document, MyApp.Document do
  destination_attribute :document_id
  allow_nil? false
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-belongs_to_versioned-name){: #relationships-belongs_to_versioned-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-belongs_to_versioned-destination){: #relationships-belongs_to_versioned-destination } | `module` |  | The destination resource |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`primary_key?`](#relationships-belongs_to_versioned-primary_key?){: #relationships-belongs_to_versioned-primary_key? } | `boolean` | `false` | Whether the generated attribute is, or is part of, the primary key of a resource. |
| [`allow_nil?`](#relationships-belongs_to_versioned-allow_nil?){: #relationships-belongs_to_versioned-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_versioned-attribute_writable?){: #relationships-belongs_to_versioned-attribute_writable? } | `boolean` |  | Whether the generated attribute will be marked as writable. If not set, it will default to the relationship's `writable?` setting. |
| [`attribute_public?`](#relationships-belongs_to_versioned-attribute_public?){: #relationships-belongs_to_versioned-attribute_public? } | `boolean` |  | Whether or not the generated attribute will be public. If not set, it will default to the relationship's `public?` setting. |
| [`attribute_always_select?`](#relationships-belongs_to_versioned-attribute_always_select?){: #relationships-belongs_to_versioned-attribute_always_select? } | `boolean` | `false` | Whether or not the generated attribute will be always selected when reading from the database. |
| [`define_attribute?`](#relationships-belongs_to_versioned-define_attribute?){: #relationships-belongs_to_versioned-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_versioned-attribute_type){: #relationships-belongs_to_versioned-attribute_type } | `any` | `:uuid` | The type of the generated created attribute. See `Ash.Type` for more. |
| [`description`](#relationships-belongs_to_versioned-description){: #relationships-belongs_to_versioned-description } | `String.t` |  | An optional description for the relationship |
| [`destination_attribute`](#relationships-belongs_to_versioned-destination_attribute){: #relationships-belongs_to_versioned-destination_attribute } | `atom` |  | The destination's identity attribute. Defaults to `:resource_id`, but self-referential relationships to versioned resources resolve automatically. |
| [`source_attribute`](#relationships-belongs_to_versioned-source_attribute){: #relationships-belongs_to_versioned-source_attribute } | `atom` |  | The field on this resource that should match the `destination_attribute` on the related resource. - Defaults to <name>_id |
| [`relationship_context`](#relationships-belongs_to_versioned-relationship_context){: #relationships-belongs_to_versioned-relationship_context } | `any` |  | Context to be set on any queries or changesets generated for managing or querying this relationship. |
| [`public?`](#relationships-belongs_to_versioned-public?){: #relationships-belongs_to_versioned-public? } | `boolean` | `false` | Whether or not the relationship will appear in public interfaces |
| [`not_found_message`](#relationships-belongs_to_versioned-not_found_message){: #relationships-belongs_to_versioned-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_versioned-writable?){: #relationships-belongs_to_versioned-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. |
| [`read_action`](#relationships-belongs_to_versioned-read_action){: #relationships-belongs_to_versioned-read_action } | `atom` | `:__ash_versioned_read__` | The read action on the destination resource used when loading data and filtering. Defaults to `:__ash_versioned_read__`, generated on every versioned resource, which returns the latest version of each record whether or not it is archived. |
| [`read_action_arguments`](#relationships-belongs_to_versioned-read_action_arguments){: #relationships-belongs_to_versioned-read_action_arguments } | `map` | `%{}` | Arguments to pass to the configured `read_action` when loading data and filtering. Arguments provided explicitly when loading the relationship take precedence over these arguments. |
| [`domain`](#relationships-belongs_to_versioned-domain){: #relationships-belongs_to_versioned-domain } | `atom` |  | The domain module to use when working with the related entity. |
| [`filterable?`](#relationships-belongs_to_versioned-filterable?){: #relationships-belongs_to_versioned-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. |
| [`sortable?`](#relationships-belongs_to_versioned-sortable?){: #relationships-belongs_to_versioned-sortable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in sorts. |
| [`sort`](#relationships-belongs_to_versioned-sort){: #relationships-belongs_to_versioned-sort } | `any` |  | A sort statement to be applied when loading the relationship. |
| [`default_sort`](#relationships-belongs_to_versioned-default_sort){: #relationships-belongs_to_versioned-default_sort } | `any` |  | A default sort statement to be applied when loading the relationship. |
| [`violation_message`](#relationships-belongs_to_versioned-violation_message){: #relationships-belongs_to_versioned-violation_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on destroy. |
| [`authorize_read_with`](#relationships-belongs_to_versioned-authorize_read_with){: #relationships-belongs_to_versioned-authorize_read_with } | `:error \| :filter` |  | If set to `:error`, any authorization filter added to the relationship will result in an error if any record matches the filter in the database. |
| [`allow_forbidden_field?`](#relationships-belongs_to_versioned-allow_forbidden_field?){: #relationships-belongs_to_versioned-allow_forbidden_field? } | `boolean` | `false` | If set to `true`, the relationship will be set to `%Ash.ForbiddenField{}` if its query produces a forbidden error. |
| [`temporal_keys`](#relationships-belongs_to_versioned-temporal_keys){: #relationships-belongs_to_versioned-temporal_keys } | `{atom, atom}` |  | For relationships involving temporal resources, the `{source, destination}` period attributes (e.g. `{:valid_at, :valid_at}`). Use `nil` for a non-temporal side (`{nil, :valid_at}` / `{:valid_at, nil}`). When both are set, a `range_overlaps(parent(source), destination)` filter is added to the relationship, alongside its usual attribute join. See the `temporal` section of `Ash.Resource.Dsl`. |


### relationships.belongs_to_versioned.filter
```elixir
filter filter
```


Applies a filter. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*.


### Examples
```
filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-belongs_to_versioned-filter-filter){: #relationships-belongs_to_versioned-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |


### Introspection

Target: `Ash.Resource.Dsl.Filter`


### Introspection

Target: `Ash.Resource.Relationships.BelongsTo`


### relationships.has_one_versioned
```elixir
has_one_versioned name, destination
```


Declares a `has_one` relationship to the latest version of a versioned resource.

Takes the same options as `has_one`.


### Nested DSLs
 * [filter](#relationships-has_one_versioned-filter)


### Examples
```
has_one_versioned :customer, MyApp.Customer, destination_attribute: :resource_id
```

```
has_one_versioned :profile, MyApp.Profile do
  source_attribute :resource_id
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-has_one_versioned-name){: #relationships-has_one_versioned-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-has_one_versioned-destination){: #relationships-has_one_versioned-destination } | `module` |  | The destination resource |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`manual`](#relationships-has_one_versioned-manual){: #relationships-has_one_versioned-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. Setting this will automatically set `no_attributes?` to `true`. |
| [`no_attributes?`](#relationships-has_one_versioned-no_attributes?){: #relationships-has_one_versioned-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/resources/relationships.md) for more. |
| [`through`](#relationships-has_one_versioned-through){: #relationships-has_one_versioned-through } | `atom \| list(atom)` |  | A list of relationship names to traverse. The result will be the first record reachable by following the relationships in order. |
| [`allow_nil?`](#relationships-has_one_versioned-allow_nil?){: #relationships-has_one_versioned-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_versioned-from_many?){: #relationships-has_one_versioned-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. |
| [`offset`](#relationships-has_one_versioned-offset){: #relationships-has_one_versioned-offset } | `non_neg_integer` |  | An offset to skip entries when loading the relationship. Implies `from_many?: true`. |
| [`description`](#relationships-has_one_versioned-description){: #relationships-has_one_versioned-description } | `String.t` |  | An optional description for the relationship |
| [`destination_attribute`](#relationships-has_one_versioned-destination_attribute){: #relationships-has_one_versioned-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_versioned-validate_destination_attribute?){: #relationships-has_one_versioned-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource |
| [`source_attribute`](#relationships-has_one_versioned-source_attribute){: #relationships-has_one_versioned-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. |
| [`relationship_context`](#relationships-has_one_versioned-relationship_context){: #relationships-has_one_versioned-relationship_context } | `any` |  | Context to be set on any queries or changesets generated for managing or querying this relationship. |
| [`public?`](#relationships-has_one_versioned-public?){: #relationships-has_one_versioned-public? } | `boolean` | `false` | Whether or not the relationship will appear in public interfaces |
| [`not_found_message`](#relationships-has_one_versioned-not_found_message){: #relationships-has_one_versioned-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_versioned-writable?){: #relationships-has_one_versioned-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. |
| [`read_action`](#relationships-has_one_versioned-read_action){: #relationships-has_one_versioned-read_action } | `atom` | `:__ash_versioned_read__` | The read action on the destination resource used when loading data and filtering. Defaults to `:__ash_versioned_read__`, generated on every versioned resource, which returns the latest version of each record whether or not it is archived. |
| [`read_action_arguments`](#relationships-has_one_versioned-read_action_arguments){: #relationships-has_one_versioned-read_action_arguments } | `map` | `%{}` | Arguments to pass to the configured `read_action` when loading data and filtering. Arguments provided explicitly when loading the relationship take precedence over these arguments. |
| [`domain`](#relationships-has_one_versioned-domain){: #relationships-has_one_versioned-domain } | `atom` |  | The domain module to use when working with the related entity. |
| [`filterable?`](#relationships-has_one_versioned-filterable?){: #relationships-has_one_versioned-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. |
| [`sortable?`](#relationships-has_one_versioned-sortable?){: #relationships-has_one_versioned-sortable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in sorts. |
| [`sort`](#relationships-has_one_versioned-sort){: #relationships-has_one_versioned-sort } | `any` |  | A sort statement to be applied when loading the relationship. |
| [`default_sort`](#relationships-has_one_versioned-default_sort){: #relationships-has_one_versioned-default_sort } | `any` |  | A default sort statement to be applied when loading the relationship. |
| [`could_be_related_at_creation?`](#relationships-has_one_versioned-could_be_related_at_creation?){: #relationships-has_one_versioned-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. |
| [`violation_message`](#relationships-has_one_versioned-violation_message){: #relationships-has_one_versioned-violation_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on destroy. |
| [`authorize_read_with`](#relationships-has_one_versioned-authorize_read_with){: #relationships-has_one_versioned-authorize_read_with } | `:error \| :filter` |  | If set to `:error`, any authorization filter added to the relationship will result in an error if any record matches the filter in the database. |
| [`allow_forbidden_field?`](#relationships-has_one_versioned-allow_forbidden_field?){: #relationships-has_one_versioned-allow_forbidden_field? } | `boolean` | `false` | If set to `true`, the relationship will be set to `%Ash.ForbiddenField{}` if its query produces a forbidden error. |
| [`temporal_keys`](#relationships-has_one_versioned-temporal_keys){: #relationships-has_one_versioned-temporal_keys } | `{atom, atom}` |  | For relationships involving temporal resources, the `{source, destination}` period attributes (e.g. `{:valid_at, :valid_at}`). Use `nil` for a non-temporal side (`{nil, :valid_at}` / `{:valid_at, nil}`). When both are set, a `range_overlaps(parent(source), destination)` filter is added to the relationship, alongside its usual attribute join. See the `temporal` section of `Ash.Resource.Dsl`. |


### relationships.has_one_versioned.filter
```elixir
filter filter
```


Applies a filter. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*.


### Examples
```
filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-has_one_versioned-filter-filter){: #relationships-has_one_versioned-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |


### Introspection

Target: `Ash.Resource.Dsl.Filter`


### Introspection

Target: `Ash.Resource.Relationships.HasOne`


### relationships.has_many_versioned
```elixir
has_many_versioned name, destination
```


Declares a `has_many` relationship to the latest versions of a versioned resource.

Takes the same options as `has_many`.


### Nested DSLs
 * [filter](#relationships-has_many_versioned-filter)


### Examples
```
has_many_versioned :tasks, MyApp.Task
```

```
has_many_versioned :tasks, MyApp.Task do
  source_attribute :resource_id
  filter expr(archived == false)
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#relationships-has_many_versioned-name){: #relationships-has_many_versioned-name } | `atom` |  | The name of the relationship |
| [`destination`](#relationships-has_many_versioned-destination){: #relationships-has_many_versioned-destination } | `module` |  | The destination resource |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`manual`](#relationships-has_many_versioned-manual){: #relationships-has_many_versioned-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. Setting this will automatically set `no_attributes?` to `true`. |
| [`no_attributes?`](#relationships-has_many_versioned-no_attributes?){: #relationships-has_many_versioned-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/resources/relationships.md) for more. |
| [`through`](#relationships-has_many_versioned-through){: #relationships-has_many_versioned-through } | `atom \| list(atom)` |  | A list of relationship names to traverse. The result will be all records reachable by following the relationships in order. For example, `through: [:classrooms, :teachers]` would load all teachers from all classrooms. |
| [`limit`](#relationships-has_many_versioned-limit){: #relationships-has_many_versioned-limit } | `integer` |  | An integer to limit entries from loaded relationship. |
| [`offset`](#relationships-has_many_versioned-offset){: #relationships-has_many_versioned-offset } | `non_neg_integer` |  | An offset to skip entries when loading the relationship. |
| [`description`](#relationships-has_many_versioned-description){: #relationships-has_many_versioned-description } | `String.t` |  | An optional description for the relationship |
| [`destination_attribute`](#relationships-has_many_versioned-destination_attribute){: #relationships-has_many_versioned-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_versioned-validate_destination_attribute?){: #relationships-has_many_versioned-validate_destination_attribute? } | `boolean` | `true` | Whether or not to validate that the destination field exists on the destination resource |
| [`source_attribute`](#relationships-has_many_versioned-source_attribute){: #relationships-has_many_versioned-source_attribute } | `atom` | `:id` | The field on this resource that should match the `destination_attribute` on the related resource. |
| [`relationship_context`](#relationships-has_many_versioned-relationship_context){: #relationships-has_many_versioned-relationship_context } | `any` |  | Context to be set on any queries or changesets generated for managing or querying this relationship. |
| [`public?`](#relationships-has_many_versioned-public?){: #relationships-has_many_versioned-public? } | `boolean` | `false` | Whether or not the relationship will appear in public interfaces |
| [`not_found_message`](#relationships-has_many_versioned-not_found_message){: #relationships-has_many_versioned-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_versioned-writable?){: #relationships-has_many_versioned-writable? } | `boolean` | `true` | Whether or not the relationship may be managed. |
| [`read_action`](#relationships-has_many_versioned-read_action){: #relationships-has_many_versioned-read_action } | `atom` | `:__ash_versioned_read__` | The read action on the destination resource used when loading data and filtering. Defaults to `:__ash_versioned_read__`, generated on every versioned resource, which returns the latest version of each record whether or not it is archived. |
| [`read_action_arguments`](#relationships-has_many_versioned-read_action_arguments){: #relationships-has_many_versioned-read_action_arguments } | `map` | `%{}` | Arguments to pass to the configured `read_action` when loading data and filtering. Arguments provided explicitly when loading the relationship take precedence over these arguments. |
| [`domain`](#relationships-has_many_versioned-domain){: #relationships-has_many_versioned-domain } | `atom` |  | The domain module to use when working with the related entity. |
| [`filterable?`](#relationships-has_many_versioned-filterable?){: #relationships-has_many_versioned-filterable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in filters. |
| [`sortable?`](#relationships-has_many_versioned-sortable?){: #relationships-has_many_versioned-sortable? } | `boolean` | `true` | If set to `false`, the relationship will not be usable in sorts. |
| [`sort`](#relationships-has_many_versioned-sort){: #relationships-has_many_versioned-sort } | `any` |  | A sort statement to be applied when loading the relationship. |
| [`default_sort`](#relationships-has_many_versioned-default_sort){: #relationships-has_many_versioned-default_sort } | `any` |  | A default sort statement to be applied when loading the relationship. |
| [`could_be_related_at_creation?`](#relationships-has_many_versioned-could_be_related_at_creation?){: #relationships-has_many_versioned-could_be_related_at_creation? } | `boolean` | `false` | Whether or not related values may exist for this relationship at creation. |
| [`violation_message`](#relationships-has_many_versioned-violation_message){: #relationships-has_many_versioned-violation_message } | `String.t` |  | A message to show if there is a conflict with this relationship in the database on destroy. |
| [`authorize_read_with`](#relationships-has_many_versioned-authorize_read_with){: #relationships-has_many_versioned-authorize_read_with } | `:error \| :filter` |  | If set to `:error`, any authorization filter added to the relationship will result in an error if any record matches the filter in the database. |
| [`allow_forbidden_field?`](#relationships-has_many_versioned-allow_forbidden_field?){: #relationships-has_many_versioned-allow_forbidden_field? } | `boolean` | `false` | If set to `true`, the relationship will be set to `%Ash.ForbiddenField{}` if its query produces a forbidden error. |
| [`temporal_keys`](#relationships-has_many_versioned-temporal_keys){: #relationships-has_many_versioned-temporal_keys } | `{atom, atom}` |  | For relationships involving temporal resources, the `{source, destination}` period attributes (e.g. `{:valid_at, :valid_at}`). Use `nil` for a non-temporal side (`{nil, :valid_at}` / `{:valid_at, nil}`). When both are set, a `range_overlaps(parent(source), destination)` filter is added to the relationship, alongside its usual attribute join. See the `temporal` section of `Ash.Resource.Dsl`. |


### relationships.has_many_versioned.filter
```elixir
filter filter
```


Applies a filter. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*.


### Examples
```
filter expr(first_name == "fred")
filter expr(last_name == "weasley" and magician == true)

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`filter`](#relationships-has_many_versioned-filter-filter){: #relationships-has_many_versioned-filter-filter .spark-required} | `any` |  | The filter to apply. Can use `^arg/1`, `^context/1` and `^actor/1` templates. Multiple filters are combined with *and*. |


### Introspection

Target: `Ash.Resource.Dsl.Filter`


### Introspection

Target: `Ash.Resource.Relationships.HasMany`


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