Relation field

Store references to records from other collections

The relation field stores references to records in other collections. It supports both single and multiple record references, with validation to ensure referenced records exist.

Configuration options

collectionId · string · required

The ID of the related collection. This cannot be changed after the field is created.

cascadeDelete · bool · default: "false"

When true, deletes the current record if all its linked relations are deleted.

minSelect · int · default: "0"

Minimum number of required relation records. Set to 0 for no minimum limit.

maxSelect · int · default: "1"

Maximum number of relation records that can be linked. Set to 1 (or less) for single relation mode. Set to > 1 for multiple relations mode.

required · bool · default: "false"

When true, requires at least one relation to be set.

Validation rules

The relation field validates:

• Collection exists: Referenced collection must exist and be accessible
• Records exist: All referenced record IDs must exist in the related collection
• Min select: If set, minimum number of relations must be met
• Max select: Number of relations cannot exceed the maximum
• Required: If enabled, at least one relation must be set

The collectionId cannot be changed after the field is created to prevent breaking existing data relationships.

Single vs multiple relations

The field behavior changes based on maxSelect:

• maxSelect <= 1: Single relation mode (value is a record ID string)
• maxSelect > 1: Multiple relations mode (value is an array of record IDs)

Special setter modifiers

The relation field supports modifiers for manipulating relations:

Append relations

// Add relations to the end
record.Set("categories+", []string{"id1", "id2"})
// Before: ["oldId1", "oldId2"]
// After:  ["oldId1", "oldId2", "id1", "id2"]

Go examples

Single relation

import "github.com/pocketbase/pocketbase/core"

field := &core.RelationField{
    Name:         "author",
    Required:     true,
    MaxSelect:    1,
    CollectionId: "users_collection_id",
}

collection.Fields.Add(field)

// Set single relation
record.Set("author", "user_record_id")

Multiple relations

field := &core.RelationField{
    Name:         "categories",
    Required:     false,
    MaxSelect:    5,
    CollectionId: "categories_collection_id",
}

collection.Fields.Add(field)

// Set multiple relations
record.Set("categories", []string{
    "category_id_1",
    "category_id_2",
    "category_id_3",
})

With min/max constraints

field := &core.RelationField{
    Name:         "tags",
    Required:     true,
    MinSelect:    1,
    MaxSelect:    10,
    CollectionId: "tags_collection_id",
}

collection.Fields.Add(field)

// Must have at least 1, max 10 tags
record.Set("tags", []string{"tag1", "tag2", "tag3"})

With cascade delete

field := &core.RelationField{
    Name:          "project",
    Required:      true,
    MaxSelect:     1,
    CollectionId:  "projects_collection_id",
    CascadeDelete: true, // Delete task when project is deleted
}

collection.Fields.Add(field)

record.Set("project", "project_id")

Database column type

The column type varies based on whether it’s single or multiple relations:

Single relation (maxSelect <= 1)

TEXT DEFAULT '' NOT NULL

Common patterns

One-to-many (author -> articles)

// In articles collection
field := &core.RelationField{
    Name:         "author",
    Required:     true,
    MaxSelect:    1,
    CollectionId: "users",
}

Expand relations in API

When querying records with relations, use the expand parameter to include related record data:

Single relation expand

const record = await pb.collection('articles').getOne('RECORD_ID', {
    expand: 'author'
});

// Access expanded author
console.log(record.expand.author.name);

View collection restrictions

Only view collections can have relations to other view collections. Regular collections cannot reference view collections.

Best practices

• Use descriptive relation field names that indicate the relationship (e.g., author, categories, assignedTo)
• Set appropriate minSelect and maxSelect constraints for data integrity
• Use cascadeDelete carefully as it can lead to unintended data loss
• Consider indexing relation fields for better query performance
• Use the expand parameter when fetching records to avoid N+1 queries
• Remember that changing collectionId is not allowed after creation

Zero value

• Single relation: Empty string ""
• Multiple relations: Empty array []