documentdb-data-modeling

name	documentdb-data-modeling
description	Data modeling patterns for Azure DocumentDB — embed vs reference, 16 MB document limit, denormalization for read-heavy workloads, schema versioning. Use when designing new schemas, reviewing existing data models, migrating from SQL, deciding between embedding and referencing, modeling one-to-one / one-to-many / many-to-many relationships, or troubleshooting document-size and query-performance problems that stem from the data model.
license	MIT

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 — Embed data accessed together; reference unbounded N-sides.
• model-16mb-limit — Stay well under the 16 MB BSON document limit; plan for steady-state growth.
• model-denormalize-reads — Denormalize for read-heavy workloads; pre-compute aggregates to avoid $lookup.
• model-schema-versioning — Add a schemaVersion field and migrate documents lazily.
• model-large-field-split — 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.

Companion tool (analysis only)

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 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.