Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 70 ยท Aggregation pipeline

Working with Arrays in Pipelines

Learn how to flatten arrays with $unwind and reshape them with $map, $filter, $reduce, $size and $arrayElemAt inside MongoDB aggregation pipelines.

Arrays are one of the best features of documents, and one of the trickiest in aggregation. An order holds its line items in an array, a post holds its tags, a student holds a list of scores. To group, count or total across those elements you need tools that open arrays up. The pipeline gives you two families: the $unwind stage, which turns one document into many, and the array expression operators ($map, $filter, $reduce, $size, $arrayElemAt), which compute on an array while keeping the document in one piece.

This lesson assumes you know $group (Grouping with $group) and expressions (Expressions and Operators). The shell blocks show real MongoDB syntax. The TryIts run a small JavaScript stand-in that behaves like these operators on arrays of plain objects, so you can see the effect without a server.

Two ways to handle an array

$unwind One document per array element.
Array operators Compute inside one document.

Unwind changes the number of documents. Array operators do not.

1 / 2

$unwind: one document per element

$unwind takes the name of an array field and emits one copy of the document for every element, with the array replaced by that single element. An order with two items becomes two documents that share the same _id and customer.

JavaScript
db.orders.aggregate([
  { $unwind: "$items" },
  { $group: { _id: "$items.sku", unitsSold: { $sum: "$items.qty" } } },
  { $sort: { unitsSold: -1 } }
])

Note the $ before the field name: the argument is a field path. After the unwind, items is no longer an array but a single subdocument, so "$items.sku" reaches into it. This is the standard recipe for "total per element": unwind, then group.

Empty and missing arrays

By default $unwind drops any document whose array is empty, missing or null, because there is nothing to emit. That is often a silent bug: a customer with an empty cart vanishes from your report. The long form of the stage fixes it with preserveNullAndEmptyArrays:

JavaScript
{ $unwind: { path: "$items", preserveNullAndEmptyArrays: true } }

With that option the document is kept once. For an empty array the items field is removed from the output document; for a missing or null field the document passes through as it was. The long form also takes includeArrayIndex: "pos", which stores each element's zero-based position in a new field, handy for ranking elements in their original order. If the field holds a non-array value, $unwind treats it as a one-element array.

The first stand-in implements $unwind over an array of objects, runs the "units per SKU" report, and shows what happens to empty and missing arrays.

JS $unwind and preserveNullAndEmptyArrays

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

No output.

Customers Ana and Raj disappear from the default result and come back with the option. Use the option whenever "no elements" is a valid answer you still want to see.

Computing inside the array

Unwinding multiplies documents, which costs memory and time, and it forces you to regroup afterwards. If you only need a per-document answer (the best score of each student, the number of tags on each post), stay inside the document with array expressions. They work in $project, $addFields, $group and anywhere else an expression is allowed.

  • $size returns the length of an array. It raises an error if the value is not an array, so guard fields that might be missing with $ifNull or $isArray.
  • $arrayElemAt returns the element at an index. A negative index counts from the end (-1 is the last element). An index outside the array gives a missing value rather than an error.
  • $filter keeps the elements for which a condition is true. You name the loop variable with as and refer to it as "$$s" (two dollar signs mean "variable", one means "field").
  • $map builds a new array by applying an expression to each element.
  • $reduce folds an array into a single value. Inside in, "$$value" is the running result and "$$this" is the current element.
JavaScript
db.students.aggregate([
  { $project: {
      name: 1,
      passed:  { $filter: { input: "$scores", as: "s", cond: { $gte: ["$$s", 50] } } },
      curved:  { $map: { input: "$scores", as: "s", in: { $min: [100, { $add: ["$$s", 5] }] } } },
      total:   { $reduce: { input: "$scores", initialValue: 0, in: { $add: ["$$value", "$$this"] } } },
      count:   { $size: "$scores" },
      first:   { $arrayElemAt: ["$scores", 0] },
      last:    { $arrayElemAt: ["$scores", -1] }
  } }
])

Two shortcuts are worth knowing. $sum, $avg, $min and $max accept an array expression directly in $project and $addFields, so { $sum: "$scores" } totals the array without $reduce. And you can combine the tools: $size of a $filter result counts the matching elements, which is a common way to ask "how many scores were passing" per student.

The second stand-in recreates these operators as plain functions and applies them to the same pipeline as above.

JS $map, $filter, $reduce, $size, $arrayElemAt

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

No output.

Look at Omar: passed is an empty array, passedCount is 0, and the document is still there. Compare that with unwinding his scores and filtering, which would remove him entirely.

Choosing between them

Use $unwind when the elements themselves are the thing you want to group, sort or join: units per SKU, posts per tag, one row per line item in a report. Use array operators when the answer belongs to the parent document: counts, totals, filtered or transformed copies of its own array.

A good habit is to put a $match before the $unwind, so you only explode documents you need. Unwinding a million orders to look at one customer's items is the kind of mistake Aggregation Performance and Explain teaches you to avoid. Also watch for unwinding two arrays of the same document one after the other: you get every combination (their Cartesian product), so ten tags and ten colors give a hundred documents per product.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does { $unwind: "$items" } do to a document whose items array has three elements?

    $unwind outputs one copy of the document per array element, replacing the array with that element.
  2. 2. A customer has an empty items array and you run a default $unwind on items. What happens to that customer?

    By default documents with empty, null or missing arrays produce no output. Use preserveNullAndEmptyArrays: true to keep them.
  3. 3. Inside a $reduce, what do "$$value" and "$$this" refer to?

    $$value is the accumulated result so far and $$this is the element being processed. The initialValue seeds $$value.
  4. 4. You only need the number of passing scores per student, one result per student. Which approach fits best?

    Array operators compute inside the document, so no extra documents are created and no regrouping is needed.

Summary

  • $unwind emits one document per array element; follow it with $group for totals per element.
  • Empty, null or missing arrays vanish unless you set preserveNullAndEmptyArrays: true; includeArrayIndex records each element's position.
  • $size, $arrayElemAt, $filter, $map and $reduce compute inside a document without changing the document count.
  • Loop variables are written with two dollar signs ($$s, $$value, $$this); field paths use one.
  • $match before $unwind keeps the exploded stream small, and unwinding two arrays multiplies them.

Next, combine documents from two collections in Joining with $lookup.