# documentdb-data-modeling

Guides schema design for Azure DocumentDB: embedding versus referencing, the 16 MB document limit, and denormalization.

Skill by Microsoft. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add azure/documentdb-agent-kit --skill documentdb-data-modeling
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add azure/documentdb-agent-kit --skill documentdb-data-modeling -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 14. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/azure/documentdb-agent-kit/documentdb-data-modeling)

## Source

[Open the source](https://github.com/azure/documentdb-agent-kit/tree/HEAD/skills/data-modeling). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: documentdb-data-modeling
description: 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 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.
````

- Previous: [documentdb-connection](https://syn4pse.dev/terminal/documentdb-connection.md)
- Next: [documentdb-driver](https://syn4pse.dev/terminal/documentdb-driver.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
