MongoDB

---

name: MongoDB slug: mongodb version: 1.0.1 description: Design MongoDB schemas with proper embedding, indexing, aggregation, and production-ready patterns. metadata: {"clawdbot":{"emoji":"🍃","requires":{"anyBins":["mongosh","mongo"]},"os":["linux","darwin","win32"]}}

When to Use

User needs MongoDB expertise — from schema design to production optimization. Agent handles document modeling, indexing strategies, aggregation pipelines, consistency patterns, and scaling.

Quick Reference

Schema Design Philosophy

• Embed when data is queried together and doesn't grow unboundedly
• Reference when data is large, accessed independently, or many-to-many
• Denormalize for read performance, accept update complexity—no JOINs means duplicate data
• Design for your queries, not for normalized elegance

Document Size Traps

• 16MB max per document—plan for this from day one; use GridFS for large files
• Arrays that grow infinitely = disaster—use bucketing pattern instead
• BSON overhead: field names repeated per document—short names save space at scale
• Nested depth limit 100 levels—rarely hit but exists

Array Traps

• Arrays > 1000 elements hurt performance—pagination inside documents is hard
• $push without $slice = unbounded growth; use $push: {$each: [...], $slice: -100}
• Multikey indexes on arrays: index entry per element—can explode index size
• Can't have multikey index on more than one array field in compound index

$lookup Traps

• $lookup performance degrades with collection size—no index on foreign collection (until 5.0)
• One $lookup per pipeline stage—nested lookups get complex and slow
• $lookup with pipeline (5.0+) can filter before joining—massive improvement
• Consider: if you $lookup frequently, maybe embed instead

Index Strategy

• ESR rule: Equality fields first, Sort fields next, Range fields last
• MongoDB doesn't do efficient index intersection—single compound index often better
• Only one text index per collection—plan carefully; use Atlas Search for complex text
• TTL index for auto-expiration: {createdAt: 1}, {expireAfterSeconds: 86400}

Consistency Traps

• Default read/write concern not fully consistent—{w: "majority", readConcern: "majority"} for strong
• Multi-document transactions since 4.0—but add latency and lock overhead; design to minimize
• Single-document operations are atomic—exploit this by embedding related data
• retryWrites: true in connection string—handles transient failures automatically

Read Preference Traps

• Stale reads on secondaries—replication lag can be seconds
• nearest for lowest latency—but may read stale data
• Write always goes to primary—read preference doesn't affect writes
• Read your own writes: use primary or session-based causal consistency

ObjectId Traps

• Contains timestamp: ObjectId.getTimestamp()—extract creation time without extra field
• Roughly time-ordered—can sort by _id for creation order without createdAt
• Not random—predictable if you know creation time; don't rely on for security tokens

Performance Mindset

• explain("executionStats") shows actual execution—not just theoretical plan
• totalDocsExamined vs nReturned ratio should be ~1—otherwise index missing
• COLLSCAN in explain = full collection scan—add appropriate index
• Covered queries: IXSCAN + totalDocsExamined: 0—all data from index

Aggregation Philosophy

• Pipeline stages are transformations—think of data flowing through
• Filter early ($match), project early ($project)—reduce data volume ASAP
• $match at start can use indexes; $match after $unwind cannot
• Test complex pipelines stage by stage—build incrementally

Common Mistakes

• Treating MongoDB as "schemaless"—still need schema design; just enforced in app not DB
• Not adding indexes—scans entire collection; every query pattern needs index
• Giant documents via array pushes—hit 16MB limit or slow BSON parsing
• Ignoring write concern—data may appear written but not persisted/replicated