Skip to content

skillDatabasesmongodb

MongoDB Schema Modeling

Decides between embedding and referencing in MongoDB and shapes documents around the actual read and write patterns of the app.

npx workspacetemplates add mongodb-schema-modeling --tool claude-code

Writes 1 file to .claude/skills/mongodb-schema-modeling/

.claude/skills/mongodb-schema-modeling/SKILL.md31 lines · 1.7 KBFile
---
name: mongodb-schema-modeling
description: Decides between embedding and referencing in MongoDB and shapes documents around the actual read and write patterns of the app.
---

# MongoDB schema modeling

Model for access patterns. Data that is read together lives together.

## Steps

1. List the queries and writes with frequency: "load an order with its lines (very often)", "update one line status (often)", "report by month (nightly)".
2. For each relationship decide:
   - Embed when the child is read with the parent, belongs to one parent, and stays small and bounded.
   - Reference when the child is shared, queried alone, or grows without limit.
   - Use the subset pattern when you need only the latest few children (embed 10 recent comments, reference the rest).
3. Never allow an unbounded array. Put growing lists in their own collection with the parent id and an index.
4. Precompute values read far more than written (order totals, counters) and update them in the same write; use the bucket pattern for time series.
5. Keep documents under a few hundred KB. Note the 16 MB hard limit.
6. Design indexes from the queries: compound indexes follow equality, sort, range order. Use `explain("executionStats")` and compare `totalDocsExamined` with `nReturned`.
7. Add schema validation (`$jsonSchema`) with required fields and types, and a `schemaVersion` field to allow later changes.
8. Use multi-document transactions only when the model truly spans documents; a better embed often removes the need.

## Rules

- Do not copy relational tables one to one.
- Avoid `$lookup` on hot paths; denormalize deliberately and write down who updates the copy.

## Report

Collections with sample documents, indexes, and one line of reasoning per embed or reference choice.

What it does

In MongoDB the document shape is the performance plan. This skill starts from how the app reads and updates data, then chooses what to nest, what to link and what to precompute.

It also flags the usual traps: arrays that grow without bound, documents near the 16 MB limit and indexes that do not match the query.

Example

you › Model collections for a blog with posts, comments and tags

agent › posts embeds tags (small, bounded) and the 5 latest comments; comments is its own collection indexed on (postId, createdAt) because threads can grow large. commentCount lives on the post and is updated with $inc. Added $jsonSchema validation and schemaVersion: 1.

Questions

Is duplicating data in MongoDB acceptable?
Yes, when reads dominate. Decide which copy is the truth and make the write path update the others, or accept a documented delay.
How do I change the shape later?
Store a schemaVersion, write code that reads both versions, and migrate documents in batches in the background.
  • Database Connection Pooling

    SkillDatabases

    Free
  • Database Migration Safety

    SkillDatabases

    Free
  • Database Schema Design

    SkillDatabases

    Free
  • MySQL Query Tuning

    Skillmysql

    Free