The Aggregation Pipeline

The MongoDB aggregation pipeline is a powerful framework for transforming and analysing data. A pipeline is an ordered array of stages, where each stage receives the documents output by the previous stage and passes its results to the next.

Basic Pipeline Structure

db.orders.aggregate([
  { $match:   { status: "completed" } },
  { $group:   { _id: "$customerId", total: { $sum: "$amount" } } },
  { $sort:    { total: -1 } },
  { $limit:   10 }
])

This pipeline finds completed orders, groups them by customer, sums the order amounts, and returns the top 10 customers by total spend.

Common Pipeline Stages

$match — filters documents (like a find filter). Place it as early as possible to reduce the number of documents processed downstream.

{ $match: { createdAt: { $gte: new Date("2024-01-01") } } }

$project — reshapes documents, including or excluding fields and computing new ones.

{ $project: { fullName: { $concat: ["$firstName", " ", "$lastName"] }, _id: 0 } }

$group — groups documents by an expression and computes aggregated values.

{ $group: { _id: "$category", count: { $sum: 1 }, avgPrice: { $avg: "$price" } } }

$sort — sorts documents. 1 for ascending, -1 for descending.

$limit** and **$limit∗∗and∗∗skip — control the number of documents returned (useful for pagination).

$unwind — deconstructs an array field, emitting one document per array element.

{ $unwind: "$tags" }

$lookup — performs a left outer join to another collection.

{
  $lookup: {
    from: "users",
    localField: "userId",
    foreignField: "_id",
    as: "userDetails"
  }
}

$addFields — adds new fields to documents without replacing the existing shape.

Aggregation Operators

Inside stages you can use arithmetic operators ($add**, **$add∗∗,∗∗subtract, $multiply**, **$multiply∗∗,∗∗divide), string operators ($concat**, **$concat∗∗,∗∗toLower, $substr**), date operators (**$substr∗∗),dateoperators(∗∗year, $month**, **$month∗∗,∗∗dayOfWeek), and conditional operators ($cond**, **$cond∗∗,∗∗ifNull).

{
  $project: {
    discountedPrice: { $multiply: ["$price", 0.9] },
    year: { $year: "$createdAt" }
  }
}

A Real-World Example

Sales report: monthly revenue for the current year.

db.orders.aggregate([
  { $match: { status: "paid", createdAt: { $gte: new Date("2024-01-01") } } },
  { $group: {
      _id: { $month: "$createdAt" },
      revenue: { $sum: "$total" },
      orderCount: { $sum: 1 }
  }},
  { $sort: { _id: 1 } }
])