@vodailoc/kilo-kit-mcp 1.1.0 → 1.1.1

package/skills/engineering/databases/references/mongodb-indexing.md

@@ -1,442 +1,442 @@
-# MongoDB Indexing and Performance
-
-Index types, strategies, and performance optimization techniques for MongoDB.
-
-## Index Fundamentals
-
-Indexes improve query performance by allowing MongoDB to scan fewer documents. Without indexes, MongoDB performs collection scans (reads every document).
-
-```javascript
-// Check if query uses index
-db.users.find({ email: "user@example.com" }).explain("executionStats")
-
-// Key metrics:
-// - executionTimeMillis: query duration
-// - totalDocsExamined: documents scanned
-// - nReturned: documents returned
-// - stage: IXSCAN (index) vs COLLSCAN (full scan)
-```
-
-## Index Types
-
-### Single Field Index
-```javascript
-// Create index on single field
-db.users.createIndex({ email: 1 })  // 1: ascending, -1: descending
-
-// Use case: queries filtering by email
-db.users.find({ email: "user@example.com" })
-
-// Drop index
-db.users.dropIndex({ email: 1 })
-db.users.dropIndex("email_1")  // By name
-```
-
-### Compound Index
-```javascript
-// Index on multiple fields (order matters!)
-db.orders.createIndex({ status: 1, createdAt: -1 })
-
-// Supports queries on:
-// 1. { status: "..." }
-// 2. { status: "...", createdAt: ... }
-// Does NOT efficiently support: { createdAt: ... } alone
-
-// Left-to-right prefix rule
-db.orders.createIndex({ a: 1, b: 1, c: 1 })
-// Supports: {a}, {a,b}, {a,b,c}
-// Not: {b}, {c}, {b,c}
-```
-
-### Text Index (Full-Text Search)
-```javascript
-// Create text index
-db.articles.createIndex({ title: "text", body: "text" })
-
-// Only one text index per collection
-db.articles.createIndex({
-  title: "text",
-  body: "text",
-  tags: "text"
-}, {
-  weights: {
-    title: 10,    // Title matches weighted higher
-    body: 5,
-    tags: 3
-  }
-})
-
-// Search
-db.articles.find({ $text: { $search: "mongodb database" } })
-
-// Search with score
-db.articles.find(
-  { $text: { $search: "mongodb" } },
-  { score: { $meta: "textScore" } }
-).sort({ score: { $meta: "textScore" } })
-```
-
-### Geospatial Indexes
-```javascript
-// 2dsphere index (spherical geometry)
-db.places.createIndex({ location: "2dsphere" })
-
-// Document format
-db.places.insertOne({
-  name: "Coffee Shop",
-  location: {
-    type: "Point",
-    coordinates: [-73.97, 40.77]  // [longitude, latitude]
-  }
-})
-
-// Find nearby
-db.places.find({
-  location: {
-    $near: {
-      $geometry: { type: "Point", coordinates: [-73.97, 40.77] },
-      $maxDistance: 5000  // meters
-    }
-  }
-})
-
-// Within polygon
-db.places.find({
-  location: {
-    $geoWithin: {
-      $geometry: {
-        type: "Polygon",
-        coordinates: [[
-          [lon1, lat1], [lon2, lat2], [lon3, lat3], [lon1, lat1]
-        ]]
-      }
-    }
-  }
-})
-```
-
-### Wildcard Index
-```javascript
-// Index all fields in subdocuments
-db.products.createIndex({ "attributes.$**": 1 })
-
-// Supports queries on any nested field
-db.products.find({ "attributes.color": "red" })
-db.products.find({ "attributes.size": "large" })
-
-// Specific paths only
-db.products.createIndex(
-  { "$**": 1 },
-  { wildcardProjection: { "attributes.color": 1, "attributes.size": 1 } }
-)
-```
-
-### Hashed Index
-```javascript
-// Hashed index (for even distribution in sharding)
-db.users.createIndex({ userId: "hashed" })
-
-// Use case: shard key
-sh.shardCollection("mydb.users", { userId: "hashed" })
-```
-
-### TTL Index (Auto-Expiration)
-```javascript
-// Delete documents after specified time
-db.sessions.createIndex(
-  { createdAt: 1 },
-  { expireAfterSeconds: 3600 }  // 1 hour
-)
-
-// Documents automatically deleted after createdAt + 3600 seconds
-// Background task runs every 60 seconds
-```
-
-### Partial Index
-```javascript
-// Index only documents matching filter
-db.orders.createIndex(
-  { customerId: 1 },
-  { partialFilterExpression: { status: "active" } }
-)
-
-// Index only used when query includes filter
-db.orders.find({ customerId: "123", status: "active" })  // Uses index
-db.orders.find({ customerId: "123" })  // Does not use index
-```
-
-### Unique Index
-```javascript
-// Enforce uniqueness
-db.users.createIndex({ email: 1 }, { unique: true })
-
-// Compound unique index
-db.users.createIndex({ firstName: 1, lastName: 1 }, { unique: true })
-
-// Sparse unique index (null values not indexed)
-db.users.createIndex({ email: 1 }, { unique: true, sparse: true })
-```
-
-### Sparse Index
-```javascript
-// Index only documents with field present
-db.users.createIndex({ phoneNumber: 1 }, { sparse: true })
-
-// Useful for optional fields
-// Documents without phoneNumber not in index
-```
-
-## Index Management
-
-### List Indexes
-```javascript
-// Show all indexes
-db.collection.getIndexes()
-
-// Index statistics
-db.collection.aggregate([{ $indexStats: {} }])
-```
-
-### Create Index Options
-```javascript
-// Background index (doesn't block operations)
-db.collection.createIndex({ field: 1 }, { background: true })
-
-// Index name
-db.collection.createIndex({ field: 1 }, { name: "custom_index_name" })
-
-// Case-insensitive index (collation)
-db.collection.createIndex(
-  { name: 1 },
-  { collation: { locale: "en", strength: 2 } }
-)
-```
-
-### Hide/Unhide Index
-```javascript
-// Hide index (test before dropping)
-db.collection.hideIndex("index_name")
-
-// Check performance without index
-// ...
-
-// Unhide or drop
-db.collection.unhideIndex("index_name")
-db.collection.dropIndex("index_name")
-```
-
-### Rebuild Indexes
-```javascript
-// Rebuild all indexes (after data changes)
-db.collection.reIndex()
-
-// Useful after bulk deletions to reclaim space
-```
-
-## Query Optimization
-
-### Covered Queries
-```javascript
-// Query covered by index (no document fetch)
-db.users.createIndex({ email: 1, name: 1 })
-
-// Covered query (all fields in index)
-db.users.find(
-  { email: "user@example.com" },
-  { email: 1, name: 1, _id: 0 }  // Must exclude _id
-)
-
-// Check with explain: stage should be "IXSCAN" with no "FETCH"
-```
-
-### Index Intersection
-```javascript
-// MongoDB can use multiple indexes
-db.collection.createIndex({ a: 1 })
-db.collection.createIndex({ b: 1 })
-
-// Query may use both indexes
-db.collection.find({ a: 1, b: 1 })
-
-// Usually compound index is better
-db.collection.createIndex({ a: 1, b: 1 })
-```
-
-### Index Hints
-```javascript
-// Force specific index
-db.orders.find({ status: "active", city: "NYC" })
-  .hint({ status: 1, createdAt: -1 })
-
-// Force no index (for testing)
-db.orders.find({ status: "active" }).hint({ $natural: 1 })
-```
-
-### ESR Rule (Equality, Sort, Range)
-```javascript
-// Optimal compound index order: Equality → Sort → Range
-
-// Query
-db.orders.find({
-  status: "completed",        // Equality
-  category: "electronics"     // Equality
-}).sort({
-  orderDate: -1               // Sort
-}).limit(10)
-
-// Optimal index
-db.orders.createIndex({
-  status: 1,      // Equality first
-  category: 1,    // Equality
-  orderDate: -1   // Sort last
-})
-
-// With range
-db.orders.find({
-  status: "completed",        // Equality
-  total: { $gte: 100 }       // Range
-}).sort({
-  orderDate: -1               // Sort
-})
-
-// Optimal index
-db.orders.createIndex({
-  status: 1,      // Equality
-  orderDate: -1,  // Sort
-  total: 1        // Range last
-})
-```
-
-## Performance Analysis
-
-### explain() Modes
-```javascript
-// Query planner (default)
-db.collection.find({ field: value }).explain()
-
-// Execution stats
-db.collection.find({ field: value }).explain("executionStats")
-
-// All execution stats
-db.collection.find({ field: value }).explain("allPlansExecution")
-```
-
-### Key Metrics
-```javascript
-// Good performance indicators:
-// - executionTimeMillis < 100ms
-// - totalDocsExamined ≈ nReturned (examine only what's needed)
-// - stage: "IXSCAN" (using index)
-// - totalKeysExamined ≈ nReturned (index selectivity)
-
-// Bad indicators:
-// - stage: "COLLSCAN" (full collection scan)
-// - totalDocsExamined >> nReturned (scanning too many docs)
-// - executionTimeMillis > 1000ms
-```
-
-### Index Selectivity
-```javascript
-// High selectivity = good (returns few documents)
-// Low selectivity = bad (returns many documents)
-
-// Check selectivity
-db.collection.aggregate([
-  { $group: { _id: "$status", count: { $sum: 1 } } }
-])
-
-// Good for indexing: email, userId, orderId
-// Bad for indexing: gender, status (few unique values)
-```
-
-## Index Strategies
-
-### Multi-Tenant Applications
-```javascript
-// Always filter by tenant first
-db.data.createIndex({ tenantId: 1, createdAt: -1 })
-
-// All queries include tenantId
-db.data.find({ tenantId: "tenant1", createdAt: { $gte: date } })
-```
-
-### Time-Series Data
-```javascript
-// Index on timestamp descending (recent data accessed more)
-db.events.createIndex({ timestamp: -1 })
-
-// Compound with filter fields
-db.events.createIndex({ userId: 1, timestamp: -1 })
-```
-
-### Lookup Optimization
-```javascript
-// Index foreign key fields
-db.orders.createIndex({ customerId: 1 })
-db.customers.createIndex({ _id: 1 })  // Default _id index
-
-// Aggregation $lookup uses these indexes
-```
-
-## Best Practices
-
-1. **Create indexes for frequent queries** - Analyze slow query logs
-2. **Limit number of indexes** - Each index adds write overhead
-3. **Use compound indexes** - More efficient than multiple single indexes
-4. **Follow ESR rule** - Equality, Sort, Range order
-5. **Use covered queries** - When possible, avoid document fetches
-6. **Monitor index usage** - Drop unused indexes
-```javascript
-db.collection.aggregate([{ $indexStats: {} }])
-```
-7. **Partial indexes for filtered queries** - Reduce index size
-8. **Consider index size** - Should fit in RAM
-```javascript
-db.collection.stats().indexSizes
-```
-9. **Background index creation** - Don't block operations (deprecated in 4.2+)
-10. **Test with explain** - Verify query plan before production
-
-## Common Pitfalls
-
-1. **Over-indexing** - Too many indexes slow writes
-2. **Unused indexes** - Waste space and write performance
-3. **Regex without prefix** - `/pattern/` can't use index, `/^pattern/` can
-4. **$ne, $nin queries** - Often scan entire collection
-5. **$or with multiple branches** - May not use indexes efficiently
-6. **Sort without index** - In-memory sort limited to 32MB
-7. **Compound index order** - Wrong order makes index useless
-8. **Case-sensitive queries** - Use collation for case-insensitive
-
-## Monitoring
-
-```javascript
-// Current operations
-db.currentOp()
-
-// Slow queries (enable profiling)
-db.setProfilingLevel(1, { slowms: 100 })
-db.system.profile.find().sort({ ts: -1 }).limit(10)
-
-// Index statistics
-db.collection.aggregate([
-  { $indexStats: {} },
-  { $sort: { "accesses.ops": -1 } }
-])
-
-// Collection statistics
-db.collection.stats()
-```
-
-## Index Size Calculation
-
-```javascript
-// Check index sizes
-db.collection.stats().indexSizes
-
-// Total index size
-db.collection.totalIndexSize()
-
-// Recommend: indexes fit in RAM
-// Monitor: db.serverStatus().mem
-```
+# MongoDB Indexing and Performance
+
+Index types, strategies, and performance optimization techniques for MongoDB.
+
+## Index Fundamentals
+
+Indexes improve query performance by allowing MongoDB to scan fewer documents. Without indexes, MongoDB performs collection scans (reads every document).
+
+```javascript
+// Check if query uses index
+db.users.find({ email: "user@example.com" }).explain("executionStats")
+
+// Key metrics:
+// - executionTimeMillis: query duration
+// - totalDocsExamined: documents scanned
+// - nReturned: documents returned
+// - stage: IXSCAN (index) vs COLLSCAN (full scan)
+```
+
+## Index Types
+
+### Single Field Index
+```javascript
+// Create index on single field
+db.users.createIndex({ email: 1 })  // 1: ascending, -1: descending
+
+// Use case: queries filtering by email
+db.users.find({ email: "user@example.com" })
+
+// Drop index
+db.users.dropIndex({ email: 1 })
+db.users.dropIndex("email_1")  // By name
+```
+
+### Compound Index
+```javascript
+// Index on multiple fields (order matters!)
+db.orders.createIndex({ status: 1, createdAt: -1 })
+
+// Supports queries on:
+// 1. { status: "..." }
+// 2. { status: "...", createdAt: ... }
+// Does NOT efficiently support: { createdAt: ... } alone
+
+// Left-to-right prefix rule
+db.orders.createIndex({ a: 1, b: 1, c: 1 })
+// Supports: {a}, {a,b}, {a,b,c}
+// Not: {b}, {c}, {b,c}
+```
+
+### Text Index (Full-Text Search)
+```javascript
+// Create text index
+db.articles.createIndex({ title: "text", body: "text" })
+
+// Only one text index per collection
+db.articles.createIndex({
+  title: "text",
+  body: "text",
+  tags: "text"
+}, {
+  weights: {
+    title: 10,    // Title matches weighted higher
+    body: 5,
+    tags: 3
+  }
+})
+
+// Search
+db.articles.find({ $text: { $search: "mongodb database" } })
+
+// Search with score
+db.articles.find(
+  { $text: { $search: "mongodb" } },
+  { score: { $meta: "textScore" } }
+).sort({ score: { $meta: "textScore" } })
+```
+
+### Geospatial Indexes
+```javascript
+// 2dsphere index (spherical geometry)
+db.places.createIndex({ location: "2dsphere" })
+
+// Document format
+db.places.insertOne({
+  name: "Coffee Shop",
+  location: {
+    type: "Point",
+    coordinates: [-73.97, 40.77]  // [longitude, latitude]
+  }
+})
+
+// Find nearby
+db.places.find({
+  location: {
+    $near: {
+      $geometry: { type: "Point", coordinates: [-73.97, 40.77] },
+      $maxDistance: 5000  // meters
+    }
+  }
+})
+
+// Within polygon
+db.places.find({
+  location: {
+    $geoWithin: {
+      $geometry: {
+        type: "Polygon",
+        coordinates: [[
+          [lon1, lat1], [lon2, lat2], [lon3, lat3], [lon1, lat1]
+        ]]
+      }
+    }
+  }
+})
+```
+
+### Wildcard Index
+```javascript
+// Index all fields in subdocuments
+db.products.createIndex({ "attributes.$**": 1 })
+
+// Supports queries on any nested field
+db.products.find({ "attributes.color": "red" })
+db.products.find({ "attributes.size": "large" })
+
+// Specific paths only
+db.products.createIndex(
+  { "$**": 1 },
+  { wildcardProjection: { "attributes.color": 1, "attributes.size": 1 } }
+)
+```
+
+### Hashed Index
+```javascript
+// Hashed index (for even distribution in sharding)
+db.users.createIndex({ userId: "hashed" })
+
+// Use case: shard key
+sh.shardCollection("mydb.users", { userId: "hashed" })
+```
+
+### TTL Index (Auto-Expiration)
+```javascript
+// Delete documents after specified time
+db.sessions.createIndex(
+  { createdAt: 1 },
+  { expireAfterSeconds: 3600 }  // 1 hour
+)
+
+// Documents automatically deleted after createdAt + 3600 seconds
+// Background task runs every 60 seconds
+```
+
+### Partial Index
+```javascript
+// Index only documents matching filter
+db.orders.createIndex(
+  { customerId: 1 },
+  { partialFilterExpression: { status: "active" } }
+)
+
+// Index only used when query includes filter
+db.orders.find({ customerId: "123", status: "active" })  // Uses index
+db.orders.find({ customerId: "123" })  // Does not use index
+```
+
+### Unique Index
+```javascript
+// Enforce uniqueness
+db.users.createIndex({ email: 1 }, { unique: true })
+
+// Compound unique index
+db.users.createIndex({ firstName: 1, lastName: 1 }, { unique: true })
+
+// Sparse unique index (null values not indexed)
+db.users.createIndex({ email: 1 }, { unique: true, sparse: true })
+```
+
+### Sparse Index
+```javascript
+// Index only documents with field present
+db.users.createIndex({ phoneNumber: 1 }, { sparse: true })
+
+// Useful for optional fields
+// Documents without phoneNumber not in index
+```
+
+## Index Management
+
+### List Indexes
+```javascript
+// Show all indexes
+db.collection.getIndexes()
+
+// Index statistics
+db.collection.aggregate([{ $indexStats: {} }])
+```
+
+### Create Index Options
+```javascript
+// Background index (doesn't block operations)
+db.collection.createIndex({ field: 1 }, { background: true })
+
+// Index name
+db.collection.createIndex({ field: 1 }, { name: "custom_index_name" })
+
+// Case-insensitive index (collation)
+db.collection.createIndex(
+  { name: 1 },
+  { collation: { locale: "en", strength: 2 } }
+)
+```
+
+### Hide/Unhide Index
+```javascript
+// Hide index (test before dropping)
+db.collection.hideIndex("index_name")
+
+// Check performance without index
+// ...
+
+// Unhide or drop
+db.collection.unhideIndex("index_name")
+db.collection.dropIndex("index_name")
+```
+
+### Rebuild Indexes
+```javascript
+// Rebuild all indexes (after data changes)
+db.collection.reIndex()
+
+// Useful after bulk deletions to reclaim space
+```
+
+## Query Optimization
+
+### Covered Queries
+```javascript
+// Query covered by index (no document fetch)
+db.users.createIndex({ email: 1, name: 1 })
+
+// Covered query (all fields in index)
+db.users.find(
+  { email: "user@example.com" },
+  { email: 1, name: 1, _id: 0 }  // Must exclude _id
+)
+
+// Check with explain: stage should be "IXSCAN" with no "FETCH"
+```
+
+### Index Intersection
+```javascript
+// MongoDB can use multiple indexes
+db.collection.createIndex({ a: 1 })
+db.collection.createIndex({ b: 1 })
+
+// Query may use both indexes
+db.collection.find({ a: 1, b: 1 })
+
+// Usually compound index is better
+db.collection.createIndex({ a: 1, b: 1 })
+```
+
+### Index Hints
+```javascript
+// Force specific index
+db.orders.find({ status: "active", city: "NYC" })
+  .hint({ status: 1, createdAt: -1 })
+
+// Force no index (for testing)
+db.orders.find({ status: "active" }).hint({ $natural: 1 })
+```
+
+### ESR Rule (Equality, Sort, Range)
+```javascript
+// Optimal compound index order: Equality → Sort → Range
+
+// Query
+db.orders.find({
+  status: "completed",        // Equality
+  category: "electronics"     // Equality
+}).sort({
+  orderDate: -1               // Sort
+}).limit(10)
+
+// Optimal index
+db.orders.createIndex({
+  status: 1,      // Equality first
+  category: 1,    // Equality
+  orderDate: -1   // Sort last
+})
+
+// With range
+db.orders.find({
+  status: "completed",        // Equality
+  total: { $gte: 100 }       // Range
+}).sort({
+  orderDate: -1               // Sort
+})
+
+// Optimal index
+db.orders.createIndex({
+  status: 1,      // Equality
+  orderDate: -1,  // Sort
+  total: 1        // Range last
+})
+```
+
+## Performance Analysis
+
+### explain() Modes
+```javascript
+// Query planner (default)
+db.collection.find({ field: value }).explain()
+
+// Execution stats
+db.collection.find({ field: value }).explain("executionStats")
+
+// All execution stats
+db.collection.find({ field: value }).explain("allPlansExecution")
+```
+
+### Key Metrics
+```javascript
+// Good performance indicators:
+// - executionTimeMillis < 100ms
+// - totalDocsExamined ≈ nReturned (examine only what's needed)
+// - stage: "IXSCAN" (using index)
+// - totalKeysExamined ≈ nReturned (index selectivity)
+
+// Bad indicators:
+// - stage: "COLLSCAN" (full collection scan)
+// - totalDocsExamined >> nReturned (scanning too many docs)
+// - executionTimeMillis > 1000ms
+```
+
+### Index Selectivity
+```javascript
+// High selectivity = good (returns few documents)
+// Low selectivity = bad (returns many documents)
+
+// Check selectivity
+db.collection.aggregate([
+  { $group: { _id: "$status", count: { $sum: 1 } } }
+])
+
+// Good for indexing: email, userId, orderId
+// Bad for indexing: gender, status (few unique values)
+```
+
+## Index Strategies
+
+### Multi-Tenant Applications
+```javascript
+// Always filter by tenant first
+db.data.createIndex({ tenantId: 1, createdAt: -1 })
+
+// All queries include tenantId
+db.data.find({ tenantId: "tenant1", createdAt: { $gte: date } })
+```
+
+### Time-Series Data
+```javascript
+// Index on timestamp descending (recent data accessed more)
+db.events.createIndex({ timestamp: -1 })
+
+// Compound with filter fields
+db.events.createIndex({ userId: 1, timestamp: -1 })
+```
+
+### Lookup Optimization
+```javascript
+// Index foreign key fields
+db.orders.createIndex({ customerId: 1 })
+db.customers.createIndex({ _id: 1 })  // Default _id index
+
+// Aggregation $lookup uses these indexes
+```
+
+## Best Practices
+
+1. **Create indexes for frequent queries** - Analyze slow query logs
+2. **Limit number of indexes** - Each index adds write overhead
+3. **Use compound indexes** - More efficient than multiple single indexes
+4. **Follow ESR rule** - Equality, Sort, Range order
+5. **Use covered queries** - When possible, avoid document fetches
+6. **Monitor index usage** - Drop unused indexes
+```javascript
+db.collection.aggregate([{ $indexStats: {} }])
+```
+7. **Partial indexes for filtered queries** - Reduce index size
+8. **Consider index size** - Should fit in RAM
+```javascript
+db.collection.stats().indexSizes
+```
+9. **Background index creation** - Don't block operations (deprecated in 4.2+)
+10. **Test with explain** - Verify query plan before production
+
+## Common Pitfalls
+
+1. **Over-indexing** - Too many indexes slow writes
+2. **Unused indexes** - Waste space and write performance
+3. **Regex without prefix** - `/pattern/` can't use index, `/^pattern/` can
+4. **$ne, $nin queries** - Often scan entire collection
+5. **$or with multiple branches** - May not use indexes efficiently
+6. **Sort without index** - In-memory sort limited to 32MB
+7. **Compound index order** - Wrong order makes index useless
+8. **Case-sensitive queries** - Use collation for case-insensitive
+
+## Monitoring
+
+```javascript
+// Current operations
+db.currentOp()
+
+// Slow queries (enable profiling)
+db.setProfilingLevel(1, { slowms: 100 })
+db.system.profile.find().sort({ ts: -1 }).limit(10)
+
+// Index statistics
+db.collection.aggregate([
+  { $indexStats: {} },
+  { $sort: { "accesses.ops": -1 } }
+])
+
+// Collection statistics
+db.collection.stats()
+```
+
+## Index Size Calculation
+
+```javascript
+// Check index sizes
+db.collection.stats().indexSizes
+
+// Total index size
+db.collection.totalIndexSize()
+
+// Recommend: indexes fit in RAM
+// Monitor: db.serverStatus().mem
+```