277448d9c0
Payload is designed with performance in mind, but its customizability means that there are many ways to configure your app that can impact performance. While Payload provides several features and best practices to help you optimize your app's specific performance needs, these are not currently well surfaced and can be obscure. Now: - A high-level performance doc now exists at `/docs/performance` - There's a new section on performance within the `/docs/queries` doc - There's a new section on performance within the `/docs/hooks` doc - There's a new section on performance within the `/docs/custom-components` doc This PR also: - Restructures and elaborates on the `/docs/queries/pagination` docs - Adds a new `/docs/database/indexing` doc - More --- - To see the specific tasks where the Asana app for GitHub is being used, see below: - https://app.asana.com/0/0/1210743577153856
121 lines
3.3 KiB
Plaintext
121 lines
3.3 KiB
Plaintext
---
|
|
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 either as full objects, or only their IDs.
|
|
|
|
Since Documents can be infinitely nested or recursively related, it's important to be able to control how deep your API populates. Depth can impact the performance of your queries by affecting the load on the database and the size of the response.
|
|
|
|
For example, when you specify a `depth` of `0`, 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">
|
|
**Important:** 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
|
|
import type { Payload } from 'payload'
|
|
|
|
const getPosts = async (payload: Payload) => {
|
|
const posts = await payload.find({
|
|
collection: 'posts',
|
|
// highlight-start
|
|
depth: 2,
|
|
// highlight-end
|
|
})
|
|
|
|
return posts
|
|
}
|
|
```
|
|
|
|
<Banner type="info">
|
|
**Reminder:** 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
|
|
// highlight-start
|
|
fetch('https://localhost:3000/api/posts?depth=2')
|
|
// highlight-end
|
|
.then((res) => res.json())
|
|
.then((data) => console.log(data))
|
|
```
|
|
|
|
<Banner type="info">
|
|
**Reminder:** This is the same for [Globals](../configuration/globals) using
|
|
the `/api/globals` endpoint.
|
|
</Banner>
|
|
|
|
## Default Depth
|
|
|
|
If no depth is specified in the request, Payload will use its default depth for all requests. By default, this is set to `2`.
|
|
|
|
To change the default depth on the application level, you can use the `defaultDepth` option in your root Payload config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload/config'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
// highlight-start
|
|
defaultDepth: 1,
|
|
// highlight-end
|
|
// ...
|
|
})
|
|
```
|
|
|
|
## 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 what the depth might be on 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',
|
|
// highlight-start
|
|
maxDepth: 2,
|
|
// highlight-end
|
|
}
|
|
]
|
|
}
|
|
```
|