---

name: database-mongodb description: Apply MongoDB data-modeling, indexing, and query rules from access patterns. Use when designing schemas, choosing embed vs reference, or tuning MongoDB query behavior. metadata: triggers: files: - '/*.ts' - '/.js' - '**/.json' keywords: - mongo - mongoose - objectid - schema - model upstream: - name: mongodb source: github repo: mongodb/mongo pinned: "8.0.0" tag_pattern: "^r(\d+\.\d+\.\d+)quot; reviewed: "2026-06-17"

MongoDB Best Practices

Priority: P0 (CRITICAL)

Rules

• Model from access patterns: data read together should usually live together.
• Embed for bounded one-to-few data; reference for unbounded growth or independent lifecycle.
• Build indexes for real queries, not theoretical flexibility. Use ESR ordering for equality -> sort -> range compound indexes.
• Use transactions only when single-document guarantees are insufficient.

Verify

• Embed vs reference choice matches cardinality and lifecycle.
• Compound index order matches equality -> sort -> range access.
• Large pagination uses cursor patterns, not deep skip().
• Explain output supports the chosen indexes; review keysExamined and docsExamined.
• Unbounded arrays and hot shard keys were reviewed.

Anti-Patterns

• No unbounded arrays: Use $push with $slice or redesign using Bucket Pattern.
• No client-side filtering: Project only needed fields; never fetch full docs to filter in memory.
• No deep nesting: Keep nesting ≤4 levels; flatten paths that frequently queried.
• No index cargo cult: each index must map to a read path and write tradeoff.

References

• Framework Map
• Best Practices Guide
• Anti-Patterns
• Postgres vs Mongo Comparison