anchi-kit 1.2.0 → 1.2.2

package/.antigravity/skills/databases/references/mongodb-aggregation.md

@@ -1,447 +0,0 @@
-# MongoDB Aggregation Pipeline
-
-Aggregation pipeline for complex data transformations, analytics, and multi-stage processing.
-
-## Pipeline Concept
-
-Aggregation processes documents through multiple stages. Each stage transforms documents and passes results to next stage.
-
-```javascript
-db.collection.aggregate([
-  { /* Stage 1 */ },
-  { /* Stage 2 */ },
-  { /* Stage 3 */ }
-])
-```
-
-## Core Pipeline Stages
-
-### $match (Filter Documents)
-```javascript
-// Filter early in pipeline for efficiency
-db.orders.aggregate([
-  { $match: { status: "completed", total: { $gte: 100 } } },
-  // Subsequent stages process only matched documents
-])
-
-// Multiple conditions
-db.orders.aggregate([
-  { $match: {
-    $and: [
-      { orderDate: { $gte: startDate } },
-      { status: { $in: ["completed", "shipped"] } }
-    ]
-  }}
-])
-```
-
-### $project (Reshape Documents)
-```javascript
-// Select and reshape fields
-db.orders.aggregate([
-  { $project: {
-    orderNumber: 1,
-    total: 1,
-    customerName: "$customer.name",
-    year: { $year: "$orderDate" },
-    _id: 0  // Exclude _id
-  }}
-])
-
-// Computed fields
-db.orders.aggregate([
-  { $project: {
-    total: 1,
-    tax: { $multiply: ["$total", 0.1] },
-    grandTotal: { $add: ["$total", { $multiply: ["$total", 0.1] }] }
-  }}
-])
-```
-
-### $group (Aggregate Data)
-```javascript
-// Group and count
-db.orders.aggregate([
-  { $group: {
-    _id: "$status",
-    count: { $sum: 1 }
-  }}
-])
-
-// Multiple aggregations
-db.orders.aggregate([
-  { $group: {
-    _id: "$customerId",
-    totalSpent: { $sum: "$total" },
-    orderCount: { $sum: 1 },
-    avgOrderValue: { $avg: "$total" },
-    maxOrder: { $max: "$total" },
-    minOrder: { $min: "$total" }
-  }}
-])
-
-// Group by multiple fields
-db.sales.aggregate([
-  { $group: {
-    _id: {
-      year: { $year: "$date" },
-      month: { $month: "$date" },
-      product: "$productId"
-    },
-    revenue: { $sum: "$amount" }
-  }}
-])
-```
-
-### $sort (Order Results)
-```javascript
-// Sort by field
-db.orders.aggregate([
-  { $sort: { total: -1 } }  // -1: descending, 1: ascending
-])
-
-// Sort by multiple fields
-db.orders.aggregate([
-  { $sort: { status: 1, orderDate: -1 } }
-])
-```
-
-### $limit / $skip (Pagination)
-```javascript
-// Limit results
-db.orders.aggregate([
-  { $sort: { orderDate: -1 } },
-  { $limit: 10 }
-])
-
-// Pagination
-const page = 2;
-const pageSize = 20;
-db.orders.aggregate([
-  { $sort: { orderDate: -1 } },
-  { $skip: (page - 1) * pageSize },
-  { $limit: pageSize }
-])
-```
-
-### $lookup (Join Collections)
-```javascript
-// Simple join
-db.orders.aggregate([
-  { $lookup: {
-    from: "customers",
-    localField: "customerId",
-    foreignField: "_id",
-    as: "customer"
-  }},
-  { $unwind: "$customer" }  // Convert array to object
-])
-
-// Pipeline join (more powerful)
-db.orders.aggregate([
-  { $lookup: {
-    from: "products",
-    let: { items: "$items" },
-    pipeline: [
-      { $match: { $expr: { $in: ["$_id", "$$items.productId"] } } },
-      { $project: { name: 1, price: 1 } }
-    ],
-    as: "productDetails"
-  }}
-])
-```
-
-### $unwind (Deconstruct Arrays)
-```javascript
-// Unwind array field
-db.orders.aggregate([
-  { $unwind: "$items" }
-])
-
-// Preserve null/empty arrays
-db.orders.aggregate([
-  { $unwind: {
-    path: "$items",
-    preserveNullAndEmptyArrays: true
-  }}
-])
-
-// Include array index
-db.orders.aggregate([
-  { $unwind: {
-    path: "$items",
-    includeArrayIndex: "itemIndex"
-  }}
-])
-```
-
-### $addFields (Add New Fields)
-```javascript
-// Add computed fields
-db.orders.aggregate([
-  { $addFields: {
-    totalWithTax: { $multiply: ["$total", 1.1] },
-    year: { $year: "$orderDate" }
-  }}
-])
-```
-
-### $replaceRoot (Replace Document Root)
-```javascript
-// Promote subdocument to root
-db.orders.aggregate([
-  { $replaceRoot: { newRoot: "$customer" } }
-])
-
-// Merge fields
-db.orders.aggregate([
-  { $replaceRoot: {
-    newRoot: { $mergeObjects: ["$customer", { orderId: "$_id" }] }
-  }}
-])
-```
-
-## Aggregation Operators
-
-### Arithmetic Operators
-```javascript
-// Basic math
-db.products.aggregate([
-  { $project: {
-    name: 1,
-    profit: { $subtract: ["$price", "$cost"] },
-    margin: { $multiply: [
-      { $divide: [
-        { $subtract: ["$price", "$cost"] },
-        "$price"
-      ]},
-      100
-    ]}
-  }}
-])
-
-// Other operators: $add, $multiply, $divide, $mod, $abs, $ceil, $floor, $round
-```
-
-### String Operators
-```javascript
-// String manipulation
-db.users.aggregate([
-  { $project: {
-    fullName: { $concat: ["$firstName", " ", "$lastName"] },
-    email: { $toLower: "$email" },
-    initials: { $concat: [
-      { $substr: ["$firstName", 0, 1] },
-      { $substr: ["$lastName", 0, 1] }
-    ]}
-  }}
-])
-
-// Other: $toUpper, $trim, $split, $substr, $regexMatch
-```
-
-### Date Operators
-```javascript
-// Date extraction
-db.events.aggregate([
-  { $project: {
-    event: 1,
-    year: { $year: "$timestamp" },
-    month: { $month: "$timestamp" },
-    day: { $dayOfMonth: "$timestamp" },
-    hour: { $hour: "$timestamp" },
-    dayOfWeek: { $dayOfWeek: "$timestamp" }
-  }}
-])
-
-// Date math
-db.events.aggregate([
-  { $project: {
-    event: 1,
-    expiresAt: { $add: ["$createdAt", 1000 * 60 * 60 * 24 * 30] }, // +30 days
-    ageInDays: { $divide: [
-      { $subtract: [new Date(), "$createdAt"] },
-      1000 * 60 * 60 * 24
-    ]}
-  }}
-])
-```
-
-### Array Operators
-```javascript
-// Array operations
-db.posts.aggregate([
-  { $project: {
-    title: 1,
-    tagCount: { $size: "$tags" },
-    firstTag: { $arrayElemAt: ["$tags", 0] },
-    lastTag: { $arrayElemAt: ["$tags", -1] },
-    hasMongoDBTag: { $in: ["mongodb", "$tags"] }
-  }}
-])
-
-// Array filtering
-db.posts.aggregate([
-  { $project: {
-    title: 1,
-    activeTags: {
-      $filter: {
-        input: "$tags",
-        as: "tag",
-        cond: { $ne: ["$$tag.status", "deprecated"] }
-      }
-    }
-  }}
-])
-```
-
-### Conditional Operators
-```javascript
-// $cond (ternary)
-db.products.aggregate([
-  { $project: {
-    name: 1,
-    status: {
-      $cond: {
-        if: { $gte: ["$stock", 10] },
-        then: "In Stock",
-        else: "Low Stock"
-      }
-    }
-  }}
-])
-
-// $switch (multiple conditions)
-db.orders.aggregate([
-  { $project: {
-    status: 1,
-    priority: {
-      $switch: {
-        branches: [
-          { case: { $gte: ["$total", 1000] }, then: "High" },
-          { case: { $gte: ["$total", 100] }, then: "Medium" }
-        ],
-        default: "Low"
-      }
-    }
-  }}
-])
-```
-
-## Advanced Patterns
-
-### Time-Based Aggregation
-```javascript
-// Daily sales
-db.orders.aggregate([
-  { $match: { orderDate: { $gte: startDate } } },
-  { $group: {
-    _id: {
-      year: { $year: "$orderDate" },
-      month: { $month: "$orderDate" },
-      day: { $dayOfMonth: "$orderDate" }
-    },
-    revenue: { $sum: "$total" },
-    orderCount: { $sum: 1 }
-  }},
-  { $sort: { "_id.year": 1, "_id.month": 1, "_id.day": 1 } }
-])
-```
-
-### Faceted Search
-```javascript
-// Multiple aggregations in one query
-db.products.aggregate([
-  { $match: { category: "electronics" } },
-  { $facet: {
-    priceRanges: [
-      { $bucket: {
-        groupBy: "$price",
-        boundaries: [0, 100, 500, 1000, 5000],
-        default: "5000+",
-        output: { count: { $sum: 1 } }
-      }}
-    ],
-    topBrands: [
-      { $group: { _id: "$brand", count: { $sum: 1 } } },
-      { $sort: { count: -1 } },
-      { $limit: 5 }
-    ],
-    avgPrice: [
-      { $group: { _id: null, avg: { $avg: "$price" } } }
-    ]
-  }}
-])
-```
-
-### Window Functions
-```javascript
-// Running totals and moving averages
-db.sales.aggregate([
-  { $setWindowFields: {
-    partitionBy: "$region",
-    sortBy: { date: 1 },
-    output: {
-      runningTotal: {
-        $sum: "$amount",
-        window: { documents: ["unbounded", "current"] }
-      },
-      movingAvg: {
-        $avg: "$amount",
-        window: { documents: [-7, 0] }  // Last 7 days
-      }
-    }
-  }}
-])
-```
-
-### Text Search with Aggregation
-```javascript
-// Full-text search (requires text index)
-db.articles.aggregate([
-  { $match: { $text: { $search: "mongodb database" } } },
-  { $addFields: { score: { $meta: "textScore" } } },
-  { $sort: { score: -1 } },
-  { $limit: 10 }
-])
-```
-
-### Geospatial Aggregation
-```javascript
-// Find nearby locations
-db.places.aggregate([
-  { $geoNear: {
-    near: { type: "Point", coordinates: [lon, lat] },
-    distanceField: "distance",
-    maxDistance: 5000,
-    spherical: true
-  }},
-  { $limit: 10 }
-])
-```
-
-## Performance Tips
-
-1. **$match early** - Filter documents before other stages
-2. **$project early** - Reduce document size
-3. **Index usage** - $match and $sort can use indexes (only at start)
-4. **$limit after $sort** - Reduce memory usage
-5. **Avoid $lookup** - Prefer embedded documents when possible
-6. **Use $facet sparingly** - Can be memory intensive
-7. **allowDiskUse** - Enable for large datasets
-```javascript
-db.collection.aggregate(pipeline, { allowDiskUse: true })
-```
-
-## Best Practices
-
-1. **Order stages efficiently** - $match → $project → $group → $sort → $limit
-2. **Use $expr carefully** - Can prevent index usage
-3. **Monitor memory** - Default limit: 100MB per stage
-4. **Test with explain** - Analyze pipeline performance
-```javascript
-db.collection.explain("executionStats").aggregate(pipeline)
-```
-5. **Break complex pipelines** - Use $out/$merge for intermediate results
-6. **Use $sample** - For random document selection
-7. **Leverage $addFields** - Cleaner than $project for adding fields