How do I install the Documentdb Data Modeling skill?

Run npx skillmds@latest add azure/documentdb-data-modeling in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Documentdb Data Modeling safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Documentdb Data Modeling?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Documentdb Data Modeling free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Documentdb Data Modeling?

Azure (@azure) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Documentdb Data Modeling by azure — Agent Skill

Name: Documentdb Data Modeling
Author: Azure

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

Azure bdf0c46 6 files · 10.4 KB Updated Sep 17, 2026

File contents

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.

---name: documentdb-data-modelingdescription: 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 DocumentDBGuiding 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) measuresheap vs TOAST bytes on a live local container and reports **where** a large fieldshould be split out — it never moves data:```bashbash 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.

Frequently asked questions