MongoDB Expert

Reference guide for MongoDB schema design, performance optimization, benchmarking, and standard practices. Grounded in MongoDB: The Definitive Guide (3rd ed.) and MongoDB 8.0 in Action (Arek Borucki). Use it to give correct, book-backed answers instead of guessing.

Version baseline

• Target: MongoDB 8.0, WiredTiger storage engine, mongosh.
• Features tied to a specific release are tagged inline as (≥X.Y) in the reference files. Grep for (≥ to find every version-gated claim.
• Sources: IA = MongoDB 8.0 in Action (authoritative for 8.0 defaults/new features). DG = MongoDB: The Definitive Guide, 3rd ed. (examples are 4.2-era; still correct for core mechanics — defer to IA where they conflict).
• MongoDB ships a major release roughly yearly. See Keeping this skill current below.

Which reference to load

Read only the file(s) the task needs — each is a standalone deep reference.

Cross-cutting rules of thumb live below; the reference files carry the detail, examples, and citations.

Highest-leverage rules (quick reference)

Schema

• Model for your access patterns, not entity relationships. Store data that's read together in the same document.
• Embed small, stable, always-co-accessed data (one-to-few); reference large, volatile, independently-queried, or unbounded data (one-to-millions). Normalizing speeds writes; denormalizing speeds reads.
• Hard limit: 16 MB per document. Unbounded array growth is the #1 anti-pattern → reference, or use the Subset/Outlier pattern.

Performance

• Order compound index keys by ESR: Equality → Sort → Range. Put the most selective equality field first.
• Aim for explain("executionStats") where nReturned ≈ totalKeysExamined ≈ totalDocsExamined. A COLLSCAN or a blocking SORT stage means a missing/wrong index.
• One index per query (except $or). In aggregation: $match/$sort/$limit early; index the $lookup foreignField; filter before $unwind.

Benchmarking

• Benchmark on production-like data volume and warm cache — small datasets and cold caches lie. Measure the tail (slow ops via the profiler), not the average.
• The working set (hot data + indexes) should fit in RAM; constant disk churn is the symptom that it doesn't.

Standard practices

• Default to writeConcern:{w:"majority"} for durability (survives failover, no rollback). w:1 can be rolled back. w:"majority" is the 8.0 default (≥5.0).
• Production = 3-member replica set minimum; avoid arbiters. Never use a monotonic shard key (ObjectId/timestamp) → hot shard.
• Single-document writes are already atomic — reach for multi-doc transactions sparingly; good schema design removes most of the need.
• Enable auth + TLS; keep MongoDB off the public internet; least-privilege RBAC.

Keeping this skill current

The user asked that this skill track MongoDB version upgrades. When a new major MongoDB release lands (≈yearly):

1. Update the baseline — bump "Target: MongoDB 8.0" in this file and the per-file baseline lines.
2. Find version-gated claims — every one is tagged (≥X.Y). Run grep -rn '(≥' ~/.claude/skills/mongodb-expert/ to list them; check whether defaults/limits changed (e.g. default chunk size, default write concern, ticket behavior).
3. Add new-release features — new index types, aggregation stages, query-engine changes (e.g. the 8.0 EXPRESS stages), sharding features. Add them tagged with their release.
4. Re-verify defaults that silently change — default write concern, default chunk size (128 MB since 5.2), WiredTiger ticket behavior (dynamic ≥7.0), TTL/capped changes. These are the claims most likely to go stale.
5. Prefer the latest edition of the source books, and MongoDB's release notes / docs.mongodb.com, for the diff.

Content is split across the four reference files, so most updates touch one file. Keep citations on version-gated claims — they carry the authority and make the next update greppable.