Basics - Expanding relations - Docs

Overview

PocketBase collections allow you to expand record relation fields directly in the returned response without making additional requests by just using the expand query parameter: ?expand=relField1,relField2.subRelField

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

For example, consider the following simple collections structure:

To list all comments with their user relation expanded, we can do the following:

GET /api/collections/comments/records?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"
                }
            }
        },
        ...
    ]
}

Indirect expand

We can also do indirect 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?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 indirect expand has some caveats:

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