documentdb-data-modeling

Files (6)

• SKILL.md
• model-16mb-limit.md
• model-denormalize-reads.md
• model-embed-vs-reference.md
• model-large-field-split.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.
- [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.

From Azure/documentdb-agent-kit, MIT.

More from Azure/documentdb-agent-kit