MongoDB Aggregation Framework

This chapter follows Indexes and query performance in MongoDB. The aggregation framework processes documents through an ordered pipeline. Each stage transforms the stream passed to the next stage.

Start with $match early to reduce working set size, then $project, $group, or $lookup as needed.

Core stages

1
import { Db } from 'mongodb';
2

3
export async function revenueByCustomer(db: Db) {
4
  return db.collection('orders').aggregate<{ _id: string; total: number }>([
5
    { $match: { status: 'paid' } },
6
    { $group: { _id: '$customerId', total: { $sum: '$amount' } } },
7
    { $sort: { total: -1 } },
8
    { $limit: 50 },
9
  ]).toArray();
10
}

$lookup and $unwind

$lookup performs a left outer join to another collection:

1
[
2
  { $lookup: {
3
      from: 'products',
4
      localField: 'items.productId',
5
      foreignField: '_id',
6
      as: 'productDetails',
7
  }},
8
  { $unwind: '$productDetails' },
9
]

$unwind on a large array multiplies document count—filter before unwinding when possible.

$addFields and $cond

1
{
2
  $addFields: {
3
    discount: {
4
      $cond: [{ $gte: ['$qty', 10] }, 0.1, 0],
5
    },
6
    lineTotal: { $multiply: ['$price', '$qty'] },
7
  },
8
}

$facet

Run parallel sub-pipelines in one round trip—useful for dashboard tiles:

1
{
2
  $facet: {
3
    byStatus: [{ $group: { _id: '$status', count: { $sum: 1 } } }],
4
    topCustomers: [
5
      { $group: { _id: '$customerId', total: { $sum: '$amount' } } },
6
      { $sort: { total: -1 } },
7
      { $limit: 5 },
8
    ],
9
  },
10
}

$setWindowFields

Window functions compute running totals or ranks without collapsing groups:

1
{
2
  $setWindowFields: {
3
    partitionBy: '$customerId',
4
    sortBy: { createdAt: 1 },
5
    output: {
6
      runningTotal: { $sum: '$amount', window: { documents: ['unbounded', 'current'] } },
7
    },
8
  },
9
}

$merge, $out, and views

• $out replaces a collection with pipeline output (destructive).
• $merge upserts into a target collection with configurable on fields.
• Views are read-only aggregation definitions stored on the server:

1
db.createView('paidOrders', 'orders', [{ $match: { status: 'paid' } }])

Memory and allowDiskUse

Stages buffer up to 100 MB per stage by default. Large sorts or groups may require { allowDiskUse: true } on aggregate(). Prefer $match and indexes over huge in-memory sorts.

Avoid $function and $accumulator

Server-side JavaScript in $function and $accumulator is deprecated and disabled on many Atlas tiers. Express logic with native aggregation operators ($multiply, $switch, $reduce) instead.

Next: Pagination in MongoDB.