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.

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:

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

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

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

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:

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: