聚合管道阶段

在此页面上

兼容性

阶段(Stages)
按字母顺序列出的阶段

MongoDB5.0 已于 10 月2024 结束生命周期。不再支持此版本的文档。要升级5.0 部署，请参阅 MongoDB6 。0 升级程序。

在db.collection.aggregate() 方法和db.aggregate() 方法中，管道阶段出现在数组中。在 Atlas 用户界面中，您可以使用聚合管道构建器来安排管道阶段。文档按顺序通过各个阶段。

兼容性

您可以对如下环境中托管的部署使用管道阶段：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

阶段(Stages)

`db.collection.aggregate()` 阶段(Stages)

除$out 、 $merge 、 $geoNear和$changeStream阶段外，所有阶段都可以在管道中出现多次。

注意

有关特定操作符（包括事务语法和示例）的详细信息，请单击该操作符的参考页面链接。

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

阶段	说明
`$addFields`	为文档添加新字段。与 `$project` 类似，`$addFields` 重塑了流中的每个文档；具体来说，就是在输出文档中添加新字段，这些输出文档既包含输入文档中的现有字段，也包含新添加的字段。 `$set` 是 `$addFields` 的别名。
`$bucket`	根据指定的表达式和存储桶边界将传入的文档分为多个组（称为存储桶）。
`$bucketAuto`	根据指定的表达式，将接收到的文档归类到特定数量的群组中（称为“存储桶”）。自动确定存储桶边界，以尝试将文档均匀地分配到指定数量的存储桶中。
`$changeStream`	返回集合的 Change Stream 游标。此阶段只能在 aggregation pipeline 中发生一次，并且必须作为第一阶段发生。
`$collStats`	返回有关集合或视图的统计信息。
`$count`	返回聚合管道此阶段的文档数量计数。有别于 `$count` 聚合累加器。
`$facet`	在单个阶段内处理同一组输入文档上的多个聚合管道。支持创建多分面聚合，能够在单个阶段中跨多个维度或分面描述数据特征。
`$geoNear`	根据与地理空间点的接近程度返回有序的文档流。针对地理空间数据，整合了 `$match`、`$sort` 和 `$limit` 功能。输出文档包含一个额外的距离字段，并可包含一个位置标识符字段。
`$graphLookup`	对集合执行递归搜索。为每个输出文档添加一个新数组字段，其中包含该文档的递归搜索遍历结果。
`$group`	按指定的标识符表达式对输入文档进行分组，并将累加器表达式（如果指定）应用于每个群组。接收所有输入文档，并为每个不同群组输出一个文档。输出文档仅包含标识符字段和累积字段（如果指定）。
`$indexStats`	返回有关集合的每个索引使用情况的统计信息。
`$limit`	将未修改的前 n 个文档传递到管道，其中 n 为指定的限制。对于每个输入文档，输出一个文档（针对前 n 个文档）或零个文档（前 n 个文档之后）。
`$listSessions`	列出活动时间足够长、足以传播到 `system.sessions` 集合的所有会话。
`$lookup`	对同一数据库中的另一个集合执行左外连接，以过滤“已连接”集合中的文档以便进行处理。
`$match`	筛选文档流以仅允许匹配的文档将未修改的文档传入下一管道阶段。`$match` 使用标准 MongoDB 查询。对于每个输入文档，输出一个文档（一个匹配项）或零个文档（无匹配项）。
`$merge`	将 aggregation pipeline 的结果文档写入集合。该阶段可将结果（插入新文档、合并文档、替换文档、保留现有文档、操作失败、使用自定义更新管道处理文档）纳入输出集合。要使用 `$merge` 阶段，它必须是管道中的最后一个阶段。
`$out`	将 aggregation pipeline 的结果文档写入集合。要使用 `$out` 阶段，它必须是管道中的最后一个阶段。
`$planCacheStats`	返回集合的计划缓存信息。
`$project`	重塑流中的每个文档，例如添加新的字段或删除现有字段。对于每个输入文档，输出一个文档。另请参阅 `$unset` 以了解如何删除现有字段。
`$redact`	根据文档中存储的信息来限制每个文档的内容，从而重塑流中的每个文档。结合了 `$project` 和 `$match` 的功能。可用于实现字段级别访问控制。对于每个输入文档，输出一个或零个文档。
`$replaceRoot`	用指定的嵌入文档替换文档。该操作会替换输入文档中的所有现有字段，包括 `_id` 字段。指定嵌入在输入文档中的文档，以将嵌入的文档提升到顶层。 `$replaceWith` 是 `$replaceRoot` 阶段的别名。
`$replaceWith`	用指定的嵌入文档替换文档。该操作会替换输入文档中的所有现有字段，包括 `_id` 字段。指定嵌入在输入文档中的文档，以将嵌入的文档提升到顶层。 `$replaceWith` 是 `$replaceRoot` 阶段的别名。
`$sample`	从其输入中随机选择指定数量的文件。
`$search`	对 Atlas 集合中的一个或多个字段执行全文搜索。 `$search` 仅适用于 MongoDB Atlas 集群，不适用于自我管理部署。
`$set`	为文档添加新字段。与 `$project` 类似，`$set` 重塑了流中的每个文档；具体来说，就是在输出文档中添加新字段，这些输出文档既包含输入文档中的现有字段，也包含新添加的字段。 `$set` 是 `$addFields` 阶段的别名。
`$setWindowFields`	将文档分组到窗口中，并将一个或多个操作符应用于每个窗口中的文档。版本 5.0 中的新增功能。
`$skip`	跳过前 n 个文档，其中 n 是指定的跳过编号，并将未修改的剩余文档传递到管道。对于每个输入文档，输出零个文档（对于前 n 个文档）或一个文档（如果在前 n 个文档之后）。
`$sort`	按指定的排序键对文档流重新排序。仅顺序会改变，而文档则保持不变。对于每个输入文档，输出一个文档。
`$sortByCount`	根据指定表达式的值对传入文档进行分组，然后计算每个不同群组中的文档数量。
`$unionWith`	执行两个集合的联合；即将两个集合的管道结果合并到一个结果集中。
`$unset`	从文档中删除/排除字段。 `$unset` 是删除字段的 `$project` 阶段的别名。
`$unwind`	对输入文档中的某一数组字段进行解构，以便为每个元素输出文档。每个输出文档均会将此数组替换为元素值。对于每个输入文档，输出 n 个文档，其中 n 为数组元素的数量，且对于空数组可为零。

有关在管道阶段使用的聚合表达式操作符，请参阅聚合管道操作符。

`db.aggregate()` 阶段(Stages)

从版本 3.6 开始，MongoDB 还提供db.aggregate()方法：

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

以下阶段使用 db.aggregate()方法，而不是 db.collection.aggregate() 方法。

阶段	说明
`$changeStream`	返回集合的 Change Stream 游标。此阶段只能在 aggregation pipeline 中发生一次，并且必须作为第一阶段发生。
`$currentOp`	返回 MongoDB 部署的活动和/或休眠操作的信息。
`$listLocalSessions`	列出当前连接的 `mongos` 或 `mongod` 实例上最近使用的所有活动会话。这些会话可能尚未传播到 `system.sessions` 集合。

可更新的阶段

您可以使用聚合管道进行更新：

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

对于更新，该管道可以由以下阶段组成：

按字母顺序列出的阶段

名称	说明
`$addFields`	向文档添加新字段。输出包含输入文档中所有现有字段和新添加字段的文档。
`$bucket`	根据指定的表达式和存储桶边界将传入的文档分为多个组（称为存储桶）。
`$bucketAuto`	根据指定的表达式，将接收到的文档归类到特定数量的群组中（称为“存储桶”）。自动确定存储桶边界，以尝试将文档均匀地分配到指定数量的存储桶中。
`$changeStream`	返回collection或数据库的change stream游标。此阶段只能在聚合管道中发生一次，并且必须作为第一阶段发生。
`$collStats`	返回有关集合或视图的统计信息。
`$count`	返回聚合管道此阶段的文档数量计数。有别于 `$count` 聚合累加器。
`$currentOp`	返回 MongoDB 部署的活动和/或休眠操作的信息。要运行，请使用`db.aggregate()`方法。
`$facet`	在单个阶段内处理同一组输入文档上的多个聚合管道。支持创建多分面聚合，能够在单个阶段中跨多个维度或分面描述数据特征。
`$geoNear`	根据与地理空间点的接近程度返回有序的文档流。针对地理空间数据，整合了 `$match`、`$sort` 和 `$limit` 功能。输出文档包含一个额外的距离字段，并可包含一个位置标识符字段。
`$graphLookup`	对集合执行递归搜索。为每个输出文档添加一个新数组字段，其中包含该文档的递归搜索遍历结果。
`$group`	按指定的标识符表达式对输入文档进行分组，并将累加器表达式（如果指定）应用于每个群组。接收所有输入文档，并为每个不同群组输出一个文档。输出文档仅包含标识符字段和累积字段（如果指定）。
`$indexStats`	返回有关集合的每个索引使用情况的统计信息。
`$limit`	将未修改的前 n 个文档传递到管道，其中 n 为指定的限制。对于每个输入文档，输出一个文档（针对前 n 个文档）或零个文档（前 n 个文档之后）。
`$listLocalSessions`	列出当前连接的 `mongos` 或 `mongod` 实例上最近使用的所有活动会话。这些会话可能尚未传播到 `system.sessions` 集合。
`$listSessions`	列出活动时间足够长、足以传播到 `system.sessions` 集合的所有会话。
`$lookup`	对同一数据库中的另一个集合执行左外连接，以过滤“已连接”集合中的文档以便进行处理。
`$match`	筛选文档流以仅允许匹配的文档将未修改的文档传入下一管道阶段。`$match` 使用标准 MongoDB 查询。对于每个输入文档，输出一个文档（一个匹配项）或零个文档（无匹配项）。
`$merge`	将 aggregation pipeline 的结果文档写入集合。该阶段可将结果（插入新文档、合并文档、替换文档、保留现有文档、操作失败、使用自定义更新管道处理文档）纳入输出集合。要使用 `$merge` 阶段，它必须是管道中的最后一个阶段。 4.2 版本中的新增功能。
`$out`	将 aggregation pipeline 的结果文档写入集合。要使用 `$out` 阶段，它必须是管道中的最后一个阶段。
`$planCacheStats`	返回集合的计划缓存信息。
`$project`	重塑流中的每个文档，例如添加新的字段或删除现有字段。对于每个输入文档，输出一个文档。
`$redact`	根据文档中存储的信息来限制每个文档的内容，从而重塑流中的每个文档。结合了 `$project` 和 `$match` 的功能。可用于实现字段级别访问控制。对于每个输入文档，输出一个或零个文档。
`$replaceRoot`	用指定的嵌入文档替换文档。该操作会替换输入文档中的所有现有字段，包括 `_id` 字段。指定嵌入在输入文档中的文档，以将嵌入的文档提升到顶层。
`$replaceWith`	用指定的嵌入文档替换文档。该操作会替换输入文档中的所有现有字段，包括 `_id` 字段。指定嵌入在输入文档中的文档，以将嵌入的文档提升到顶层。 `$replaceRoot`的别名。
`$sample`	从其输入中随机选择指定数量的文件。
$search	对 Atlas 集合中的一个或多个字段执行全文搜索。注意 `$search` 仅适用于 MongoDB Atlas 集群，不适用于自我管理部署。
`$set`	向文档添加新字段。输出包含输入文档中所有现有字段和新添加字段的文档。 `$addFields`的别名。
`$setWindowFields`	将文档分组到窗口中，并将一个或多个操作符应用于每个窗口中的文档。版本 5.0 中的新增功能。
`$skip`	跳过前 n 个文档，其中 n 是指定的跳过编号，并将未修改的剩余文档传递到管道。对于每个输入文档，输出零个文档（对于前 n 个文档）或一个文档（如果在前 n 个文档之后）。
`$sort`	按指定的排序键对文档流重新排序。仅顺序会改变，而文档则保持不变。对于每个输入文档，输出一个文档。
`$sortByCount`	根据指定表达式的值对传入文档进行分组，然后计算每个不同群组中的文档数量。
`$unionWith`	执行两个集合的联合；即将两个集合的管道结果合并到一个结果集中。 4.4 版本新增。
`$unset`	从文档中删除/排除字段。排除/删除字段的`$project`阶段的别名。
`$unwind`	对输入文档中的某一数组字段进行解构，以便为每个元素输出文档。每个输出文档均会将此数组替换为元素值。对于每个输入文档，输出 n 个文档，其中 n 为数组元素的数量，且对于空数组可为零。

后退

$bit

来年

$addFields

兼容性

阶段(Stages)

db.collection.aggregate() 阶段(Stages)

注意

db.aggregate() 阶段(Stages)

可更新的阶段

按字母顺序列出的阶段

注意

`db.collection.aggregate()` 阶段(Stages)

`db.aggregate()` 阶段(Stages)