documentdb-data-modeling

# Data Modeling — Azure DocumentDB Guiding principle: **"Data that is accessed together should be stored together."** Each rule follows the same shape — why it matters → incorrect example → correct example → references. ## Rules - [model-embed-vs-reference](model-embed-vs-reference.md) — Embed data accessed together; reference unbounded N-sides. - [model-16mb-limit](model-16mb-limit.md) — Stay well under the 16 MB BSON document limit; plan for steady-state growth. - [model-denormalize-reads](model-denormalize-reads.md) — Denormalize for read-heavy workloads; pre-compute aggregates to avoid `$lookup`. - [model-schema-versioning](model-schema-versioning.md) — Add a `schemaVersion` field and migrate documents lazily. - [model-large-field-split](model-large-field-split.md) — Split a large, low-compressibility field into a side collection keyed by `_id` to avoid the PostgreSQL TOAST detoast tax on scans. Companion tool: [`scripts/toast-split-advisor.sh`](../../scripts/toast-split-advisor.sh). ## Companion tool (analysis only) [`scripts/toast-split-advisor.sh`](../../scripts/toast-split-advisor.sh) measures heap vs TOAST bytes on a live local container and reports **where** a large field should be split out — it never moves data: ```bash bash scripts/toast-split-advisor.sh --db <name> [--json] ``` ## Decision framework | Relationship | Cardinality | Access pattern | Recommendation | |---|---|---|---| | One-to-One | 1:1 | Always together | Embed | | One-to-Few | 1:N (N < ~100) | Usually together | Embed array | | One-to-Many | 1:N (N > ~100) | Often separate | Reference | | Many-to-Many | M:N | Varies | Two-way reference or junction collection | See each rule file for the full reasoning and code examples.