> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Relations

> How a judgment reads other documents: the ones that point at it, or the one it points at.

A relation lets a judgment read documents other than the one it judges. Documents point at each other through an ordinary attribute that holds another document's `id`, and a relation follows that pointer in one of two directions.

```mermaid theme={null}
flowchart LR
  subgraph many["Documents that point at the judged document"]
    t1["ticket"] -- "attributes.account_id" --> a["account (judged)"]
    t2["ticket"] --> a
    i1["invoice"] --> a
  end
  subgraph one["The document the judged document points at"]
    l1["order line (judged)"] -- "attributes.product_id" --> p["product"]
    l2["order line (judged)"] --> p
    l3["order line (judged)"] --> p
  end
```

* **Documents that point at the judged document** (many to one). An account read with its tickets and invoices, a user with their posts, a conversation with its messages. Each related document carries the judged document's id.
* **The document the judged document points at** (one to many when it changes). An order line read with its product, a message with its conversation. The judged document carries the id of its **referenced document**, and many judged documents can share one.

|                                          | Documents that point at it                                                                  | The document it points at                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `join`                                   | `{"theirs": "attributes.<name>", "mine": "id"}`                                             | `{"theirs": "id", "mine": "attributes.<name>"}`                                                          |
| Who holds the pointer                    | each related document                                                                       | the judged document                                                                                      |
| What the relation reads                  | the newest created, bounded by `last_n`, `window` or both, at most 1,000                    | at most one document                                                                                     |
| What a write to the other side re-judges | the one judged document it points at, once its writes settle (the debounce and its ceiling) | every judged document that points at it and is inside the re-judge scope: a **fan-out**                  |
| What decides the cost                    | how often related documents are written                                                     | changes to what the relation shows × judged documents in scope                                           |
| What you see before paying               | a replay estimate of the monthly cost, before it runs `on_change`                           | the same replay estimate, which cannot count fan-out, and an estimate for each fan-out above `job_above` |
| Guide                                    | [Judge a document with its related documents](/guides/related-documents)                    | [Judge a document with the document it points at](/guides/referenced-document)                           |

Both directions share the rest:

* A relation is a key under `related` in the judgment's [context recipe](/guides/context-recipes#related-documents), with `match` to pick the documents it reads and `fields`, `aggregate` or both to say what the engine sees. A judgment has at most 4.
* Each attribute that relations join on needs a reference index, built by a `reference_index` job when a judgment first uses it. A namespace has at most 3, and an attribute used in both directions is one index.
* An answer carries a `watermark`, the log position its context was read at, and its evaluation lists `related_documents`: every document the context read, with its revision.
* A write to another document that changes nothing a relation shows re-judges nothing and is not billed.
* Related documents live in the same namespace as the judged document.

Parts of the API reference call a judgment with relations an entity judgment, and its replay estimate counts the documents it applies to as `entities`.