Relations

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.

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	Judge a document with the document it points at

Both directions share the rest:

A relation is a key under related in the judgment’s context recipe, 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.

Get started

Before you build

Concepts

Guides

Engines

Reference