# `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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*