An aggregation pipeline consists of one or more stages that process documents. These documents can come from a collection, a view, or a specially designed stage.
Each stage performs an operation on the input documents. For example, a stage
can $filter documents, $group documents, and calculate
values. The documents that a stage outputs are then passed to the next stage in
the pipeline.
An aggregation pipeline can return results for groups of documents. You can also update documents with an aggregation pipeline using 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.
You can run aggregation pipelines in the UI for deployments hosted in MongoDB Atlas.
When you run aggregation pipelines on MongoDB Atlas deployments in the MongoDB Atlas UI, you can preview the results at each stage.
Complete Aggregation Pipeline Examples
The Complete Aggregation Pipeline Tutorials section contains step-by-step tutorials for common aggregation tasks, with examples for MongoDB Shell and each of the official MongoDB drivers.
Additional Aggregation Pipeline Stage Details
An aggregation pipeline consists of one or more stages that process documents:
A stage does not need to output one document for every input document. Some stages produce new documents or filter documents out.
The same stage can appear multiple times in a pipeline, except for
$out,$merge, and$geoNear.
For all aggregation stages, see Aggregation Stages.
Expressions and Operators
Some aggregation pipeline stages accept expressions. Operators calculate values based on input expressions.
In the MongoDB Query Language, you can build expressions from the following components:
Component | Example |
|---|---|
Constants |
|
Operators | |
Field path expressions |
|
For example, { $add: [ 3, "$inventory.total" ] } is an expression
that consists of the $add operator and two operands:
The constant
3The field path expression
"$inventory.total"
The expression returns the result of adding 3 to the value at path
inventory.total of the input document.
Field Paths
Field path expressions access fields in input
documents. Prefix the field name with a dollar sign $. For example,
"$user" references the user field, and "$user.name"
references the embedded user.name field.
"$<field>" is equivalent to "$$CURRENT.<field>", where
CURRENT is a system variable that defaults to the root of
the current object unless a stage specifies otherwise.
For more examples, see Field Paths.
Run an Aggregation Pipeline
To run an aggregation pipeline, use:
Update Documents Using an Aggregation Pipeline
To update documents with an aggregation pipeline, use:
Other Considerations
Aggregation Pipeline Limitations
For limits on value types and result size, see Aggregation Pipeline Limits.
Aggregation Pipelines and Sharded Collections
Aggregation pipelines support operations on sharded collections. See Aggregation Pipeline and Sharded Collections.
Aggregation Pipelines as an Alternative to Map-Reduce
Starting in MongoDB 5.0, map-reduce is deprecated:
Instead of map-reduce, you should use an aggregation pipeline. Aggregation pipelines provide better performance and usability than map-reduce.
You can rewrite map-reduce operations using aggregation pipeline stages, such as
$group,$merge, and others.For map-reduce operations that require custom functionality, you can use the
$accumulatorand$functionaggregation operators. You can use those operators to define custom aggregation expressions in JavaScript.
For examples of aggregation pipeline alternatives to map-reduce, see:
Accessing Array Element Indexes in $map, $filter, and $reduce
MongoDB 8.3 improves access to array element indexes in
$map, $filter, and $reduce
aggregation expressions. You can use the new arrayIndexAs field to
set a variable to store the index of an array element. You can also use
the new $$IDX aggregation system variable to access
the index of the current array element if you omit arrayIndexAs.
Learn More
To learn more about aggregation pipelines, see: