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:

    Expand diagram

    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.