-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
840e075
commit fac5425
Showing
13 changed files
with
218 additions
and
241 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -129,125 +129,7 @@ If you don't use GraphQL, you can delete those files! But if you do, you'll find | |
|
|
||
| ## Depth | ||
|
|
||
| <Banner type="info"> | ||
| "Depth" gives you control over how many levels down related documents should be automatically | ||
| populated when retrieved. | ||
| </Banner> | ||
|
|
||
| You can specify population `depth` via query parameter in the REST API and by an option in the local API. _Depth has no effect in the GraphQL API, because there, depth is based on the shape of your queries._ | ||
| It is also possible to limit the depth for specific `relation` and `upload` fields using the `maxDepth` property in your configuration. | ||
| **For example, let's look at the following Collections:** `departments`, `users`, `posts` | ||
|
|
||
| ``` | ||
| // type: 'relationship' fields are equal to 1 depth level | ||
| { | ||
| slug: 'posts', | ||
| fields: [ | ||
| { | ||
| name: 'title', | ||
| type: 'text', | ||
| }, | ||
| { | ||
| name: 'author', | ||
| label: 'Post Author', | ||
| type: 'relationship', | ||
| relationTo: 'users', | ||
| } | ||
| ] | ||
| } | ||
| { | ||
| slug: 'users', | ||
| fields: [ | ||
| { | ||
| name: 'email', | ||
| type: 'email', | ||
| }, | ||
| { | ||
| name: 'department' | ||
| type: 'relationship', | ||
| relationTo: 'departments' | ||
| } | ||
| ] | ||
| } | ||
| { | ||
| slug: 'departments', | ||
| fields: [ | ||
| { | ||
| name: 'name' | ||
| type: 'text', | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| If you were to query the Posts endpoint at, say, `http://localhost:3000/api/posts?depth=1`, you will retrieve Posts with populations one level deep. This depth parameter can be thought of as N, where N is the number of levels you want to populate. To populate one level further, you would simply specify N+1 as the depth. A returned result may look like the following: | ||
|
|
||
| ``` | ||
| // ?depth=1 | ||
| { | ||
| id: '5ae8f9bde69e394e717c8832', | ||
| title: 'This post sucks', | ||
| author: { | ||
| id: '5f7dd05cd50d4005f8bcab17', | ||
| email: '[email protected]', | ||
| department: '5e3ca05cd50d4005f8bdab15' | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Notice how the `user.author` is fully populated, but `user.author.department` is left as a document ID? That's because the User collection counted as the first level of `depth` and got populated—but then prevented any further populations from taking place. | ||
|
|
||
| To populate `user.author.department` in it's entirety you could specify `?depth=2` or _higher_. | ||
|
|
||
| ``` | ||
| // ?depth=2 | ||
| { | ||
| id: '5ae8f9bde69e394e717c8832', | ||
| title: 'This post sucks', | ||
| author: { | ||
| id: '5f7dd05cd50d4005f8bcab17', | ||
| email: '[email protected]', | ||
| department: { | ||
| id: '5e3ca05cd50d4005f8bdab15', | ||
| name: 'Marvel' | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Field-level max depth | ||
|
|
||
| Fields like relationships or uploads can have a `maxDepth` property that limits the depth of the population for that field. Here are some examples: | ||
|
|
||
| Depth: 10 | ||
| Current depth when field is accessed: 1 | ||
| `maxDepth`: undefined | ||
|
|
||
| In this case, the field would be populated to 9 levels of population. | ||
|
|
||
| Depth: 10 | ||
| Current depth when field is accessed: 0 | ||
| `maxDepth`: 2 | ||
|
|
||
| In this case, the field would be populated to 2 levels of population, despite there being a remaining depth of 8. | ||
|
|
||
| Depth: 10 | ||
| Current depth when field is accessed: 2 | ||
| `maxDepth`: 1 | ||
|
|
||
| In this case, the field would not be populated, as the current depth (2) has exceeded the `maxDepth` for this field (1). | ||
|
|
||
| <Banner type="warning"> | ||
| <strong>Note:</strong> | ||
| <br /> | ||
| When access control on collections prevents relationship fields from populating, the API response | ||
| will contain the relationship id instead of the full document. | ||
| </Banner> | ||
| Documents can be related to other Documents through a concept called "relationships". When you query a Document, you can specify these relationships are populated. [More details](../queries/depth). | ||
|
|
||
| ## Plugins | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| --- | ||
| title: Depth | ||
| label: Depth | ||
| order: 30 | ||
| desc: Payload depth determines how many levels down related documents should be automatically populated when retrieved. | ||
| keywords: query, documents, pagination, documentation, Content Management System, cms, headless, javascript, node, react, nextjs | ||
| --- | ||
|
|
||
| Documents in Payload can have relationships to other Documents. This is true for both [Collections](../configuration/collections) as well as [Globals](../configuration/globals). When you query a Document, you can specify the depth at which to populate any of its related Documents as full objects, or simply return their Document IDs. | ||
|
|
||
| Depth will optimize the performance of your application by limiting the number of queries made to the database, and significantly reducing the amount of data returned. Since Documents can be infinitely nested or recursively related, it's important to be able to control how deep your API populate. | ||
|
|
||
| When you specify a `depth` of `0`, for example, the API response might look like this: | ||
|
|
||
| ```json | ||
| { | ||
| "id": "5ae8f9bde69e394e717c8832", | ||
| "title": "This is a great post", | ||
| "author": "5f7dd05cd50d4005f8bcab17" | ||
| } | ||
| ``` | ||
|
|
||
| But with a `depth` of `1`, the response might look like this: | ||
|
|
||
| ```json | ||
| { | ||
| "id": "5ae8f9bde69e394e717c8832", | ||
| "title": "This is a great post", | ||
| "author": { | ||
| "id": "5f7dd05cd50d4005f8bcab17", | ||
| "name": "John Doe" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| <Banner type="warning"> | ||
| <strong>Important:</strong> | ||
| Depth has no effect in the [GraphQL API](../graphql/overview), because there, depth is based on the shape of your queries. | ||
| </Banner> | ||
|
|
||
| ## Local API | ||
|
|
||
| To specify depth in the [Local API](../local-api/overview), you can use the `depth` option in your query: | ||
|
|
||
| ```ts | ||
| const getPosts = async () => { | ||
| const posts = await payload.find({ | ||
| collection: 'posts', | ||
| depth: 2, // highlight-line | ||
| }) | ||
|
|
||
| return posts | ||
| } | ||
| ``` | ||
|
|
||
| <Banner type="info"> | ||
| <strong>Reminder:</strong> | ||
| This is the same for [Globals](../configuration/globals) using the `findGlobal` operation. | ||
| </Banner> | ||
|
|
||
| ## REST API | ||
|
|
||
| To specify depth in the [REST API](../rest-api/overview), you can use the `depth` parameter in your query: | ||
|
|
||
| ```ts | ||
| fetch('https://localhost:3000/api/posts?depth=2') // highlight-line | ||
| .then((response) => response.json()) | ||
| .then((data) => console.log(data)) | ||
| ``` | ||
|
|
||
| <Banner type="info"> | ||
| <strong>Reminder:</strong> | ||
| This is the same for [Globals](../configuration/globals) using the `/api/globals` endpoint. | ||
| </Banner> | ||
|
|
||
| ## Max Depth | ||
|
|
||
| Fields like the [Relationship Field](../fields/relationship) or the [Upload Field](../fields/upload) can also set a maximum depth. If exceeded, this will limit the population depth regardless of the depth of the request. | ||
|
|
||
| To set a max depth for a field, use the `maxDepth` property in your field configuration: | ||
|
|
||
| ```js | ||
| { | ||
| slug: 'posts', | ||
| fields: [ | ||
| { | ||
| name: 'author', | ||
| type: 'relationship', | ||
| relationTo: 'users', | ||
| maxDepth: 2, // highlight-line | ||
| } | ||
| ] | ||
| } | ||
| ``` |
Oops, something went wrong.