---
title: "Queries — Depth (Relationship Population)"
aliases: [payload-depth, relationship-depth, populate-depth]
tags: [payloadcms, queries, relationships, performance, api]
sources: [raw/queries__depth.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

`depth` controls how many levels of related Documents are auto-populated (expanded from ID to full object) in API responses. Applies to [[wiki/payloadcms/local-api|Local API]] and [[wiki/payloadcms/rest-api|REST API]] — **not GraphQL** (GraphQL uses query shape instead).

---

## Depth Levels

| depth | Result |
|-------|--------|
| `0` | Related docs returned as IDs only: `"author": "5f7dd..."` |
| `1` | Immediate relations expanded: `"author": { "id": "...", "name": "John" }` |
| `2` | Relations-of-relations expanded (default) |
| N | N levels deep |

---

## Setting Depth

### Local API
```ts
const posts = await payload.find({
  collection: 'posts',
  depth: 2,
})
// Also works with findGlobal
```

### REST API
```
GET /api/posts?depth=2
GET /api/globals/header?depth=1
```

---

## Default & Max Depth

### Application-level default
```ts
// payload.config.ts
export default buildConfig({
  defaultDepth: 1,   // fallback when no depth is specified (built-in default: 2)
})
```

### Field-level max cap
```js
{
  name: 'author',
  type: 'relationship',
  relationTo: 'users',
  maxDepth: 2,   // request depth cannot exceed this, regardless of API param
}
```
Also available on [[wiki/payloadcms/fields-upload|Upload Field]].

---

## Key Takeaways

- Default depth is **2** unless overridden via `defaultDepth` in root config.
- `maxDepth` on a field acts as a hard ceiling — it overrides whatever depth the API request asks for.
- Depth **0** returns IDs only; depth **1** is cheapest for populated data.
- Higher depth = more DB joins/lookups + larger response payload — tune for performance.
- GraphQL ignores `depth` entirely; population is controlled by the query shape.
- `findGlobal` in the Local API and `/api/globals/*` in REST both respect `depth` the same way.

---

## Performance Notes

- Excessive depth on large collections with many relationships can cause significant DB load.
- See [[wiki/payloadcms/performance-overview|Performance Optimization]] for general DB tuning.
- Use `depth: 0` + manual lookups when you only need IDs (e.g., foreign-key joins in server code).

---

## Related

- [[wiki/payloadcms/queries|Queries — Overview]] — where, sort, pagination, select/populate
- [[wiki/payloadcms/fields-relationship|Relationship Field]] — `maxDepth`, `filterOptions`, bi-directional
- [[wiki/payloadcms/fields-upload|Upload Field]] — also supports `maxDepth`
- [[wiki/payloadcms/local-api|Local API]] — `payload.find()` options
- [[wiki/payloadcms/rest-api|REST API]] — query param reference

---

## Sources

- `raw/queries__depth.md` — official Payload CMS depth docs
