Docs Menu
Docs Home
/
MongoDB Manual

Aggregation

On this page

  • Aggregation Pipelines
  • Single Purpose Aggregation Operations
  • Map-Reduce
  • Additional Features and Behaviors
  • Learn More

Aggregation operations process multiple documents and return computed results. You can use aggregation operations to:

  • Group values from multiple documents together.

  • Perform operations on the grouped data to return a single result.

  • Analyze data changes over time.

To perform aggregation operations, you can use:

You can run aggregation pipelines in the UI for deployments hosted in MongoDB Atlas.

Aggregation Pipelines

An aggregation pipeline consists of one or more stages that process documents:

  • Each stage performs an operation on the input documents. For example, a stage can filter documents, group documents, and calculate values.

  • The documents that are output from one stage are input to the next stage.

  • An aggregation pipeline can return results for groups of documents. For example, return the total, average, maximum, and minimum values.

Starting in MongoDB 4.2, you can update documents with an aggregation pipeline if you use the stages shown in Updates with Aggregation Pipeline.

Note

Aggregation pipelines run with the db.collection.aggregate() method do not modify documents in a collection, unless the pipeline contains a $merge or $out stage.

Aggregation Pipeline Example

The following aggregation pipeline example contains two stages and returns the total quantity of urgent orders for each product:

db.orders.aggregate( [
   { $match: { status: "urgent" } },
   { $group: { _id: "$productName", sumQuantity: { $sum: "$quantity" } } }
] )

The $match stage:

  • Filters the documents to those with a status of urgent.

  • Outputs the filtered documents to the $group stage.

The $group stage:

  • Groups the input documents by productName.

  • Uses $sum to calculate the total quantity for each productName, which is stored in the sumQuantity field returned by the aggregation pipeline.

For a runnable example, see Complete Aggregation Pipeline Example.

Aggregation Pipeline Stages and Operations

The most basic pipeline stages provide filters that operate like queries and document transformations that modify the form of the output document.

Other pipeline operations provide tools for grouping and sorting documents by specific field or fields as well as tools for aggregating the contents of arrays, including arrays of documents. In addition, pipeline stages can use operators for tasks such as calculating the average or concatenating a string.

The pipeline provides efficient data aggregation using native operations within MongoDB, and is the preferred method for data aggregation in MongoDB.

The aggregation pipeline can operate on a sharded collection.

The aggregation pipeline can use indexes to improve its performance during some of its stages. In addition, the aggregation pipeline has an internal optimization phase. See Pipeline Operators and Indexes and Aggregation Pipeline Optimization for details.

Single Purpose Aggregation Operations

MongoDB also provides db.collection.estimatedDocumentCount(), db.collection.count() and db.collection.distinct().

All of these operations aggregate documents from a single collection. While these operations provide simple access to common aggregation processes, they lack the flexibility and capabilities of an aggregation pipeline.

Diagram of the annotated distinct operation.

The single purpose aggregation methods are simple but lack the capabilities of an aggregation pipeline.

Map-Reduce

An aggregation pipeline provides better performance and usability than a map-reduce operation.

Map-reduce operations can be rewritten using aggregation pipeline operators, such as $group, $merge, and others.

For map-reduce operations that require custom functionality, MongoDB provides the $accumulator and $function aggregation operators starting in version 4.4. Use these operators to define custom aggregation expressions in JavaScript.

For examples of aggregation pipeline alternatives to map-reduce operations, see Map-Reduce to Aggregation Pipeline and Map-Reduce Examples.

Additional Features and Behaviors

For a feature comparison of the aggregation pipeline, map-reduce, and the special group functionality, see Aggregation Commands Comparison.

Learn More

Practical MongoDB Aggregations E-Book

For more information on aggregations, read the Practical MongoDB Aggregations e-book.

Back

Tailable Cursors

Next

Aggregation Pipeline