Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB Manual

聚合

在此页面上

  • 定义
  • 语法
  • 会话
  • 事务
  • Stable API
  • 例子

定义

aggregate

使用聚合管道执行聚合操作。管道允许用户通过一系列基于阶段的操作来处理集合或其他来源的数据。

提示

在 mongosh中，该命令也可以通过db.aggregate()和db.collection.aggregate()辅助方法或使用watch()辅助方法运行。

助手方法对于mongosh用户来说很方便，但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段，请使用数据库命令。

语法

5.0 版本中的更改。

该命令具有以下语法：

db.runCommand(
   {
     aggregate: "<collection>" || 1,
     pipeline: [ <stage>, <...> ],
     explain: <boolean>,
     allowDiskUse: <boolean>,
     cursor: <document>,
     maxTimeMS: <int>,
     bypassDocumentValidation: <boolean>,
     readConcern: <document>,
     collation: <document>,
     hint: <string or document>,
     comment: <any>,
     writeConcern: <document>,
     let: <document> // Added in MongoDB 5.0
   }
)

命令字段

aggregate命令将以下字段作为参数：

字段
类型
说明
aggregate
字符串
充当聚合管道的输入的集合或视图的名称。使用 1 执行与集合无关的命令。
pipeline
阵列
聚合管道阶段数组，作为聚合管道的一部分处理和转换文档流。
explain
布尔

可选。指定返回关于管道处理的信息。

不适用于多文档事务。

allowDiskUse

布尔

可选。

使用此选项可以覆盖特定查询的 allowDiskUseByDefault。您可以使用此选项执行以下任一操作：

  • 禁止在默认允许使用磁盘的系统上使用磁盘。

  • 支持在默认情况下禁止使用磁盘的系统上使用磁盘。

从 MongoDB 6.0 开始，如果 allowDiskUseByDefault 设置为 true，并且服务器需要超过 100 MB 的内存用于管道执行阶段，那么 MongoDB 会自动将临时文件写入磁盘，除非查询指定了 { allowDiskUse: false }。

有关详细信息，请参阅allowDiskUseByDefault。

如果任何聚合阶段由于 内存限制 而将数据写入临时文件，则 分析器日志消息 和 诊断日志消息 会包含 指示符。usedDisk

cursor
文档

指定包含控制游标对象创建选项的文档。

在版本 3.6 中更改：MongoDB 3.6 删除了在没有 cursor 选项的情况下使用 aggregate 命令的操作，除非该命令包含 explain 选项。除非包含 explain 选项，否则必须指定游标选项。

  • 要指示具有默认批次大小的游标，请指定 cursor: {}。

  • 要指示具有非默认批次大小的游标，请使用 cursor: { batchSize: <num> }。

maxTimeMS
非负整数

可选。

指定时间限制（以毫秒为单位）。如果您未指定 maxTimeMS 值，操作将不会超时。如果值为 0 ，则显式指定默认无限制行为。

MongoDB 使用与 db.killOp() 相同的机制终止超过分配的时间限制的操作。MongoDB 仅在指定的中断点之一中终止操作。

bypassDocumentValidation
布尔

可选。仅当您指定 $out 或 $merge 聚合阶段时使用。

启用aggregate可在操作期间绕过文档验证。这样，您就可以插入不符合验证要求的文档。

readConcern
文档

可选。指定读关注。

从 MongoDB 3.6 开始，readConcern 选项具有以下事务语法： readConcern: { level: <value> }

可能的读关注级别是：

有关读关注级别的更多信息，请参阅读关注级别。

$out阶段不能与读关注"linearizable" 一起使用。如果您为"linearizable" db.collection.aggregate()$out指定 读关注，则不能在管道中包含 阶段。

$merge 阶段不能与读关注 "linearizable" 一起使用。换言之，如果您为 db.collection.aggregate() 指定 "linearizable" 读关注，则不能将 $merge 阶段包括在管道中。

collation
文档

可选。

指定用于操作的排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

排序规则选项的语法如下：

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

指定排序规则时，locale 字段为必填字段；所有其他排序规则字段均为可选字段。有关字段的说明，请参阅排序规则文档。

如果未指定排序规则，但集合具有默认排序规则（请参阅 db.createCollection()），则操作将使用为集合指定的排序规则。

如果没有为收集或操作指定排序规则，MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。

您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果执行带排序的查找，则不能使用一种排序规则进行查找而另一种排序规则进行排序。

hint
字符串或文档

可选。用于该聚合的索引。该索引位于运行聚合的初始集合/视图上。

通过索引名称或索引规范文档来指定索引。

注意

hint 不适用于 $lookup 和 $graphLookup 阶段。

comment
注意到

可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置：

注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

注意

在aggregate命令上设置的任何注释都会由在aggregate游标上运行的任何后续getMore命令继承。

writeConcern
文档

可选。一个表达写关注的文档，该写关注会与 $out 或 $merge 阶段一起配合使用。

在 $out 或 $merge 阶段省略使用默认写关注。

let
文档

可选。

指定包含变量列表的文档。这样可以将变量与查询文本分开，从而提高命令的可读性。

文档语法为：

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

变量设置为表达式返回的值，并且之后不能再进行更改。

要访问命令中的变量值，请使用双美元符号前缀 ($$) 以及 $$<variable_name> 形式的变量名称。例如：$$targetTotal。

注意

要使用变量筛选管道 $match 阶段的结果，必须在 $expr 运算符中访问该变量。

有关使用let和变量的完整示例，请参阅在let中使用变量。

版本 5.0 中的新增功能。

MongoDB3 。6 删除aggregate cursor不带 选项的 命令的使用，除非该命令包含explain 选项。除非包含explain 选项，否则必须指定游标选项。

  • 要指示具有默认批次大小的游标，请指定 cursor: {}。

  • 要指示具有非默认批次大小的游标，请使用 cursor: { batchSize: <num> }。

有关聚合管道聚合管道、聚合参考和聚合管道限制的更多信息。

会话

4.0 版本中的新功能。

对于在一个会话内创建的游标，不能在该会话外调用 getMore。

同样，对于在会话外创建的游标，不能在会话内调用 getMore。

会话空闲超时

MongoDB 驱动程序和mongosh将所有操作与服务器会话关联，但未确认的写入操作除外。对于未显式与会话关联的操作（即使用Mongo.startSession() ），MongoDB 驱动程序和mongosh创建隐式会话并将其与操作关联。

如果会话空闲时间超过 30 分钟，MongoDB Server 会将该会话标记为已过期，并可能随时将其关闭。当 MongoDB Server 关闭会话时，它还会终止任何正在进行的操作并打开与会话关联的游标。这包括使用超过 30 分钟的 noCursorTimeout() 或 maxTimeMS() 配置的游标。

对于返回游标的操作，如果游标的空闲时间可能超过 30 分钟，则使用 Mongo.startSession() 在显式会话中发出操作，并使用 refreshSessions 命令定期刷新会话。更多信息，请参阅会话空闲超时。

事务

aggregate可以在分布式事务中使用。

但是，事务中不允许有以下阶段：

此外，您不能指定 explain 选项。

  • 对于在 ACID 事务外部创建的游标，无法在 ACID 事务内部调用 getMore。

  • 对于在事务中创建的游标，无法在事务外部调用 getMore。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

客户端断开连接

对于不包括aggregate $out或$merge 阶段的 操作：

从 MongoDB4 开始。2 ，如果发出 的客户端在操作完成之前断开连接，MongoDBaggregate 会使用aggregate killOp将 标记为终止。

Stable API

使用 Stable API V1 时：

例子

MongoDB3 。6 删除aggregate cursor不带 选项的 命令的使用，除非该命令包含explain 选项。除非包含explain 选项，否则必须指定游标选项。

  • 要指示具有默认批次大小的游标，请指定 cursor: {}。

  • 要指示具有非默认批次大小的游标，请使用 cursor: { batchSize: <num> }。

aggregate大多数用户不应直接运行 命令，而应使用 中提供的db.collection.aggregate() mongosh助手或其驱动程序中的等效助手。在2 中。6 及更高版本，db.collection.aggregate() 辅助程序始终返回游标。

除演示命令语法的前两个示例外，本页中的其他示例均使用 db.collection.aggregate() 助手。

使用多阶段管道聚合数据

集合 articles 包含如下文档：

{
   _id: ObjectId("52769ea0f3dc6ead47c9a1b2"),
   author: "abc123",
   title: "zzz",
   tags: [ "programming", "database", "mongodb" ]
}

以下示例对articles集合执行aggregate操作，以计算该集合中出现的tags数组中每个不同元素的计数。

db.runCommand( {
   aggregate: "articles",
   pipeline: [
      { $project: { tags: 1 } },
      { $unwind: "$tags" },
      { $group: { _id: "$tags", count: { $sum : 1 } } }
   ],
   cursor: { }
} )

在mongosh中，此操作可以使用db.collection.aggregate()辅助程序，如下所示：

db.articles.aggregate( [
   { $project: { tags: 1 } },
   { $unwind: "$tags" },
   { $group: { _id: "$tags", count: { $sum : 1 } } }
] )

在管理员数据库上使用 $currentOp

以下示例将对管理员数据库上运行附带两个阶段的管道。第一个阶段会运行 $currentOp 操作，而第二个阶段则会筛选此操作的结果。

db.adminCommand( {
   aggregate : 1,
   pipeline : [ {
      $currentOp : { allUsers : true, idleConnections : true } }, {
      $match : { shard : "shard01" }
      }
   ],
   cursor : { }
} )

注意

aggregate命令不指定集合，而是采用{aggregate: 1}形式。这是因为初始$currentOp阶段不从集合中提取输入。它生成自己的数据，供管道的其余部分使用。

添加了新的 db.aggregate() 助手，帮助运行类似本示例的无集合聚合。上述聚合也可以像这个示例一样运行。

返回聚合操作信息

以下聚合操作会将可选字段 explain 设为 true 以返回有关此聚合操作的信息。

db.orders.aggregate([
      { $match: { status: "A" } },
      { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
      { $sort: { total: -1 } }
   ],
   { explain: true }
)

注意

解释输出可能因版本而异。

提示

另请参阅：

db.collection.aggregate() 方法

互动 allowDiskUseByDefault

从 MongoDB 6.0 开始，需要 100 MB 以上内存容量的管道阶段默认将临时文件写入磁盘。在 MongoDB 的早期版本中，您必须将 { allowDiskUse: true } 传递给单个 find 和 aggregate 命令才能启用此行为。

单个 find 和 aggregate 命令可以通过以下任一方式覆盖 allowDiskUseByDefault 参数：

  • 使用 { allowDiskUse: true } 以允许在 allowDiskUseByDefault 设置为 false 时将临时文件写入磁盘

  • 使用 { allowDiskUse: false } 以禁止在 allowDiskUseByDefault 设置为 true 时将临时文件写入磁盘

如果任何聚合阶段由于 内存限制 而将数据写入临时文件，则 分析器日志消息 和 诊断日志消息 会包含 指示符。usedDisk

提示

另请参阅：

指定批处理大小的聚合数据

要指定初始批量大小，请在 cursor 字段中指定 batchSize，如下面示例所示：

db.orders.aggregate( [
      { $match: { status: "A" } },
      { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
      { $sort: { total: -1 } },
      { $limit: 2 }
   ],
   { cursor: { batchSize: 0 } }
)

{ cursor: { batchSize: 0 } } 文档指定初始批处理大小，表示首次批处理为空。此批处理大小对于快速返回游标或失败消息非常有用，无需执行大量服务器端工作。

要为后续 getMore 操作（初始批次后）指定批次大小，请在运行 getMore 命令时使用 batchSize 字段。

指定排序规则

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

集合 myColl 包含以下文档：

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

以下聚合操作包括排序规则选项：

db.myColl.aggregate(
   [ { $match: { status: "A" } }, { $group: { _id: "$category", count: { $sum: 1 } } } ],
   { collation: { locale: "fr", strength: 1 } }
);

有关排序规则字段的说明，请参阅排序规则文档。

提示索引

使用以下文档创建集合 foodColl：

db.foodColl.insertMany( [
   { _id: 1, category: "cake", type: "chocolate", qty: 10 },
   { _id: 2, category: "cake", type: "ice cream", qty: 25 },
   { _id: 3, category: "pie", type: "boston cream", qty: 20 },
   { _id: 4, category: "pie", type: "blueberry", qty: 15 }
] )

创建以下索引：

db.foodColl.createIndex( { qty: 1, type: 1 } );
db.foodColl.createIndex( { qty: 1, category: 1 } );

下面的聚合操作包含 hint 选项，强制使用指定的索引：

db.foodColl.aggregate(
   [ { $sort: { qty: 1 }}, { $match: { category: "cake", qty: 10  } }, { $sort: { type: -1 } } ],
   { hint: { qty: 1, category: 1 } }
)

覆盖默认读关注

要覆盖默认的读关注级别，请使用readConcern选项。 getMore命令使用原始aggregate命令中指定的readConcern级别。

您不能将 $out 或 $merge 阶段与读关注 "linearizable" 一起使用。换言之，如果将 "linearizable" 读关注为 db.collection.aggregate() 指定，则不能在管道中包含任一阶段。

对副本集执行以下操作可以指定读关注 "majority"，以读取确认已写入大多数节点的数据的最新副本。

重要

  • 您可以为包含 阶段的聚合指定"majority" 读关注$out 级别 。

  • 无论读关注级别如何，节点上的最新数据可能无法反映系统中数据的最新版本。

db.restaurants.aggregate(
   [ { $match: { rating: { $lt: 5 } } } ],
   { readConcern: { level: "majority" } }
)

为确保单个线程可以读取自己的写入内容，请对副本集的主节点使用 "majority" 读关注和 "majority" 写关注。

使用以下项中的变量： let

版本 5.0 中的新增功能。

要定义可在命令中其他位置访问的变量，请使用 let 选项。

注意

要通过在管道 $match 阶段使用变量筛选结果，必须访问 $expr 运算符中的变量。

创建包含不同口味蛋糕销售额的集合 cakeSales：

db.cakeSales.insertMany( [
   { _id: 1, flavor: "chocolate", salesTotal: 1580 },
   { _id: 2, flavor: "strawberry", salesTotal: 4350 },
   { _id: 3, flavor: "cherry", salesTotal: 2150 }
] )

如下示例：

  • 检索 salesTotal 大于 3000 的蛋糕，即 _id 为 2 的蛋糕

  • 在 let 中定义了一个 targetTotal 变量，该变量在 $gt 中被引用为 $$targetTotal

db.runCommand( {
   aggregate: db.cakeSales.getName(),
   pipeline: [
      { $match: {
           $expr: { $gt: [ "$salesTotal", "$$targetTotal" ] }
      } },
    ],
    cursor: {},
    let: { targetTotal: 3000 }
} )

提示

另请参阅：

db.collection.aggregate()

← 聚合命令
数数 →

在此页面上