mongodb-schema-design
starsforks
How to install mongodb-schema-design?
mongodb/agent-skills/mongodb-schema-design
$npx -y skills add mongodb/agent-skills --skill mongodb-schema-designMongoDB schema design patterns and anti-patterns. Use when designing data models, reviewing schemas, migrating from SQL, or troubleshooting performance issues caused by schema problems. Triggers on "design schema", "embed vs reference", "MongoDB data model", "schema review", "unb
SKILL.md
| 1 | # MongoDB Schema Design |
| 2 | |
| 3 | Data modeling patterns and anti-patterns for MongoDB, maintained by MongoDB. Bad schema is the root cause of most MongoDB performance and cost issues—queries and indexes cannot fix a fundamentally wrong model. |
| 4 | |
| 5 | ## When to Apply |
| 6 | |
| 7 | Reference these guidelines when: |
| 8 | - Designing a new MongoDB schema from scratch |
| 9 | - Migrating from SQL/relational databases to MongoDB |
| 10 | - Reviewing existing data models for performance issues |
| 11 | - Troubleshooting slow queries or growing document sizes |
| 12 | - Deciding between embedding and referencing |
| 13 | - Modeling relationships (one-to-one, one-to-many, many-to-many) |
| 14 | - Implementing tree/hierarchical structures |
| 15 | - Seeing Atlas Schema Suggestions or Performance Advisor warnings |
| 16 | - Hitting the 16MB document limit |
| 17 | - Adding schema validation to existing collections |
| 18 | |
| 19 | ## Quick Reference |
| 20 | |
| 21 | ### 1. Schema Anti-Patterns - 3 rules |
| 22 | |
| 23 | - [antipattern-unnecessary-collections](references/antipattern-unnecessary-collections.md) - Splitting homogeneous data into multiple collections is often an anti-pattern; consult this reference to validate whether this is the case. |
| 24 | - [antipattern-excessive-lookups](references/antipattern-excessive-lookups.md) - When encountering overly normalized collections that reference each other or frequent and possibly slow $lookup operations, consult this reference to validate whether this is problematic and how to fix it. |
| 25 | - [antipattern-unnecessary-indexes](references/antipattern-unnecessary-indexes.md) - Consult this reference when indexes overlap or are not used by queries, to identify and remove unnecessary indexes that add overhead without benefit. |
| 26 | |
| 27 | ### 2. Schema Fundamentals - 4 rules |
| 28 | |
| 29 | - [fundamental-embed-vs-reference](references/fundamental-embed-vs-reference.md) - Consult this reference for approaches to modeling different types of relationships (1:1, 1:few, 1:many, many:many, tree/hierarchical data) and how to decide between embedding and referencing based on access patterns. |
| 30 | - [fundamental-document-model](references/fundamental-document-model.md) - Fundamentals of the document model. Consult this reference when migrating from SQL or other normalized data to a document database like MongoDB. |
| 31 | - [fundamental-schema-validation](references/fundamental-schema-validation.md) - Consult this reference when creating new collections, or adding validation to existing collections, for example in response to finding inconsistent document structures or data quality issues. |
| 32 | - [fundamental-document-size](references/fundamental-document-size.md) - Consult this reference when documents hit the hard 16MB limit, or when accesses are slower than expected as a result of large documents. |
| 33 | |
| 34 | ### 3. Design Patterns - 11 rules |
| 35 | |
| 36 | - [pattern-approximation](references/pattern-approximation.md) - Use approximate values for high-frequency counters |
| 37 | - [pattern-archive](references/pattern-archive.md) - Move historical data to separate/cold storage for performance |
| 38 | - [pattern-attribute](references/pattern-attribute.md) - Collapse many optional fields into key-value attributes |
| 39 | - [pattern-bucket](references/pattern-bucket.md) - Group time-series or IoT data into buckets |
| 40 | - [pattern-computed](references/pattern-computed.md) - Pre-calculate expensive aggregations |
| 41 | - [pattern-document-versioning](references/pattern-document-versioning.md) - Track document changes to enable historical queries and audit trails |
| 42 | - [pattern-extended-reference](references/pattern-extended-reference.md) - Cache frequently-accessed data from related entities |
| 43 | - [pattern-outlier](references/pattern-outlier.md) - Handle collections in which a small subset of documents are much larger than the rest, to prevent outliers from dominating memory and index costs |
| 44 | - [pattern-polymorphic](references/pattern-polymorphic.md) - Store different types of entities in the same collection, often when they are different types of the same base entity (e.g. different types of users or different types of products) |
| 45 | - [pattern-schema-versioning](references/pattern-schema-versioning.md) - Schema evolution, preventing drift, and safe online migrations. Consult when encountering inconsistent document structures, or when planning a schema change that cannot be applied atomically. |
| 46 | - [pattern-time-series-collections](references/pattern-time-series-collections.md) - Use native time series collections for high-frequency |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
