vault backup: 2026-05-15 16:31:20

99 Daily/2026-05-15.md

@@ -83,3 +83,4 @@ tags: [daily]
 - 16:01 — session ended | `Shumiland`
 - 16:15 — session ended | `ai_leed`
 - 16:29 (1min) — session ended | `ai_leed`
+- 16:30 — session ended | `ai_leed`

wiki/_master-index.md

@@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 |
 | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 |
 | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 |
-| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 124 |
+| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 126 |
 
 | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 |
 | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 |

wiki/payloadcms/_index.md

@@ -126,3 +126,4 @@
 | [[wiki/payloadcms/plugin-stripe\|Stripe Plugin]] | Two-way Stripe↔Payload sync, webhook handlers, REST proxy (dev-only), `sync` auto-hooks, serverless `waitUntil` fix, `skipSync` loop prevention | raw/plugins__stripe.md | 2026-05-15 |
 | [[wiki/payloadcms/building-without-db-connection\|Building Without a DB Connection]] | Docker build fails when Next.js SSG calls Local API — two-phase `compile`/`generate` build modes, `force-dynamic` escape hatch, `NEXT_PUBLIC_` gotcha | raw/production__building-without-a-db-connection.md | 2026-05-15 |
 | [[wiki/payloadcms/production-preventing-abuse\|Production — Preventing API Abuse]] | Login rate limiting (maxLoginAttempts/lockTime), maxDepth, CSRF, CORS, GraphQL complexity limits, malicious file upload mitigation | raw/production__preventing-abuse.md | 2026-05-15 |
+| [[wiki/payloadcms/queries-depth\|Queries — Depth (Relationship Population)]] | depth=0 (IDs only) vs depth=N (full objects), defaultDepth config, field-level maxDepth cap, performance notes, GraphQL exception | raw/queries__depth.md | 2026-05-15 |

wiki/payloadcms/queries-depth.md

@@ -0,0 +1,100 @@
+---
+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