From fea3130985ddcc07916da0e7a49e9d0181afc503 Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 15 May 2026 16:31:20 +0100 Subject: [PATCH] vault backup: 2026-05-15 16:31:20 --- 99 Daily/2026-05-15.md | 1 + .../production__preventing-abuse.md | 0 raw/{ => _processed}/queries__depth.md | 0 wiki/_master-index.md | 2 +- wiki/payloadcms/_index.md | 1 + wiki/payloadcms/queries-depth.md | 100 ++++++++++++++++++ 6 files changed, 103 insertions(+), 1 deletion(-) rename raw/{ => _processed}/production__preventing-abuse.md (100%) rename raw/{ => _processed}/queries__depth.md (100%) create mode 100644 wiki/payloadcms/queries-depth.md diff --git a/99 Daily/2026-05-15.md b/99 Daily/2026-05-15.md index 391b91e..fcf9d2b 100644 --- a/99 Daily/2026-05-15.md +++ b/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` diff --git a/raw/production__preventing-abuse.md b/raw/_processed/production__preventing-abuse.md similarity index 100% rename from raw/production__preventing-abuse.md rename to raw/_processed/production__preventing-abuse.md diff --git a/raw/queries__depth.md b/raw/_processed/queries__depth.md similarity index 100% rename from raw/queries__depth.md rename to raw/_processed/queries__depth.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index aecce24..0aafae3 100644 --- a/wiki/_master-index.md +++ b/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 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 5a75462..fcce932 100644 --- a/wiki/payloadcms/_index.md +++ b/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 | diff --git a/wiki/payloadcms/queries-depth.md b/wiki/payloadcms/queries-depth.md new file mode 100644 index 0000000..8c9cf97 --- /dev/null +++ b/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