> This page location: /docs.md > /docs/development.md > /docs/manual/reference/mql.md

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

# Aggregation Stages

In the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) and [`db.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#mongodb-method-db.aggregate) methods, [pipeline](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline) stages appear in an array. Documents pass through the stages in sequence. In the Atlas UI, arrange pipeline stages with the [aggregation pipeline builder.](https://www.mongodb.com/docs/atlas/atlas-ui/create-agg-pipeline.md#std-label-atlas-ui-agg-pipeline)

## db.collection.aggregate() Stages

All stages except the [`$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), [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear), [`$changeStream`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestream.md#mongodb-pipeline-pipe.-changeStream), and [`$changeStreamSplitLargeEvent`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestreamsplitlargeevent.md#mongodb-pipeline-pipe.-changeStreamSplitLargeEvent) stages can appear multiple times in a pipeline.

**Note:**

For details on a specific command, including syntax and examples, click on the link to the command's reference page.

```javascript
db.collection.aggregate( [ { <stage> }, ... ] )
```

**Core Stages**

Stages that filter, reshape, group, and combine documents in the aggregation pipeline.

| Stage | Description |
| --- | --- |
| [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) | Adds new fields to documents. Similar to [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project), [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) reshapes each document in the stream; specifically, by adding new fields to output documents that contain both the existing fields from the input documents and the newly added fields. [`$set`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set.md#mongodb-pipeline-pipe.-set) is an alias for [`$addFields`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) |
| [`$bucket`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucket.md#mongodb-pipeline-pipe.-bucket) | Categorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries. |
| [`$bucketAuto`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucketauto.md#mongodb-pipeline-pipe.-bucketAuto) | Categorizes incoming documents into a specific number of groups, called buckets, based on a specified expression. Bucket boundaries are automatically determined in an attempt to evenly distribute the documents into the specified number of buckets. |
| [`$count`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/count.md#mongodb-pipeline-pipe.-count) | Returns a count of the number of documents at this stage of the aggregation pipeline. Distinct from the [`$count`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/count-accumulator.md#mongodb-group-grp.-count) aggregation accumulator. |
| [`$densify`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify.md#mongodb-pipeline-pipe.-densify) | Creates new documents in a sequence of documents where certain values in a field are missing. |
| [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) | Returns literal documents from input expressions. |
| [`$facet`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet.md#mongodb-pipeline-pipe.-facet) | Processes multiple [aggregation pipelines](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline) within a single stage on the same set of input documents. Enables the creation of multi-faceted aggregations capable of characterizing data across multiple dimensions, or facets, in a single stage. |
| [`$fill`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill.md#mongodb-pipeline-pipe.-fill) | Populates `null` and missing field values within documents. |
| [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) | Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match), [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort), and [`$limit`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit) for geospatial data. The output documents include an additional distance field and can include a location identifier field. |
| [`$graphLookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphlookup.md#mongodb-pipeline-pipe.-graphLookup) | Performs a recursive search on a collection. To each output document, adds a new array field that contains the traversal results of the recursive search for that document. |
| [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) | Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields. |
| [`$limit`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit) | Passes the first *n* documents unmodified to the pipeline where *n* is the specified limit. For each input document, outputs either one document (for the first *n* documents) or zero documents (after the first *n* documents). |
| [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) | Performs a left outer join to another collection or view in the *same* database to filter in documents from the "joined" collection or view for processing. |
| [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) | Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match). |
| [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) | Writes the resulting documents of the aggregation pipeline to a collection. The stage can incorporate (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom update pipeline) the results into an output collection. To use the [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) stage, it must be the last stage in the pipeline. |
| [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) | Writes the resulting documents of the aggregation pipeline to a collection. To use the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage, it must be the last stage in the pipeline. |
| [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) | Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document. See also [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) for removing existing fields. |
| [`$redact`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact.md#mongodb-pipeline-pipe.-redact) | Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) and [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match). Can be used to implement field level redaction. For each input document, outputs either one or zero documents. |
| [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) | Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the `_id` field. Specify a document embedded in the input document to promote the embedded document to the top level. [`$replaceWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replacewith.md#mongodb-pipeline-pipe.-replaceWith) is an alias for [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) stage. |
| [`$replaceWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replacewith.md#mongodb-pipeline-pipe.-replaceWith) | Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the `_id` field. Specify a document embedded in the input document to promote the embedded document to the top level. [`$replaceWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replacewith.md#mongodb-pipeline-pipe.-replaceWith) is an alias for [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) stage. |
| [`$sample`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-sample) | Randomly selects the specified number of documents from its input. |
| [`$set`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set.md#mongodb-pipeline-pipe.-set) | Adds new fields to documents. Similar to [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project), [`$set`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set.md#mongodb-pipeline-pipe.-set) reshapes each document in the stream; specifically, by adding new fields to output documents that contain both the existing fields from the input documents and the newly added fields. [`$set`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set.md#mongodb-pipeline-pipe.-set) is an alias for [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) stage. |
| [`$setWindowFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/setwindowfields.md#mongodb-pipeline-pipe.-setWindowFields) | Groups documents into windows and applies one or more operators to the documents in each window. **New in version 5.0** |
| [`$skip`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip.md#mongodb-pipeline-pipe.-skip) | Skips the first *n* documents where *n* is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first *n* documents) or one document (if after the first *n* documents). |
| [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort) | Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document. |
| [`$sortByCount`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortbycount.md#mongodb-pipeline-pipe.-sortByCount) | Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. |
| [`$unionWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionwith.md#mongodb-pipeline-pipe.-unionWith) | Performs a union of two collections; i.e. combines pipeline results from two collections or views into a single result set. |
| [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) | Removes/excludes fields from documents. [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) is an alias for [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage that removes fields. |
| [`$unwind`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind.md#mongodb-pipeline-pipe.-unwind) | Deconstructs an array field from the input documents to output a document for *each* element. Each output document replaces the array with an element value. For each input document, outputs *n* documents where *n* is the number of array elements and can be zero for an empty array. |

**Language Extensions**

Stages that extend the aggregation language with specialized capabilities, such as Atlas Search and change streams.

| Stage | Description |
| --- | --- |
| [`$changeStream`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestream.md#mongodb-pipeline-pipe.-changeStream) | Returns a [Change Stream](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) cursor for the collection.  This stage can only occur once in an aggregation pipeline and it must occur as the first stage. |
| [`$changeStreamSplitLargeEvent`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changestreamsplitlargeevent.md#mongodb-pipeline-pipe.-changeStreamSplitLargeEvent) | Splits large [change stream](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) events that exceed 16 MB into smaller fragments returned in a change stream cursor. You can only use `$changeStreamSplitLargeEvent` in a `$changeStream` pipeline and it must be the final stage in the pipeline. |
| [`$rankFusion`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/rankfusion.md#mongodb-pipeline-pipe.-rankFusion) | Combines the results of input pipelines that rank documents. `$rankFusion` de-duplicates input pipeline results and uses the [Reciprocal Rank Fusion](https://www.mongodb.com/docs/manual/reference/operator/aggregation/rankfusion.md#std-label-rankFusion-rrf) algorithm to create a final document ranking. |
| [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) | Performs a full-text search of the field or fields in a collection. To learn more, see [MongoDB Search Aggregation Pipeline Stages.](https://www.mongodb.com/docs/atlas/reference/atlas-search/query-syntax/) |
| [`$searchMeta`](https://www.mongodb.com/docs/search/query/aggregation-stages/searchMeta.md#mongodb-pipeline-pipe.-searchMeta) | Returns different types of metadata result documents for the [MongoDB Search](https://www.mongodb.com/docs/atlas/atlas-search/) query against an [Atlas](https://www.mongodb.com/docs/atlas/reference/atlas-search/query-syntax/) collection. To learn more, see [MongoDB Search Aggregation Pipeline Stages.](https://www.mongodb.com/docs/atlas/reference/atlas-search/query-syntax/) |
| [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch) | Performs an ANN (Approximate Nearest Neighbor) or ENN (Exact Nearest Neighbor) search on a vector in the specified field of an [Atlas](https://www.mongodb.com/docs/atlas/reference/atlas-search/query-syntax/) collection. `$vectorSearch` is only available for MongoDB Atlas clusters running MongoDB v6.0.11 or higher, and is not available for self-managed deployments. **New in version 7.0.2** |

**Metadata Sources**

Stages that return metadata about the deployment, such as collection statistics, index information, and active operations.

| Stage | Description |
| --- | --- |
| [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats) | Returns statistics regarding a collection or view. |
| [`$currentOp`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentop.md#mongodb-pipeline-pipe.-currentOp) | Returns information on active and/or dormant operations for the MongoDB deployment. Uses the [`db.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#mongodb-method-db.aggregate) method instead of the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) method. |
| [`$indexStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#mongodb-pipeline-pipe.-indexStats) | Returns statistics regarding the use of each index for the collection. |
| [`$listClusterCatalog`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listclustercatalog.md#mongodb-pipeline-pipe.-listClusterCatalog) | Retrieves information for collections in a cluster, including names and creation options. |
| [`$listLocalSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listlocalsessions.md#mongodb-pipeline-pipe.-listLocalSessions) | Lists all active sessions recently in use on the currently connected [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) or [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance. These sessions may have not yet propagated to the `system.sessions` collection. Uses the [`db.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#mongodb-method-db.aggregate) method instead of the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) method. |
| [`$listSampledQueries`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsampledqueries.md#mongodb-pipeline-pipe.-listSampledQueries) | Lists sampled queries for all collections or a specific collection. |
| [`$listSearchIndexes`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsearchindexes.md#mongodb-pipeline-pipe.-listSearchIndexes) | Returns information about existing [MongoDB Search indexes](https://www.mongodb.com/docs/atlas/atlas-search/atlas-search-overview/#fts-indexes) on a specified collection or view. |
| [`$listSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsessions.md#mongodb-pipeline-pipe.-listSessions) | Lists all sessions that have been active long enough to propagate to the `system.sessions` collection. |
| [`$planCacheStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/plancachestats.md#mongodb-pipeline-pipe.-planCacheStats) | Returns [plan cache](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-query-plans-query-optimization) information for a collection. |
| [`$querySettings`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querysettings.md#mongodb-pipeline-pipe.-querySettings) | Returns query settings previously added with [`setQuerySettings`.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings) **New in version 8.0** |
| [`$queryStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querystats.md#mongodb-pipeline-pipe.-queryStats) | Returns runtime statistics for recorded queries. WARNING: The `$queryStats` aggregation stage is unsupported and is not guaranteed to be stable in a future release. Don't build functionality that relies on a specific output format of this stage, since the output may change in a future release. |
| [`$shardedDataDistribution`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardeddatadistribution.md#mongodb-pipeline-pipe.-shardedDataDistribution) | Returns information on the distribution of data in sharded collections. Uses the [`db.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#mongodb-method-db.aggregate) method instead of the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) method. **New in version 6.0.3** |

To learn about expressions that you can use in pipeline stages, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-operator-ref-landing)

## Stages Available for Updates

Use the aggregation pipeline for updates in:

| 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) |

For updates, the pipeline supports these stages:

- [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) and its alias [`$set`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set.md#mongodb-pipeline-pipe.-set)

- [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) and its alias [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset)

- [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) and its alias [`$replaceWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replacewith.md#mongodb-pipeline-pipe.-replaceWith)
