聚合管道阶段

在此页面上

兼容性

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

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

兼容性

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

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

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

阶段(Stages)

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

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

注意

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

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

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

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

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

MongoDB 还提供了 db.aggregate() 方法：

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

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

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

可更新的阶段

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

命令	`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游标。此阶段只能在聚合管道中发生一次，并且必须作为第一阶段发生。
`$changeStreamSplitLargeEvent`	将超过 16 MB 的大型 change stream 事件分割成较小的分段，在 change stream 游标中返回。您只能在 `$changeStream` 管道中使用 `$changeStreamSplitLargeEvent`，且它必须为该管道中的最后阶段。
`$collStats`	返回有关集合或视图的统计信息。
`$count`	返回聚合管道此阶段的文档数量计数。有别于 `$count` 聚合累加器。
`$currentOp`	返回 MongoDB 部署的活动和/或休眠操作的信息。要运行，请使用`db.aggregate()`方法。
`$densify`	在文档序列中创建新文档，其中缺少字段中的某些值。
`$documents`	根据输入值返回字面文档。
`$facet`	在单个阶段内处理同一组输入文档上的多个聚合管道。支持创建多分面聚合，能够在单个阶段中跨多个维度或分面描述数据特征。
`$fill`	填充文档中的 `null` 和缺失的字段值。
`$geoNear`	根据与地理空间点的接近程度返回有序的文档流。针对地理空间数据，整合了 `$match`、`$sort` 和 `$limit` 功能。输出文档包含一个额外的距离字段，并可包含一个位置标识符字段。
`$graphLookup`	对集合执行递归搜索。为每个输出文档添加一个新数组字段，其中包含该文档的递归搜索遍历结果。
`$group`	按指定的标识符表达式对输入文档进行分组，并将累加器表达式（如果指定）应用于每个群组。接收所有输入文档，并为每个不同群组输出一个文档。输出文档仅包含标识符字段和累积字段（如果指定）。
`$indexStats`	返回有关集合的每个索引使用情况的统计信息。
`$limit`	将未修改的前 n 个文档传递到管道，其中 n 为指定的限制。对于每个输入文档，输出一个文档（针对前 n 个文档）或零个文档（前 n 个文档之后）。
`$listLocalSessions`	列出当前连接的 `mongos` 或 `mongod` 实例上最近使用的所有活动会话。这些会话可能尚未传播到 `system.sessions` 集合。
`$listSearchIndexes`	返回指定集合上现有 Atlas Search 索引的信息。
`$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 集群，不适用于自我管理部署。要了解更多信息，请参阅Atlas Search 聚合管道阶段。
$searchMeta	为针对 Atlas 集合的 Atlas Search 查询返回不同类型的元数据结果文档。注意 `$searchMeta` 仅在运行 MongoDB v4.4.9 或更高版本的 MongoDB Atlas 集群中可用，在自管理式部署中不可用。要了解更多信息，请参阅Atlas Search 聚合管道阶段。
`$set`	向文档添加新字段。输出包含输入文档中所有现有字段和新添加字段的文档。 `$addFields`的别名。
`$setWindowFields`	将文档分组到窗口中，并将一个或多个操作符应用于每个窗口中的文档。版本 5.0 中的新增功能。
`$shardedDataDistribution`	提供有关分片集合的数据和大小分布信息。 6.0.3 版本新增。
`$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)