Relationship

The relationship field links a document to one or more documents in another collection. Use it for authors on a post, products in an order, or any connection between content types.

defineRelationshipField({
  name: 'author',
  label: 'Author',
  relationTo: 'users',
})

relationTo names the collection you're linking to. By default the field stores a single reference; set hasMany: true to store an ordered list of them:

defineRelationshipField({
  name: 'categories',
  label: 'Categories',
  relationTo: 'categories',
  hasMany: true,
})

What the API returns

A relationship stores the related document's ID — a single ID, or an array of IDs when hasMany is set. How much of the related document you get back depends on the read depth. By default, reads use a depth of 1, which hydrates the immediate related documents one level deep; request depth: 0 for just the IDs, or a higher depth to follow relationships further. Set the depth when you read through the SDK or REST API so a list view can stay lean while a detail view pulls in what it needs.

To surface the reverse direction — the posts that point at an author, say — without storing the link on both sides, use a Join.

Generated reference

The contract below is generated from the public @dyrected/core exports by @dyrected/knowledge, so it stays in sync with the package. See Fields for the shared field options every type accepts.

RelationshipField

A reference to one or more documents in another collection, stored as an ID or array of IDs. Use relationTo to name the target and hasMany for multiple.

export type RelationshipField = TypedField<"relationship", string | string[]>;