documentdb-data-modeling

Files (5)

• SKILL.md
• model-16mb-limit.md
• model-denormalize-reads.md
• model-embed-vs-reference.md
• model-schema-versioning.md

SKILL.md (first lines)

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

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

From khelanmodi/documentdb-agent-kit, MIT.

More from khelanmodi/documentdb-agent-kit