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

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.