MongoDB Aggregation

What Is MongoDB Aggregation?

MongoDB Aggregation is a framework for processing documents through a sequence of stages to filter, transform, group, calculate, and analyze data.

Use it when a normal query is not enough to produce the result you need.

Documents
    ↓
Aggregation Pipeline
    ↓
Filter
    ↓
Transform
    ↓
Group
    ↓
Sort
    ↓
Results

Aggregation = overall data-processing framework
Pipeline    = ordered sequence of stages
Stage       = one processing step

Why Use Aggregation?

Aggregation lets you combine several processing steps in one pipeline: filter, transform, calculate, group, sort, work with arrays, combine related collections, reshape data, and build reports or analytics.

db.sales.aggregate([
  {
    $match: {
      status: "completed"
    }
  }
])

How It Works

1. aggregate() starts a pipeline on the sales collection.
2. $match keeps only documents with status: "completed".
3. Those filtered documents become the pipeline result.

Aggregation Pipeline

An aggregation pipeline is an ordered sequence of stages. Each stage receives documents, processes them, and passes its output to the next stage.

db.sales.aggregate([
  {
    $match: {
      status: "completed"
    }
  },
  {
    $group: {
      _id: "$category",
      totalSales: {
        $sum: "$amount"
      }
    }
  },
  {
    $sort: {
      totalSales: -1
    }
  }
])

Documents
    ↓
  $match
    ↓
  $group
    ↓
  $sort
    ↓
 Results

How It Works

1. $match filters the documents.
2. $group groups the remaining documents.
3. $sum calculates a total inside $group (it is an accumulator in this example, not a pipeline stage).
4. $sort sorts the grouped results.
5. MongoDB returns the final documents.

Pipeline Stages

Each stage performs one specific operation. This table introduces common stages—not every stage MongoDB supports.

Aggregation Stage vs Expression

Keep these concepts separate: a stage is a pipeline step; an expression calculates or produces a value inside a stage.

Stage

{
  $match: {
    status: "completed"
  }
}

Expression

{
  $project: {
    total: {
      $add: ["$price", "$tax"]
    }
  }
}

Pipeline
   |
   +-- Stage
   |     |
   |     +-- may contain expressions
   |
   +-- Stage
         |
         +-- may contain expressions

$match is the stage. $add is an expression used inside $project. Browse more expressions in MongoDB Operators.

Where Do Accumulators Fit?

Accumulators calculate values from multiple input values or documents in aggregation contexts. They are not the same topic as Aggregation itself.

{
  $group: {
    _id: "$category",
    total: {
      $sum: "$amount"
    },
    average: {
      $avg: "$amount"
    }
  }
}

Aggregation
     ↓
Pipeline
     ↓
$group Stage
     ↓
Accumulators
 ┌───────────────┐
 │ $sum          │
 │ $avg          │
 └───────────────┘

• $group is an aggregation stage.
• $sum and $avg are accumulators in this example.
• The pipeline contains the stage; the accumulators calculate values within that stage.

Learn more about MongoDB Accumulators →

Pseudocode

Read documents
      ↓
Run Stage 1
      ↓
Pass results to Stage 2
      ↓
Run Stage 2
      ↓
Pass results to Stage 3
      ↓
Return final results

FOR each pipeline stage
    process the current documents
    pass the result to the next stage
RETURN final documents

$match

$match filters documents so only matching ones continue through the pipeline.

db.orders.aggregate([
  {
    $match: {
      status: "completed"
    }
  }
])

How It Works

1. MongoDB examines each input document.
2. Documents with status: "completed" pass through.
3. Other documents leave the pipeline stream.

$project

$project selects or reshapes fields.

db.products.aggregate([
  {
    $project: {
      name: 1,
      price: 1
    }
  }
])

How It Works

1. MongoDB processes each document.
2. Only the requested fields are included in the output (plus _id unless excluded).
3. The pipeline continues with the reshaped documents.

$set

$set adds or modifies fields. Expressions inside it calculate new values.

db.products.aggregate([
  {
    $set: {
      discountedPrice: {
        $multiply: ["$price", 0.9]
      }
    }
  }
])

How It Works

1. $set is the stage that adds or updates a field.
2. $multiply is the expression that computes price × 0.9.
3. The new discountedPrice field is passed to later stages.

$group

$group combines documents that share a grouping key. Accumulators can calculate values for each group.

db.sales.aggregate([
  {
    $group: {
      _id: "$category",
      totalSales: {
        $sum: "$amount"
      }
    }
  }
])

How It Works

1. Documents are grouped by category (_id is the grouping key).
2. Each category becomes one group.
3. $sum adds amount values inside that group (accumulator, not a stage).
4. One output document is produced per group.

For accumulator operators and patterns, see MongoDB Accumulators.

$sort

$sort orders documents. Use 1 for ascending and -1 for descending.

db.products.aggregate([
  {
    $sort: {
      price: -1
    }
  }
])

How It Works

1. Documents reaching $sort are ordered by price.
2. -1 puts higher prices first.
3. Sorted documents continue to the next stage.

$limit and $skip

$limit keeps only the first N documents that reach it. $skip discards the first N documents—useful for simple pagination patterns.

db.products.aggregate([
  {
    $sort: {
      price: -1
    }
  },
  {
    $limit: 5
  }
])

How It Works

1. $sort orders products by price (highest first).
2. $limit: 5 keeps only the first five sorted documents.

db.products.aggregate([
  {
    $skip: 10
  },
  {
    $limit: 10
  }
])

How It Works

1. $skip: 10 drops the first 10 documents.
2. $limit: 10 keeps the next 10—a basic page-style window.
3. For very large collections, other pagination strategies may scale better than large skips.

$unwind

$unwind expands an array field so each element becomes its own pipeline document.

{
  name: "Laptop",
  tags: ["computer", "electronics"]
}

{
  $unwind: "$tags"
}

One document
     ↓
  $unwind
     ↓
Multiple documents

{ name: "Laptop", tags: "computer" }
{ name: "Laptop", tags: "electronics" }

How It Works

1. MongoDB reads the tags array.
2. Each array element becomes a separate document in the stream.
3. Other fields (like name) are copied onto each output document.

$lookup

$lookup performs a left outer join with another collection in the same database. Matching documents are added as an array field.

orders
   |
   v
$lookup
   |
   v
customers
   |
   v
combined result
(joined docs in an array field)

db.orders.aggregate([
  {
    $lookup: {
      from: "customers",
      localField: "customerId",
      foreignField: "_id",
      as: "customer"
    }
  }
])

How It Works

1. For each order, MongoDB looks up matching customers.
2. Matches are placed in the customer array field.
3. Orders without matches still continue, with an empty array.

Worked Walkthrough — Sales by Category

Group sales by category, total the amounts, then sort highest first.

db.sales.insertMany([
  { product: "Laptop", category: "Electronics", amount: 1000 },
  { product: "Mouse",  category: "Electronics", amount: 50 },
  { product: "Chair",  category: "Furniture",   amount: 200 },
  { product: "Desk",   category: "Furniture",   amount: 400 }
])

db.sales.aggregate([
  {
    $group: {
      _id: "$category",
      totalSales: {
        $sum: "$amount"
      }
    }
  },
  {
    $sort: {
      totalSales: -1
    }
  }
])

[
  { _id: "Electronics", totalSales: 1050 },
  { _id: "Furniture", totalSales: 600 }
]

How It Works

1. MongoDB reads the sales documents.
2. $group creates a group for each category.
3. $sum adds amount values inside each group (accumulator in the aggregation pipeline).
4. $sort orders groups by totalSales descending.
5. MongoDB returns the final grouped documents.

Multiple Stages Together

A typical report pipeline filters first, then groups, sorts, and limits.

db.sales.aggregate([
  {
    $match: {
      status: "completed"
    }
  },
  {
    $group: {
      _id: "$category",
      totalSales: {
        $sum: "$amount"
      }
    }
  },
  {
    $sort: {
      totalSales: -1
    }
  },
  {
    $limit: 5
  }
])

All Sales
   ↓
$match
   ↓
Completed Sales
   ↓
$group
   ↓
Category Totals
   ↓
$sort
   ↓
Highest First
   ↓
$limit
   ↓
Top 5

How It Works

1. $match keeps completed sales only.
2. $group totals amount per category.
3. $sort puts the largest totals first.
4. $limit returns only the top 5 groups.

Aggregation vs find()

Aggregation does not replace find(). Use the simplest operation that solves the problem.

Pipeline Order & Filtering Early

Stage order matters. Changing order can change the result, how many documents pass between stages, and how much work the pipeline does.

db.sales.aggregate([
  { $match: { status: "completed" } },
  { $group: { _id: "$category", totalSales: { $sum: "$amount" } } },
  { $sort: { totalSales: -1 } }
])

$match → $group → $sort

Filtering early often reduces later work—but $match is not required to be first in every pipeline, and MongoDB's optimizer can reorder some operations when it is safe to do so.

Many Documents
      ↓
   $match
      ↓
Fewer Documents
      ↓
$group / $sort / ...

Arrays, joins, and output

• Arrays: inspect array fields with expressions, or use $unwind to turn elements into separate documents.
• Multiple collections: $lookup combines related data; joined matches usually arrive as an array field.
• Output: most pipelines return a result cursor. $out and $merge can write results to a collection.

Performance Notes

Avoid absolute claims. Filtering can reduce work, but it does not guarantee a fast pipeline by itself.

Cheat Sheet

Key Takeaways