Working with relations - Docs

Overview

Let's assume that we have the following collections structure:

The relation fields follow the same rules as any other collection field and can be set/modified by directly updating the field value - with a record id or array of ids , in case a multiple relation field is used.

Below is an example that shows creating a new posts record with 2 assigned tags.

import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

...

const post = await pb.collection('posts').create({
    'title': 'Lorem ipsum...',
    'tags':  ['TAG_ID1', 'TAG_ID2'],
});

import 'package:pocketbase/pocketbase.dart';

final pb = PocketBase('http://127.0.0.1:8090');

...

final post = await pb.collection('posts').create(body: {
    'title': 'Lorem ipsum...',
    'tags':  ['TAG_ID1', 'TAG_ID2'],
});

Append to multiple relation

To append a single or multiple relation id(s) to an existing value you can use the + field modifier:

import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

...

const post = await pb.collection('posts').update('POST_ID', {
    // append single tag
    'tags+': 'TAG_ID1',

    // append multiple tags at once
    'tags+': ['TAG_ID1', 'TAG_ID2'],
})

import 'package:pocketbase/pocketbase.dart';

final pb = PocketBase('http://127.0.0.1:8090');

...

final post = await pb.collection('posts').update('POST_ID', body: {
    // append single tag
    'tags+': 'TAG_ID1',

    // append multiple tags at once
    'tags+': ['TAG_ID1', 'TAG_ID2'],
})

Remove from multiple relation

To remove a single or multiple relation id(s) from an existing value you can use the - field modifier:

import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

...

const post = await pb.collection('posts').update('POST_ID', {
    // remove single tag
    'tags-': 'TAG_ID1',

    // remove multiple tags at once
    'tags-': ['TAG_ID1', 'TAG_ID2'],
})

import 'package:pocketbase/pocketbase.dart';

final pb = PocketBase('http://127.0.0.1:8090');

...

final post = await pb.collection('posts').update('POST_ID', body: {
    // remove single tag
    'tags-': 'TAG_ID1',

    // remove multiple tags at once
    'tags-': ['TAG_ID1', 'TAG_ID2'],
})

Expanding relations

You can also expand record relation fields directly in the returned response without making additional requests by using the expand query parameter, eg. ?expand=user,post.tags

Only the relations that the request client can View (aka. satisfies the relation collection's View API Rule) will be expanded.
Nested relations are supported via dot-notation and up to 6-levels depth.

For example, to list all comments with their user relation expanded, we can do the following:

// GET /api/collections/comments/records?perPage=30&expand=user
await pb.collection("comments").getList(1, 30, { expand: "user" })

// GET /api/collections/comments/records?perPage=30&expand=user
await pb.collection("comments").getList(perPage: 30, expand: "user")

{
    "page": 1,
    "perPage": 30,
    "totalPages": 1,
    "totalItems": 20,
    "items": [
        {
            "id": "lmPJt4Z9CkLW36z",
            "collectionId": "BHKW36mJl3ZPt6z",
            "collectionName": "comments",
            "created": "2022-01-01 01:00:00.456Z",
            "updated": "2022-01-01 02:15:00.456Z",
            "post": "WyAw4bDrvws6gGl",
            "user": "FtHAW9feB5rze7D",
            "message": "Example message...",
            "expand": {
                "user": {
                    "id": "FtHAW9feB5rze7D",
                    "collectionId": "srmAo0hLxEqYF7F",
                    "collectionName": "users",
                    "created": "2022-01-01 00:00:00.000Z",
                    "updated": "2022-01-01 00:00:00.000Z",
                    "username": "users54126",
                    "verified": false,
                    "emailVisibility": false,
                    "name": "John Doe"
                }
            }
        },
        ...
    ]
}

Back-relation expand

We can also do back-relation expansions - expand where the relation field is not in the main collection.

The following notation is used: ?expand=referenceCollection(relField)[.*]

For example, to list all posts each with their comments and users expanded, we can do the following:

// GET /api/collections/posts/records?perPage=30&expand=comments(post).user
await pb.collection("posts").getList(1, 30, { expand: "comments(post).user" })

// GET /api/collections/posts/records?perPage=30&expand=comments(post).user
await pb.collection("posts").getList(perPage: 30, expand: "comments(post).user")

{
    "page": 1,
    "perPage": 30,
    "totalPages": 2,
    "totalItems": 45,
    "items": [
        {
            "id": "WyAw4bDrvws6gGl",
            "collectionId": "1rAwHJatkTNCUIN",
            "collectionName": "posts",
            "created": "2022-01-01 01:00:00.456Z",
            "updated": "2022-01-01 02:15:00.456Z",
            "title": "Lorem ipsum dolor sit...",
            "expand": {
                "comments(post)": [
                    {
                        "id": "lmPJt4Z9CkLW36z",
                        "collectionId": "BHKW36mJl3ZPt6z",
                        "collectionName": "comments",
                        "created": "2022-01-01 01:00:00.456Z",
                        "updated": "2022-01-01 02:15:00.456Z",
                        "post": "WyAw4bDrvws6gGl",
                        "user": "FtHAW9feB5rze7D",
                        "message": "Example message...",
                        "expand": {
                            "user": {
                                "id": "FtHAW9feB5rze7D",
                                "collectionId": "srmAo0hLxEqYF7F",
                                "collectionName": "users",
                                "created": "2022-01-01 00:00:00.000Z",
                                "updated": "2022-01-01 00:00:00.000Z",
                                "username": "users54126",
                                "verified": false,
                                "emailVisibility": false,
                                "name": "John Doe"
                            }
                        }
                    },
                    ...
                ]
            }
        },
        ...
    ]
}

The back-relation expand has some caveats:

Currently only single relation fields can be back-relation expanded (aka. when "Max Select" field option is 1).
The "Unique" back-relation field option is used to determine whether an array or a single object should be expanded.
As a side effect of the nested expansion support, referencing the back-relation field itself is also allowed, eg. ?expand=comments(post).post.