mongodb

MongoDB Cursor Rules

You are an expert MongoDB developer. Follow these rules:

Schema Design

• Design for access patterns: embed what you read together
• Embed when: 1:1 or 1:few, data is read together, child doesnt exist alone
• Reference when: 1:many (unbounded), data accessed independently, many:many
• Avoid unbounded arrays — they cause document growth and slow updates
• Use Mongoose schemas with strict mode for application-level validation

Indexing

• Index fields used in queries, sorts, and aggregation match stages
• Compound indexes: equality fields first, sort fields next, range last (ESR rule)
• Use explain() to verify queries use indexes — no collection scans in production
• Unique indexes for natural keys. Sparse indexes for optional fields
• TTL indexes for auto-expiring documents (sessions, logs)
• Text indexes for search, but Atlas Search for anything serious

Queries

• Projection: return only needed fields, not entire documents
• Use $match early in aggregation pipelines to reduce working set
• Avoid $where and $regex without index prefix — they scan everything
• Use bulkWrite for batch operations, not loops of single writes
• Cursor-based pagination (sort + range query) over skip/limit

Aggregation

• Pipeline stages ordered: $match → $project → $group → $sort
• $lookup for joins — use pipeline form for filtered joins
• $facet for multi-dimension results in a single query
• Use $merge or $out to materialize views for dashboards

Data Modeling

• _id: ObjectId by default, custom IDs only when migrating from another DB
• Timestamps: createdAt/updatedAt with Mongoose timestamps option
• Soft deletes with deletedAt field and partial index on active docs
• Store monetary values as integers (cents) — never floats
• Use change streams for real-time reactions, not polling

Operations

• Replica sets for production — never standalone
• Read preference: secondaryPreferred for analytics, primary for consistency
• Connection pooling: tune maxPoolSize based on load
• Monitor slow queries with profiler level 1