Relations

Reading across a reference

In GraphQL a reference resolves to the target record's own type, so you select the related fields inline. A field can be limited to the models it may point at. If it admits two or more, it returns a union that you read with inline fragments. On the SDK's data client relations are opt-in: ask for them with include, which nests to three levels.

Within a request, references to records of the same model are fetched together in batches. By default a query can nest 24 levels deep.

Filtering and writing

A list query can filter through a reference using the referenced model's own filter, for example posts by the author with a given natural key. A write connects a reference to a record by that record's natural key, or disconnects it to clear it.

Relationship kinds

A plain reference is structural and grants no access to the record it points at. A read association changes that for reads: whoever can read the referenced record can read the one that refers to it, across one hop. A composition makes the child owned by its parent, so access and deletes cascade from parent to child, and it is always single-valued. The fourth kind turns a model into a tree, described under hierarchies.

Reverse traversal

Name an inverse on the reference and the target model gains a field that lists the records pointing at it. For a composition that field is a plain list. For an association it is a paginated connection taking the same filter, sort and paging arguments as the model's list query.