Relationship field

Link a document to an author, category, or other related documents.

Use field.Relationship to link one document to another, such as a post to its author. When you save, Ridu checks that the related document exists and that the current user can read it. Reads return its ID; request population to include the related document too.

In the admin

A populated Author relationship field in the Ridu admin referencing the documentation user.

The picker shows the target label; stored data contains a reference that can be populated on read.

Link to one or several documents

content/posts.go

field.Relationship("author", "users").
  Required().
  OnDelete(field.ReferenceDeleteRestrict)

A relationship to one document in one collection stores its document ID. Use field.Relationships("reviewers", "users") for an ordered list of users.

Use field.PolymorphicRelationship("subject", "posts", "media") when the selected document can come from more than one collection. Its value contains both relationTo and id to identify the collection and document. Use field.PolymorphicRelationships to select several such documents.

Configuration

Constructor or method	What it controls
`field.Relationship(name, collection)`	Stores one document ID from one target collection.
`field.Relationships(name, collection)`	Stores an ordered list of IDs from one target collection.
`field.PolymorphicRelationship(name, collections...)`	Stores one `{ relationTo, id }` reference from several allowed collections.
`field.PolymorphicRelationships(name, collections...)`	Stores an ordered list of polymorphic references.
`.Required()`	Requires one reference, or a non-empty list for plural fields.
`.FilterOptionRules(rules...)`	Narrows picker choices and server admission with finite query predicates.
`.OnDelete(field.ReferenceDeleteRestrict)` / `ReferenceDeleteNullify` / `ReferenceDeleteCascade`	Rejects a hard delete while referenced, clears or removes matching references, or deletes the referencing document too.
`.Index()` / `.Unique()`	Available on a singular, single-target relationship.
`.Localized()`	Stores the reference or list separately for each content locale.
`.Validate(...)`, `.LiveValidate(...)`, `.Access(...)`, `.Hooks(...)`	Adds application rules and lifecycle behavior.

Filter the available choices

content/posts.go

field.Relationship("reviewer", "users").
  FilterOptionRules(field.OptionFilter(
    "team", field.FilterEquals, "editorialTeam",
  ))

This picker shows users whose team matches the current document’s editorialTeam. The server checks the same rule when saving. Authors also need read access to the selected user.

Use OptionFilterValue to compare against a fixed value, or OptionFilterFor to apply a rule to a specific collection in a relationship that supports several collection types.

Choose what happens when a related document is deleted

ReferenceDeleteNullify clears an optional singular value or removes list members when the target is permanently deleted. ReferenceDeleteRestrict blocks that deletion while a current reference exists. ReferenceDeleteCascade deletes the referencing document as well, for owned data on a singular relationship. Required references default to restrict and cannot nullify. Version snapshots remain immutable. See delete behavior.

Filter by related documents

Filter a relationship to one document by its ID: { author: { equals: adaID } }, or in with several IDs. A list of documents is filtered by membership, so in matches when the list holds any of the IDs:

// Posts that list Ada or Grace among their reviewers.
query.In("reviewers", adaID, graceID)

// Posts whose subject is this post, whichever collection holds the ID.
query.In("subject", query.Reference("posts", postID))

A polymorphic relationship, single or a list, compares { relationTo, id } references, as the SDK and REST write them: { subject: { in: [{ relationTo: 'posts', id: postID }] } }. Wrap in in not to exclude documents. Equality, contains and ranges are rejected for lists and polymorphic relationships, and none of them can be sorted. See Filter by membership. The admin list offers is any of and is none of for these fields.

Read and translate relationships

Request populate through the Local API or SDK to read the related document. Population respects access rules, localization, and the requested depth limit. .Localized() lets each content locale select a different document.

Common mistakes

The target collection must be declared, and upload-only semantics belong in Upload.
Changing from one document to a list, or removing an allowed collection, requires migrating existing values.
Picker visibility never replaces authorization.
Use Join for the inverse view; do not duplicate both sides as manually synchronized ID lists.

See field.Relationship and the complete relationship and population guide.