Database Manual / Reference / Query Language

Aggregation Stages聚合阶段

In the db.collection.aggregate() method and db.aggregate() method, pipeline stages appear in an array. 在db.collection.aggregate()方法和db.aggregate()方法中，管道阶段以数组的形式出现。In the Atlas UI, you can arrange pipeline stages using the aggregation pipeline builder. 在Atlas UI中，您可以使用聚合管道生成器来排列管道阶段。Documents pass through the stages in sequence.文件按顺序通过各个阶段。

Compatibility兼容性

You can use pipeline stages for deployments hosted in the following environments:您可以将管道阶段用于在以下环境中托管的部署：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务
  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

db.collection.aggregate() Stages阶段

All stages except the $out, $merge, $geoNear, $changeStream, and $changeStreamSplitLargeEvent stages can appear multiple times in a pipeline.除$out、$merge、$geoNear、$changeStream和$changeStreamSplitLargeEvent阶段外，所有阶段都可以在管道中多次出现。

Note

For details on a specific command, including syntax and examples, click on the link to the command's reference page.有关特定命令的详细信息，包括语法和示例，请单击指向该命令参考页面的链接。

db.collection.aggregate( [ { <stage> }, ... ] )
Stage阶段Description描述
$addFieldsAdds new fields to documents. Similar to $project, $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.向文档中添加新字段。与$project类似，$addFields会重塑流中的每个文档；具体来说，通过向输出文档添加新字段，这些字段既包含输入文档中的现有字段，也包含新添加的字段。
$set is an alias for $addFields.是$addFields的别名。
$bucketCategorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries.根据指定的表达式和桶边界将传入文档分类到称为桶的组中。
$bucketAutoCategorizes 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.桶边界是自动确定的，试图将文档均匀地分布到指定数量的桶中。
$changeStreamReturns a Change Stream cursor for the collection. This stage can only occur once in an aggregation pipeline and it must occur as the first stage.返回集合的“更改流”游标。此阶段在聚合管道中只能发生一次，并且必须作为第一阶段发生。
$changeStreamSplitLargeEventSplits large change stream events that exceed 16 MB into smaller fragments returned in a change stream cursor.将超过16MB的大型更改流事件拆分为更改流游标中返回的较小片段。
You can only use $changeStreamSplitLargeEvent in a $changeStream pipeline and it must be the final stage in the pipeline.您只能在$changeStream管道中使用$changeStreamSplitRateEvent，并且它必须是管道中的最后一个阶段。
$collStatsReturns statistics regarding a collection or view.返回有关集合或视图的统计信息。
$countReturns a count of the number of documents at this stage of the aggregation pipeline.返回聚合管道此阶段的文档数量计数。
Distinct from the $count aggregation accumulator.不同于$count聚合累加器。
$densifyCreates new documents in a sequence of documents where certain values in a field are missing.在字段中缺少某些值的文档序列中创建新文档。
$documentsReturns literal documents from input expressions.从输入表达式返回文本文档。
$facetProcesses multiple aggregation pipelines 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.允许创建能够在单个阶段跨多个维度或方面表征数据的多面聚合。
$fillPopulates null and missing field values within documents.填充文档中的null字段值和缺失的字段值。
$geoNearReturns an ordered stream of documents based on the proximity to a geospatial point. 根据与地理空间点的接近程度返回有序的文档流。Incorporates the functionality of $match, $sort, and $limit for geospatial data. 结合了地理空间数据的$match、$sort和$limit功能。The output documents include an additional distance field and can include a location identifier field.输出文档包括附加的距离字段，并且可以包括位置标识符字段。
$graphLookupPerforms 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.对集合执行递归搜索。向每个输出文档添加一个新的数组字段，其中包含该文档的递归搜索的遍历结果。
$groupGroups 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.消耗所有输入文档，并为每个不同的组输出一个文档。输出文档仅包含标识符字段和累积字段（如果指定）。
$indexStatsReturns statistics regarding the use of each index for the collection.返回有关集合中每个索引使用情况的统计信息。
$limitPasses the first n documents unmodified to the pipeline where n is the specified limit. 将前n个文档原封不动地传递给管道，其中n是指定的限制。For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).对于每个输入文档，输出一个文档（对于前n个文档）或零个文档（在前n个文件之后）。
$listClusterCatalogRetrieves information for collections in a cluster, including names and creation options.
$listSampledQueriesLists sampled queries for all collections or a specific collection.
$listSearchIndexesReturns information about existing MongoDB Search indexes on a specified collection or view.返回指定集合或视图上现有MongoDB搜索索引的信息。
$listSessionsLists all sessions that have been active long enough to propagate to the system.sessions collection.列出所有已激活足够长时间以传播到system.sessions集合的会话。
$lookupPerforms 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.对同一数据库中的另一个集合或视图执行左外联接，以从“联接”的集合或视图中筛选文档进行处理。
$matchFilters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. 筛选文档流，只允许匹配的文档未经修改地传递到下一个管道阶段。$match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).使用标准的MongoDB查询。对于每个输入文档，输出一个文档（匹配）或零个文档（不匹配）。
$mergeWrites 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 stage, it must be the last stage in the pipeline.要使用$merge阶段，它必须是管道中的最后一个阶段。
$outWrites the resulting documents of the aggregation pipeline to a collection. 将聚合管道的结果文档写入集合。To use the $out stage, it must be the last stage in the pipeline.要使用$out阶段，它必须是管道中的最后一个阶段。
$planCacheStatsReturns plan cache information for a collection.
$projectReshapes 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 for removing existing fields.

$querySettingsReturns query settings previously added with setQuerySettings.

New in version 8.0.

$queryStatsReturns 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.$queryStats聚合阶段不受支持，也不能保证在未来的版本中稳定。不要构建依赖于此阶段特定输出格式的功能，因为输出可能会在未来的版本中发生变化。

$rankFusionCombines the results of input pipelines that rank documents. 组合对文档进行排序的输入管道的结果。$rankFusion de-duplicates input pipeline results and uses the Reciprocal Rank Fusion algorithm to create a final document ranking.
$redactReshapes 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 and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero documents.可用于实现字段级编校。对于每个输入文档，输出一个或零个文档。
$replaceRootReplaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. 用指定的嵌入文档替换文档。该操作将替换输入文档中的所有现有字段，包括_id字段。Specify a document embedded in the input document to promote the embedded document to the top level.指定嵌入在输入文档中的文档，以将嵌入的文档提升到顶层。 $replaceWith is an alias for $replaceRoot stage.是$replaceRoot阶段的别名。
$replaceWithReplaces 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 is an alias for $replaceRoot stage.
$sampleRandomly selects the specified number of documents from its input.从输入中随机选择指定数量的文档。
$searchPerforms a full-text search of the field or fields in an Atlas collection.对Atlas集合中的一个或多个字段执行全文搜索。
To learn more, see MongoDB Search Aggregation Pipeline Stages.要了解更多信息，请参阅MongoDB搜索聚合管道阶段。
$searchMetaReturns different types of metadata result documents for the MongoDB Search query against an Atlas collection. To learn more, see MongoDB Search Aggregation Pipeline Stages.
$setAdds new fields to documents. Similar to $project, $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 is an alias for $addFields stage.

$setWindowFieldsGroups documents into windows and applies one or more operators to the documents in each window.

New in version 5.0.

$skipSkips 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).
$sortReorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document.
$sortByCountGroups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group.
$unionWithPerforms a union of two collections; i.e. combines pipeline results from two collections or views into a single result set.
$unsetRemoves/excludes fields from documents.

$unset is an alias for $project stage that removes fields.

$unwindDeconstructs 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.
$vectorSearchPerforms an ANN or ENN search on a vector in the specified field of an Atlas collection.

$vectorSearch is only available for MongoDB Atlas clusters running MongoDB v6.0.11 or higher, and is not available for self-managed deployments.$vectorSearch仅适用于运行MongoDB v6.0.11或更高版本的MongoDB Atlas集群，不适用于自我管理部署。

New in version 7.0.2.

To learn about expressions that you can use in pipeline stages, see Expressions.要了解可以在管道阶段中使用的表达式，请参阅表达式。

db.aggregate() Stages阶段

MongoDB also provides the db.aggregate() method:MongoDB还提供了db.aggregate()方法：

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

The following stages use the db.aggregate() method and not the db.collection.aggregate() method.以下阶段使用db.aggregate()方法，而不是db.collection.aggregate()方法。

Stage阶段Description描述
$changeStreamReturns a Change Stream cursor for the collection. This stage can only occur once in an aggregation pipeline and it must occur as the first stage.
$currentOpReturns information on active and/or dormant operations for the MongoDB deployment.返回有关MongoDB部署的活动和/或休眠操作的信息。
$documentsReturns literal documents from input values.从输入值返回文字文档。
$listLocalSessionsLists all active sessions recently in use on the currently connected mongos or mongod instance. These sessions may have not yet propagated to the system.sessions collection.

Stages Available for Updates可用于更新的阶段

You can use the aggregation pipeline for updates in:您可以在以下位置使用聚合管道进行更新：

Command命令mongosh Methods方法
findAndModify
db.collection.findOneAndUpdate()
db.collection.findAndModify()
update
db.collection.updateOne()
db.collection.updateMany()
Bulk.find.update()
Bulk.find.updateOne()
Bulk.find.upsert()

For the updates, the pipeline can consist of the following stages:对于更新，管道可以由以下阶段组成：