Aggregation Pipeline
$match, $group, $project, $sort, $lookup, and $unwind
Skills taught: mongodb.aggregation
The Aggregation Pipeline
MongoDB's aggregation pipeline processes documents through a series of stages. Each stage transforms the documents passing through it. The result of one stage becomes the input of the next — like a Unix pipe (cat | grep | sort | uniq -c).
// Basic structure: an array of stage objects
const results = await db.collection('orders').aggregate([
// Stage 1: Filter (like WHERE in SQL)
{ $match: { status: 'completed' } },
// Stage 2: Group and compute (like GROUP BY + SUM in SQL)
{
$group: {
_id: '$category', // group key
totalRevenue: { $sum: '$amount' },
orderCount: { $count: {} },
avgOrder: { $avg: '$amount' }
}
},
// Stage 3: Sort results
{ $sort: { totalRevenue: -1 } },
// Stage 4: Take top 10
{ $limit: 10 },
// Stage 5: Rename/reshape fields
{
$project: {
_id: 0,
category: '$_id',
totalRevenue: { $round: ['$totalRevenue', 2] },
orderCount: 1,
avgOrder: { $round: ['$avgOrder', 2] }
}
}
]).toArray();
Core Stages Reference
- $match
- Filters documents. Identical syntax to find(). Place $match early in the pipeline to use indexes and reduce documents flowing to later stages.
- $group
- Groups documents by a key and computes aggregates. Accumulators: $sum, $avg, $min, $max, $count, $first, $last, $push (array of values), $addToSet (unique array).
- $project
- Reshapes documents: include/exclude fields (like projection in find), rename fields, compute new fields with expressions, and transform values.
- $unwind
- Deconstructs an array field — produces one document per array element. Used to process arrays element-by-element, or after $lookup to convert the results array to a single embedded document.
// $group accumulators — the most important ones
await db.collection('sales').aggregate([
{ $match: { year: 2026 } },
{
$group: {
_id: '$region',
total: { $sum: '$amount' }, // sum of all amounts
count: { $count: {} }, // number of documents
average: { $avg: '$amount' }, // average
max: { $max: '$amount' }, // highest single sale
min: { $min: '$amount' }, // lowest single sale
products: { $addToSet: '$productId' }, // unique product IDs (array)
allAmts: { $push: '$amount' } // array of ALL amounts
}
}
]).toArray();
// Group by multiple fields — use an object as _id
await db.collection('sales').aggregate([
{
$group: {
_id: { year: { $year: '$date' }, region: '$region' },
total: { $sum: '$amount' }
}
},
{ $sort: { '_id.year': -1, total: -1 } }
]).toArray();
$project — Reshaping Documents
await db.collection('users').aggregate([
{
$project: {
// Include fields
name: 1,
email: 1,
// Exclude fields (can mix with inclusions ONLY for _id)
_id: 0,
password: 0,
// Rename a field
userId: '$_id',
// Compute a new field
fullName: { $concat: ['$firstName', ' ', '$lastName'] },
// Conditional expression
status: {
$cond: {
if: { $gt: ['$age', 18] },
then: 'adult',
else: 'minor'
}
},
// Date extraction
joinYear: { $year: '$createdAt' },
// String operations
emailDomain: {
$arrayElemAt: [{ $split: ['$email', '@'] }, 1]
}
}
}
]).toArray();
$unwind — Working with Arrays
// Source document:
// { _id: 1, product: 'A', tags: ['sale', 'new', 'featured'] }
// After $unwind: { tags: '$tags' } — produces 3 documents:
// { _id: 1, product: 'A', tags: 'sale' }
// { _id: 1, product: 'A', tags: 'new' }
// { _id: 1, product: 'A', tags: 'featured' }
// Count products per tag:
await products.aggregate([
{ $unwind: '$tags' },
{
$group: {
_id: '$tags',
count: { $count: {} }
}
},
{ $sort: { count: -1 } }
]).toArray();
// preserveNullAndEmptyArrays — keep docs with no/empty array
await products.aggregate([
{
$unwind: {
path: '$tags',
preserveNullAndEmptyArrays: true // keep products with no tags
}
}
]).toArray();
Real-World Example: Sales Dashboard
// Build a sales report: monthly revenue by category
const report = await db.collection('orders').aggregate([
// Filter: only completed orders in 2026
{
$match: {
status: 'completed',
placedAt: {
$gte: new Date('2026-01-01'),
$lt: new Date('2027-01-01')
}
}
},
// Join with products to get category
{
$lookup: {
from: 'products',
localField: 'productId',
foreignField: '_id',
as: 'product'
}
},
{ $unwind: '$product' },
// Group by month + category
{
$group: {
_id: {
month: { $month: '$placedAt' },
category: '$product.category'
},
revenue: { $sum: '$amount' },
orderCount: { $count: {} }
}
},
// Sort chronologically
{ $sort: { '_id.month': 1, revenue: -1 } },
// Final shape
{
$project: {
_id: 0,
month: '$_id.month',
category: '$_id.category',
revenue: { $round: ['$revenue', 2] },
orderCount: 1
}
}
]).toArray();
console.table(report);
Tip: Always put $match and $sort as early in the pipeline as possible. Placing $match first lets MongoDB use an index and reduces the number of documents processed by all subsequent stages. A $match after a $group cannot use any indexes.
Frequently Asked Questions
Can aggregation replace find()?
Yes — db.collection.aggregate([{ $match: query }]) is equivalent to find(query). But aggregation has more overhead, so use find() for simple queries. Use aggregation when you need grouping, joining, reshaping, or multi-stage transformations.
What is allowDiskUse in aggregation?
By default, $group and $sort stages are limited to 100MB of RAM. If your aggregation exceeds this, it throws an error. Pass { allowDiskUse: true } as the second argument to aggregate() to allow spilling to disk: db.collection.aggregate([...], { allowDiskUse: true }).
How do I debug a complex aggregation pipeline?
Build the pipeline incrementally — start with just $match, verify the results, then add $group, verify again. MongoDB Compass has a visual aggregation pipeline builder that shows the output of each stage interactively.