Aggregation Pipeline Stages
- Stages
- Alphabetical Listing of Stages

Aggregation Pipeline Stages

In the db.collection.aggregate method anddb.aggregate method, pipeline stages appear in an array. Documents passthrough the stages in sequence.

Stages

db.collection.aggregate() Stages

All except the $out, $merge, and $geoNear stages canappear multiple times in a pipeline.

Note

For details on specific operator, including syntax and examples,click on the specific operator to go to its reference page.

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

Stage	Description
`$addFields`	Adds new fields to documents. Similar to`$project`, `$addFields` reshapes eachdocument in the stream; specifically, by adding new fields tooutput documents that contain both the existing fieldsfrom the input documents and the newly added fields.`$set` is an alias for `$addFields`.
`$bucket`	Categorizes incoming documents into groups, called buckets,based on a specified expression and bucket boundaries.
`$bucketAuto`	Categorizes incoming documents into a specific number ofgroups, called buckets, based on a specified expression.Bucket boundaries are automatically determined in an attemptto evenly distribute the documents into the specified numberof buckets.
`$collStats`	Returns statistics regarding a collection or view.
`$count`	Returns a count of the number of documents at this stage ofthe aggregation pipeline.
`$facet`	Processes multiple aggregation pipelines within a single stage on the same setof input documents. Enables the creation of multi-facetedaggregations capable of characterizing data across multipledimensions, or facets, in a single stage.
`$geoNear`	Returns an ordered stream of documents based on the proximity to ageospatial point. Incorporates the functionality of`$match`, `$sort`, and `$limit` forgeospatial data. The output documents include an additional distancefield and can include a location identifier field.
`$graphLookup`	Performs a recursive search on a collection. To each outputdocument, adds a new array field that contains the traversalresults of the recursive search for that document.
`$group`	Groups input documents by a specified identifier expressionand applies the accumulator expression(s), if specified, toeach group. Consumes all input documents and outputs onedocument per each distinct group. The output documents onlycontain the identifier field and, if specified, accumulatedfields.
`$indexStats`	Returns statistics regarding the use of each index for thecollection.
`$limit`	Passes the first n documents unmodified to the pipelinewhere n is the specified limit. For each input document,outputs either one document (for the first n documents) orzero documents (after the first n documents).
`$listSessions`	Lists all sessions that have been active long enough topropagate to the `system.sessions` collection.
`$lookup`	Performs a left outer join to another collection in thesame database to filter in documents from the “joined”collection for processing.
`$match`	Filters the document stream to allow only matching documentsto pass unmodified into the next pipeline stage.`$match` uses standard MongoDB queries. For eachinput document, outputs either one document (a match) or zerodocuments (no match).
`$merge`	Writes the resulting documents of the aggregation pipeline toa collection. The stage can incorporate (insert newdocuments, merge documents, replace documents, keep existingdocuments, fail the operation, process documents with acustom update pipeline) the results into an outputcollection. To use the `$merge` stage, it must bethe last stage in the pipeline.New in version 4.2.
`$out`	Writes the resulting documents of the aggregation pipeline toa collection. To use the `$out` stage, it must bethe last stage in the pipeline.
`$planCacheStats`	Returns plan cache information for acollection.
`$project`	Reshapes each document in the stream, such as by adding newfields or removing existing fields. For each input document,outputs one document.See also `$unset` for removing existing fields.
`$redact`	Reshapes each document in the stream by restricting thecontent for each document based on information stored in thedocuments themselves. Incorporates the functionality of`$project` and `$match`. Can be used toimplement field level redaction. For each input document,outputs either one or zero documents.
`$replaceRoot`	Replaces a document with the specified embedded document. Theoperation replaces all existing fields in the input document,including the `id` field. Specify a document embedded inthe input document to promote the embedded document to thetop level.`$replaceWith` is an alias for`$replaceRoot` stage.
`$replaceWith`	Replaces a document with the specified embedded document. Theoperation replaces all existing fields in the input document,including the `_id` field. Specify a document embedded inthe input document to promote the embedded document to thetop level.`$replaceWith` is an alias for`$replaceRoot` stage.
`$sample`	Randomly selects the specified number of documents from itsinput.
`$set`	Adds new fields to documents. Similar to`$project`, `$set` reshapes eachdocument in the stream; specifically, by adding new fields tooutput documents that contain both the existing fieldsfrom the input documents and the newly added fields.`$set` is an alias for `$addFields` stage.
`$skip`	Skips the first _n documents where n is the specified skipnumber and passes the remaining documents unmodified to thepipeline. For each input document, outputs either zerodocuments (for the first n documents) or one document (ifafter the first n documents).
`$sort`	Reorders the document stream by a specified sort key. Onlythe order changes; the documents remain unmodified. For eachinput document, outputs one document.
`$sortByCount`	Groups incoming documents based on the value of a specifiedexpression, then computes the count of documents in eachdistinct group.
`$unset`	Removes/excludes fields from documents.`$unset` is an alias for `$project` stagethat removes fields.
`$unwind`	Deconstructs an array field from the input documents tooutput a document for each element. Each output documentreplaces the array with an element value. For each inputdocument, outputs n documents where n is the number ofarray elements and can be zero for an empty array.

For aggregation expression operators to use in the pipeline stages, seeAggregation Pipeline Operators.

db.aggregate() Stages

Starting in version 3.6, MongoDB also provides thedb.aggregate method:

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

The following stages use the db.aggregate() method and notthe db.collection.aggregate() method.

Stage	Description
`$currentOp`	Returns information on active and/or dormant operations forthe MongoDB deployment.
`$listLocalSessions`	Lists all active sessions recently in use on the currentlyconnected `mongos` or `mongod`instance. These sessions may have not yet propagated to the`system.sessions` collection.

Stages Available for Updates

Starting in MongoDB 4.2, you can use the aggregation pipeline forupdates in:

Command	`mongo` Shell Methods
`findAndModify`	`db.collection.findAndModify()db.collection.findOneAndUpdate()`
`update`	`db.collection.updateOne()db.collection.updateMany()db.collection.update()`

For the updates, the pipeline can consist of the following stages:

$addFields and its alias $set
$project and its alias $unset
$replaceRoot and its alias $replaceWith.

Alphabetical Listing of Stages

Name	Description
`$addFields`	Adds new fields to documents. Outputs documents thatcontain all existing fields from the input documents and newlyadded fields.
`$bucket`	Categorizes incoming documents into groups, called buckets, based ona specified expression and bucket boundaries.
`$bucketAuto`	Categorizes incoming documents into a specific number of groups,called buckets, based on a specified expression. Bucketboundaries are automatically determined in an attempt to evenlydistribute the documents into the specified number of buckets.
`$collStats`	Returns statistics regarding a collection or view.
`$count`	Returns a count of the number of documents at this stage of theaggregation pipeline.
`$currentOp`	Returns information on active and/or dormant operations for theMongoDB deployment. To run, use the `db.aggregate()` method.
`$facet`	Processes multiple aggregation pipelines within a single stage on the same set ofinput documents. Enables the creation of multi-facetedaggregations capable of characterizing data across multipledimensions, or facets, in a single stage.
`$geoNear`	Returns an ordered stream of documents based on the proximity to ageospatial point. Incorporates the functionality of`$match`, `$sort`, and `$limit` forgeospatial data. The output documents include an additional distancefield and can include a location identifier field.
`$graphLookup`	Performs a recursive search on a collection. To each output document,adds a new array field that contains the traversal results of therecursive search for that document.
`$group`	Groups input documents by a specified identifier expression andapplies the accumulator expression(s), if specified, to each group.Consumes all input documents and outputs one document per eachdistinct group. The output documents only contain the identifierfield and, if specified, accumulated fields.
`$indexStats`	Returns statistics regarding the use of each index for thecollection.
`$limit`	Passes the first n documents unmodified to the pipelinewhere n is the specified limit. For each input document, outputseither one document (for the first n documents) or zero documents(after the first n documents).
`$listLocalSessions`	Lists all active sessions recently in use on the currently connected`mongos` or `mongod` instance. These sessions mayhave not yet propagated to the `system.sessions` collection.
`$listSessions`	Lists all sessions that have been active long enough to propagate tothe `system.sessions` collection.
`$lookup`	Performs a left outer join to another collection in the same_database to filter in documents from the “joined” collection forprocessing.
`$match`	Filters the document stream to allow only matching documentsto pass unmodified into the next pipeline stage. `$match`uses standard MongoDB queries. For each input document, outputseither one document (a match) or zero documents (no match).
`$merge`	Writes the resulting documents of the aggregation pipeline to acollection. The stage can incorporate (insert new documents, mergedocuments, replace documents, keep existing documents, fail theoperation, process documents with a custom update pipeline) theresults into an output collection. To use the `$merge`stage, it must be the last stage in the pipeline.New in version 4.2.
`$out`	Writes the resulting documents of the aggregation pipeline to acollection. To use the `$out` stage, it must be the laststage in the pipeline.
`$planCacheStats`	Returns plan cache information for acollection.
`$project`	Reshapes each document in the stream, such as by adding new fields orremoving existing fields. For each input document, outputs onedocument.
`$redact`	Reshapes each document in the stream by restricting the content foreach document based on information stored in the documentsthemselves. Incorporates the functionality of `$project`and `$match`. Can be used to implement field levelredaction. For each input document, outputs either one or zerodocuments.
`$replaceRoot`	Replaces a document with the specified embedded document. Theoperation replaces all existing fields in the input document,including the `_id` field. Specify a document embedded in theinput document to promote the embedded document to the top level.
`$replaceWith`	Replaces a document with the specified embedded document. Theoperation replaces all existing fields in the input document,including the `_id` field. Specify a document embedded in theinput document to promote the embedded document to the top level.Alias for `$replaceRoot`.
`$sample`	Randomly selects the specified number of documents from its input.
`$set`	Adds new fields to documents. Outputs documents thatcontain all existing fields from the input documents and newlyadded fields.Alias for `$addFields`.
`$skip`	Skips the first _n documents where n is the specified skip numberand passes the remaining documents unmodified to the pipeline. Foreach input document, outputs either zero documents (for the first n_documents) or one document (if after the first _n documents).
`$sort`	Reorders the document stream by a specified sort key. Only the orderchanges; the documents remain unmodified. For each input document,outputs one document.
`$sortByCount`	Groups incoming documents based on the value of a specifiedexpression, then computes the count of documents in each distinctgroup.
`$unset`	Removes/exludes fields from documents.Alias for `$project` stage that excludes/removes fields.
`$unwind`	Deconstructs an array field from the input documents to output adocument for each element. Each output document replaces the arraywith an element value. For each input document, outputs n documentswhere n is the number of array elements and can be zero for anempty array.