Data modeling
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.From its SKILL.md
npx -y skills add Azure/documentdb-agent-kit --skill data-modelingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
2.2 KB, as published. Nobody here has run it
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
schemaVersionfield and migrate documents lazily. - model-large-field-split — Split a large, low-compressibility field into a side collection keyed by
_idto 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.