mongodb-guideline

name	mongodb-guideline
description	MongoDB 7.0+ schema design, collection/index creation, query optimization, sharding, and async connection management. Triggers: createCollection, createIndex, aggregation, $lookup, $match, $group, TTL index, async client, embedded document, content schema, metadata, document design, chat/log storage, user settings, content/metadata operations.
origin	custom
workloads	["mongodb"]

MongoDB Database Guideline

When to Activate

• Designing MongoDB collection schemas (chat, log, user settings, content, metadata)
• Writing queries or aggregation pipelines
• Creating indexes (single, compound, TTL, text)
• Troubleshooting slow queries
• Setting up async driver connection (PyMongo Async / Node.js native driver)
• Implementing TTL-based data expiry

MongoDB Version and Defaults

• MongoDB 7.0+
• Driver: raw async driver without ODM
  • Python: PyMongo Async AsyncMongoClient (async) / pymongo 4.x (sync). motor is deprecated as of 2026-05.
  • Node.js: mongodb 6.x (native driver)
• Default write concern: w: "majority"
• Default read preference: primaryPreferred
• Schema validation performed in application layer, not driver (Pydantic, Zod, etc.)

Naming Rules

• Collections: snake_case, plural (e.g. chat_histories, user_settings, contents, content_metadata)
• Fields: snake_case (e.g. user_id, created_at, updated_at)
• Indexes: idx_{collection}_{field} / uidx_{collection}_{field}
• Database: snake_case (e.g. myapp, myapp_log)

Field Type Guide

Use Case	Recommended Type	Notes
Document ID	ObjectId	Default _id, auto-generated
External ID	string (UUID)	For API-facing IDs
Integer	int32 / int64	Use int64 for large counts
Boolean	bool	Never use 0/1 strings
String	string	Always validate max length in app
Timestamp	date (ISODate)	Always store in UTC
Decimal	Decimal128	Never use double for money
Embedded doc	object	For tightly coupled data
Reference	ObjectId / int	For loosely coupled relations
Tags/list	array	Prefer flat arrays
Free-form data	object	Use only when schema is truly dynamic

Prohibited Items

• $where operator: prohibited (JS injection risk)
• Unbounded arrays: prohibited (document size limit 16MB)
• Deep nesting (4+ levels): discouraged
• Storing binary files in documents: use GridFS or S3
• Schema-less by habit: always define expected fields

Reference Files

• document-design.md — Embed vs Reference strategy, content-centric design, global query avoidance
• index-strategy.md — MongoDB index strategies that differ from RDBMS, multikey/partial/TTL
• shard-key.md — Shard key selection principles, pattern-specific guides
• connection-and-features.md — Async connection (PyMongo Async AsyncMongoClient; motor deprecated as of 2026-05), transactions, change streams

Related

• mongodb-patterns — Runtime query/aggregation/index/transaction/connection pool/diagnostic patterns (this guideline covers design conventions; patterns covers execution patterns).