obsidian/wiki/payloadcms/queries-depth.md

title	aliases	tags	sources	created	updated
Queries — Depth (Relationship Population)	payload-depth relationship-depth populate-depth	payloadcms queries relationships performance api	raw/queries__depth.md	2026-05-15	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 and wiki/payloadcms/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

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

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

Field-level max cap

{
  name: 'author',
  type: 'relationship',
  relationTo: 'users',
  maxDepth: 2,   // request depth cannot exceed this, regardless of API param
}

Also available on wiki/payloadcms/fields-upload.

---

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 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 — where, sort, pagination, select/populate
• wiki/payloadcms/fields-relationship — maxDepth, filterOptions, bi-directional
• wiki/payloadcms/fields-upload — also supports maxDepth
• wiki/payloadcms/local-api — payload.find() options
• wiki/payloadcms/rest-api — query param reference

---

Sources

• raw/queries__depth.md — official Payload CMS depth docs