mongodb-schema-design_skill

Overview

This skill teaches practical MongoDB schema design and NoSQL data modeling patterns. It focuses on when to embed vs reference, modeling relationships, normalization vs denormalization, and planning schema evolution. Use it to design schemas that match query patterns and scale predictably.

How this skill works

I show concrete patterns (embedded documents, arrays, references, polymorphic types, adjacency lists, versioning) and provide decision rules to choose between them. The skill includes example documents, Python snippets for inserts and $lookup aggregation, and guidelines for performance, validation, and evolution. It inspects typical query and growth patterns and recommends embedding or referencing accordingly.

When to use it

• Designing a new MongoDB schema to match application queries
• Modeling one-to-one, one-to-many, and many-to-many relationships
• Deciding between embedding and referencing for performance and scalability
• Planning for unbounded arrays or rapidly growing related data
• Preparing for schema evolution, versioning, and audit history

Best practices

• Embed when related data is always read and updated together to reduce queries and ensure atomicity
• Reference when related collections can grow without bound or are accessed independently
• Keep documents under MongoDB's 16MB limit and favor smaller, focused documents
• Model for your most common query patterns; optimize read or write paths intentionally
• Use validation schemas and document design decisions to support evolution and maintenance
• Denormalize selectively for performance and track trade-offs for consistency

Example use cases

• User profile with embedded address when address is small and always retrieved with the user
• Orders stored as a separate collection referenced from users when order volume is large
• Product attributes stored as key/value arrays for flexible variants and filters
• Categories modeled with adjacency lists for hierarchical navigation and parent lookups
• Versioned product documents to preserve history and support rollback or audit trails