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
.