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. Requires relationTo to specify the target collection. Use hasMany for multiple relationships.

export type RelationshipField = TypedField<"relationship", string | string[]> & {
  /** Target collection slug (required for relationship fields). */
  relationTo: string;
};