> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Aggregation Pipeline

An aggregation pipeline consists of one or more [stages](https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md#std-label-aggregation-pipeline-operator-reference) 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/filter.md#mongodb-expression-exp.-filter) documents, [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-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.](https://www.mongodb.com/docs/manual/tutorial/update-documents-with-aggregation-pipeline.md#std-label-updates-agg-pipeline)

**Note:**

Aggregation pipelines run with the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) method do not modify documents in a collection, unless the pipeline contains a [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) or [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage.

You can [run aggregation pipelines in the UI](https://www.mongodb.com/docs/atlas/atlas-ui/agg-pipeline/) for deployments hosted in [MongoDB Atlas.](https://www.mongodb.com/docs/atlas)

When you run aggregation pipelines on MongoDB Atlas deployments in the MongoDB Atlas UI, you can preview the results at each stage.

You can also use an LLM (large language model) to generate aggregation pipelines from natural language. To learn more, see [Natural Language to MongoDB Queries.](https://www.mongodb.com/docs/manual/natural-language-to-mongodb.md#std-label-natural-language-to-mongodb)

## Complete Aggregation Pipeline Examples

The [Complete Aggregation Pipeline Tutorials](https://www.mongodb.com/docs/manual/tutorial/aggregation-complete-examples.md#std-label-aggregation-complete-examples) section contains step-by-step tutorials for common aggregation tasks, with examples for MongoDB Shell and each of the [official MongoDB drivers.](https://www.mongodb.com/docs/drivers/)

## Run an Aggregation Pipeline

To run an aggregation pipeline, use:

- [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) or

- [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate)

## Additional Aggregation Pipeline Stage Details

An aggregation pipeline consists of one or more [stages](https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md#std-label-aggregation-pipeline-operator-reference) 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out), [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge), and [`$geoNear`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear)

For all aggregation stages, see [Aggregation Stages.](https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md#std-label-aggregation-pipeline-operator-reference)

### Expressions and Operators

In aggregation pipelines, expressions define how the stage processes each input document in the pipeline. For example, expressions can define which documents to include, how to reshape fields, or how to compute new values.

Some aggregation pipeline stages accept [expressions](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-expression). Operators calculate values based on input expressions.

In the MongoDB Query Language, you can build expressions from the following components:

| Component | Example |
| --- | --- |
| Constants | `3` |
| Operators | [`$add`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/add.md#mongodb-expression-exp.-add) |
| Field path expressions | `"$<path.to.field>"` |

For example, `{ $add: [ 3, "$inventory.total" ] }` is an expression that consists of the `$add` operator and two operands:

- The constant `3`

- The [field path expression](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-agg-quick-ref-field-paths) `"$inventory.total"`

The expression returns the result of adding 3 to the value at path `inventory.total` of the input document.

**Note: Accessing Array Element Indexes in $map, $filter, and $reduce**

MongoDB 8.3 improves access to array element indexes in [`$map`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/map.md#mongodb-expression-exp.-map), [`$filter`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/filter.md#mongodb-expression-exp.-filter), and [`$reduce`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/reduce.md#mongodb-expression-exp.-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`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.IDX) aggregation system variable to access the index of the current array element if you omit `arrayIndexAs`.

### Field Paths

[Field path](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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.

For more examples, see [Field Paths.](https://www.mongodb.com/docs/manual/core/field-paths.md#std-label-agg-field-paths)

## Update Documents Using an Aggregation Pipeline

To update documents with an aggregation pipeline, use:

| Command | `mongosh` Methods |
| --- | --- |
| [`findAndModify`](https://www.mongodb.com/docs/manual/reference/command/findandmodify.md#mongodb-dbcommand-dbcmd.findAndModify) | [db.collection.findOneAndUpdate()](https://www.mongodb.com/docs/manual/reference/method/db.collection.findoneandupdate.md#std-label-findOneAndUpdate-agg-pipeline)[db.collection.findAndModify()](https://www.mongodb.com/docs/manual/reference/method/db.collection.findandmodify.md#std-label-findAndModify-agg-pipeline) |
| [`update`](https://www.mongodb.com/docs/manual/reference/command/update.md#mongodb-dbcommand-dbcmd.update) | [db.collection.updateOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateone.md#std-label-updateOne-example-agg)[db.collection.updateMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updatemany.md#std-label-updateMany-example-agg) [Bulk.find.update()](https://www.mongodb.com/docs/manual/reference/method/bulk.find.update.md#std-label-example-bulk-find-update-agg)[Bulk.find.updateOne()](https://www.mongodb.com/docs/manual/reference/method/bulk.find.updateone.md#std-label-example-bulk-find-update-one-agg)[Bulk.find.upsert()](https://www.mongodb.com/docs/manual/reference/method/bulk.find.upsert.md#std-label-bulk-find-upsert-update-agg-example) |

## Other Considerations

### Aggregation Pipeline Limitations

For limits on value types and result size, see [Aggregation Pipeline Limits.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md#std-label-agg-pipeline-limits)

### Aggregation Pipelines and Sharded Collections

Aggregation pipelines support operations on sharded collections. See [Aggregation Pipeline and Sharded Collections.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-sharded-collections.md#std-label-aggregation-pipeline-sharded-collection)

**Important: Aggregation Pipelines as an Alternative to Map-Reduce**

Starting in MongoDB 5.0, [map-reduce](https://www.mongodb.com/docs/manual/core/map-reduce.md#std-label-map-reduce) is deprecated.

For examples of aggregation pipeline alternatives to map-reduce, see:

- [Map-Reduce to Aggregation Pipeline](https://www.mongodb.com/docs/manual/reference/map-reduce-to-aggregation-pipeline.md#std-label-map-reduce-to-agg-pipeline)

- [Map-Reduce Examples](https://www.mongodb.com/docs/manual/tutorial/map-reduce-examples.md#std-label-map-reduce-examples)

## Learn More

To learn more about aggregation pipelines, see:

- [Expressions](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expression-operators)

- [Aggregation Stages](https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md#std-label-aggregation-pipeline-operator-reference)