Depth

Documents in Payload can have relationships to other Documents. This is true for both Collections as well as 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.

Depth will optimize the performance of your application by limiting the amount of processing made in 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 populates.

For example, when you specify a depth of 0, the API response might look like this:

1{
2  "id": "5ae8f9bde69e394e717c8832",
3  "title": "This is a great post",
4  "author": "5f7dd05cd50d4005f8bcab17"
5}

But with a depth of 1, the response might look like this:

1{
"id": "5ae8f9bde69e394e717c8832",
"title": "This is a great post",
"author": {
  "id": "5f7dd05cd50d4005f8bcab17",
  "name": "John Doe"
}
8}

Local API

To specify depth in the Local API, you can use the depth option in your query:

1import type { Payload } from 'payload'
2
3const getPosts = async (payload: Payload) => {
4  const posts = await payload.find({
5    collection: 'posts',
6    depth: 2, 
7  })
8
9  return posts
10}

REST API

To specify depth in the REST API, you can use the depth parameter in your query:

1fetch('https://localhost:3000/api/posts?depth=2') 
2  .then((res) => res.json())
3  .then((data) => console.log(data))

Max Depth

Fields like the Relationship Field or the Upload Field 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:

1{
slug: 'posts',
fields: [
  {
    name: 'author',
    type: 'relationship',
    relationTo: 'users',
    maxDepth: 2, 
  }
]
11}

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Depth

Local API

REST API

Max Depth

Select