Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Aggregation

Aggregation - $group, $unwind and $lookup

Summarize data with $group and accumulators, flatten arrays with $unwind, and join collections with $lookup in Mongoose aggregation - with runnable stand-ins for each stage.

The previous lesson covered stages that filter, sort and reshape single documents. This lesson covers the three stages that change the shape of the whole result: $group (many documents into one per key), $unwind (one document into many) and $lookup (a join against another collection). Together they answer most reporting questions.

If you have not seen pipelines yet, start with The aggregation pipeline basics.

$group: one output per key

$group needs an _id expression, the grouping key, and any number of accumulators that compute values over all documents sharing that key.

JavaScript
const perCustomer = await Order.aggregate([
  { $match: { status: 'paid' } },
  {
    $group: {
      _id: '$customer',          // the key
      orders: { $sum: 1 },       // count
      revenue: { $sum: '$amount' },
      biggest: { $max: '$amount' },
      average: { $avg: '$amount' },
    },
  },
]);

Common accumulators: $sum, $avg, $min, $max, $first, $last (depend on prior $sort), $push (collect all values into an array), $addToSet (collect unique values), and $count. A key of null groups everything into one document, which is how you compute a grand total. A compound key { year: { $year: '$createdAt' }, month: { $month: '$createdAt' } } groups by month.

Node.js $group with accumulators (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

$unwind: arrays into rows

Documents often contain arrays: an order has items, a post has tags. To group or count by array elements you first unwind: each element becomes its own document, with the other fields copied.

JavaScript
// Which tags are used most?
await Post.aggregate([
  { $unwind: '$tags' },
  { $group: { _id: '$tags', posts: { $sum: 1 } } },
  { $sort: { posts: -1 } },
]);

By default, documents with an empty or missing array disappear. Keep them with the long form: { $unwind: { path: '$tags', preserveNullAndEmptyArrays: true } }. Add includeArrayIndex: 'pos' to know each element's index.

Node.js $unwind then $group (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

$lookup: a left outer join

$lookup pulls matching documents from another collection and stores them in an array field. It is the aggregation counterpart of populate, executed inside the database.

JavaScript
const orders = await Order.aggregate([
  {
    $lookup: {
      from: 'customers',          // the COLLECTION name, not the model name
      localField: 'customer',     // field in orders
      foreignField: '_id',        // field in customers
      as: 'customerDoc',          // output array
    },
  },
  { $unwind: '$customerDoc' },    // one customer per order: flatten
]);

Details that trip people up:

  • from is the collection name (usually the lowercase plural, for example customers), not 'Customer'. Find it with Customer.collection.name.
  • The output is always an array, even for a single match; follow with $unwind (or $first) to get an object.
  • With no match, the array is empty; $unwind then drops the order unless you use preserveNullAndEmptyArrays.
  • The foreignField should be indexed (for _id it already is).
Node.js $lookup then $unwind (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Pipeline-style $lookup

The short form only joins on equality. The long form takes a sub-pipeline and let variables, letting you filter and limit the joined side:

JavaScript
{
  $lookup: {
    from: 'comments',
    let: { postId: '$_id' },
    pipeline: [
      { $match: { $expr: { $eq: ['$post', '$$postId'] }, approved: true } },
      { $sort: { createdAt: -1 } },
      { $limit: 3 },
      { $project: { text: 1, author: 1 } },
    ],
    as: 'latestComments',
  },
}

$$postId reads the variable defined in let; $expr lets a $match compare fields. This is how you express "the latest three approved comments for each post" in one round trip, something that populate needs perDocumentLimit and several queries for.

A complete report

Revenue per customer name, biggest first:

JavaScript
const report = await Order.aggregate([
  { $match: { status: 'paid' } },
  { $group: { _id: '$customer', revenue: { $sum: '$amount' }, orders: { $sum: 1 } } },
  { $lookup: { from: 'customers', localField: '_id', foreignField: '_id', as: 'c' } },
  { $unwind: '$c' },
  { $project: { _id: 0, name: '$c.name', revenue: 1, orders: 1 } },
  { $sort: { revenue: -1 } },
]);

Group first, then look up: you join once per customer instead of once per order. Ordering stages to shrink the stream before expensive stages is the main performance habit.

flowchart LR
  A["orders"] --> B["$match paid"] --> C["$group by customer"] --> D["$lookup customers"] --> E["$unwind"] --> F["$project name, revenue"] --> G["$sort"]

Group before joining to keep the join small.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does { $group: { _id: null, total: { $sum: '$amount' } } } compute?

    A constant (null) key puts all documents in one group, the usual way to compute overall totals.
  2. 2. A post has tags: []. After { $unwind: '$tags' } what happens to it?

    By default documents with an empty or missing array produce no output.
  3. 3. What type does the as field of $lookup always hold?

    Even a single match is wrapped in an array; use $unwind or $first to flatten.
  4. 4. What must from contain in $lookup?

    $lookup runs in the database, which only knows collection names.

Summary

  • $group collapses documents by a key and computes accumulators such as $sum, $avg, $push.
  • $unwind turns each array element into its own document; empty arrays vanish by default.
  • $lookup joins another collection into an array; from is the collection name.
  • The pipeline form of $lookup filters, sorts and limits the joined side.
  • Group before looking up so you join less data.

Next: Facets, buckets and pagination