db.collection.aggregate（）

MongoDB 中文手册

参考 > 参考 > mongo Shell方法 > 收集方法 > db.collection.aggregate（）

在本页面

定义
行为
例子

定义¶

db.collection.aggregate（管道，选项）¶

mongo 壳法

此页面记录了mongoshell方法，并且没有引用MongoDB Node.js驱动程序（或任何其他驱动程序）方法。对于相应的MongoDB驱动程序API，请改为参考您特定的 MongoDB驱动程序文档。

计算集合或视图中数据的聚合值。

参数	类型	描述
`pipeline`	数组	数据聚合操作或阶段的序列。有关详细信息，请参见聚合管道运算符。该方法仍然可以将流水线阶段作为单独的参数而不是数组中的元素接受。但是，如果您不将指定`pipeline`为数组，则不能指定 `options`参数。
`options`	文献	可选的。`aggregate()`传递给`aggregate`命令的其他选项。仅当您将指定`pipeline`为数组时才可用。

该options文档可以包含以下字段和值：

领域	类型	描述
`explain`	布尔值	可选的。指定返回有关管道处理的信息。有关示例，请参阅有关聚合管道操作的返回信息。在多文档交易中不可用。
allowDiskUse	布尔值	可选的。允许写入临时文件。设置为时 `true`，大多数聚合操作可以将数据写入`_tmp`目录中的 `dbPath`子目录，但以下情况除外： `$graphLookup` 阶段 `$addToSet`该`$group`阶段中使用的累加器表达式（从4.2.3、4.0.14、3.6.17版开始） `$push`该`$group`阶段中使用的累加器表达式（从4.2.3、4.0.14、3.6.17版开始）有关allowDiskUse的示例，请参见使用外部排序执行大型排序操作。从MongoDB 4.2开始，事件探查器日志消息和诊断日志消息包括一个`usedDisk` 指示符，指示是否有任何聚合阶段由于内存限制而将数据写入临时文件。
`cursor`	文献	可选的。指定游标的初始批处理大小。该`cursor` 字段的值是带有该字段的文档`batchSize`。有关语法和示例，请参见指定初始批处理大小。
`maxTimeMS`	非负整数	可选的。指定用于游标的处理操作的时间限制（以毫秒为单位）。如果未为maxTimeMS指定值，则操作不会超时。值`0`明确指定默认的无限制行为。 MongoDB使用与相同的机制终止超出其分配的时间限制的操作`db.killOp()`。MongoDB仅在其指定的中断点之一处终止操作。
`bypassDocumentValidation`	布尔值	可选的。仅当您指定`$out`或`$merge`聚合阶段时适用。允许`db.collection.aggregate`在操作过程中绕过文档验证。这使您可以插入不符合验证要求的文档。 3.2版中的新功能。
`readConcern`	文献	可选的。指定读取关注。从MongoDB 3.6开始，readConcern选项具有以下语法： `readConcern: { level: <value> }` 可能的阅读关注级别为： `"local"`。当与因果一致的会话相关联时，这是针对主要对象的读取操作和针对次要对象的读取操作的默认读取关注级别。 `"available"`。当不与因果关系一致的会话关联时，这是针对次要对象的读取的默认设置。该查询返回实例的最新数据。 `"majority"`。可用于使用WiredTiger存储引擎的副本集。 `"linearizable"`。仅可用于读取操作 `primary`。有关阅读关注级别的更多信息，请参阅阅读关注级别。从MongoDB 4.2开始，此`$out`阶段不能与“关注”一起使用`"linearizable"`。也就是说，如果您为指定了`"linearizable"`读取关注 `db.collection.aggregate()`，则不能将`$out`阶段包括在管道中。该`$merge`阶段不能与已关注的内容一起使用`"linearizable"`。也就是说，如果您为指定了 `"linearizable"`读取关注 `db.collection.aggregate()`，则不能将`$merge`阶段包括在管道中。
`collation`	文献	可选的。指定用于操作的排序规则。归类允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。排序规则选项具有以下语法：复制 collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } 指定排序规则时，该`locale`字段为必填字段；所有其他排序规则字段都是可选的。有关字段的说明，请参见整理文档。如果未指定排序规则，但是集合具有默认排序规则（请参阅参考资料`db.createCollection()`），则该操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，则MongoDB使用先前版本中使用的简单二进制比较进行字符串比较。您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。 3.4版的新功能。
`hint`	字符串或文件	可选的。用于聚合的索引。索引位于运行聚合的初始集合/视图上。通过索引名称或索引规范文档指定索引。注意该`hint`不适`$lookup`和 `$graphLookup`阶段。 3.6版的新功能。
`comment`	串	可选的。用户可以指定任意字符串，以帮助通过数据库概要分析器，currentOp和日志来跟踪操作。 3.6版的新功能。
`writeConcern`	文献	可选的。表示与or 阶段一起使用的写关注点的文档。`$out$merge` 忽略对`$out`or `$merge`阶段使用默认的写关注。

返回值：	一个光标通过聚集流水线操作的最后阶段产生的文件，或者如果包括 `explain`选项，提供了聚集操作的处理细节的文件。如果管道包含`$out`运算符，则 `aggregate()`返回一个空游标。请参阅 `$out`以获取更多信息。

行为¶

错误处理¶

如果发生错误，则aggregate()助手将引发异常。

游标行为¶

在mongo外壳程序中，如果db.collection.aggregate()未使用var关键字将从返回的光标分配给变量，则mongo外壳程序会自动将光标最多迭代20次。请参阅在mongo Shell中迭代游标以在Shell中处理游标 mongo。

从聚合返回的游标仅支持对评估的游标（即已检索到第一批游标的游标）进行操作的游标方法，例如以下方法：

`cursor.hasNext()` `cursor.next()` `cursor.toArray()` `cursor.forEach()`	`cursor.map()` `cursor.objsLeftInBatch()` `cursor.itcount()` `cursor.pretty()`

也可以看看

有关更多信息，请参见“ 聚合管道”，“ 聚合参考”，“ 聚合管道限制 ”和aggregate。

会话¶

版本4.0中的新功能。

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

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

会话空闲超时¶

从MongoDB 3.6开始，MongoDB驱动程序和mongo 外壳程序将所有操作与服务器会话相关联，但未确认的写操作除外。对于未与会话明确关联的操作（即使用Mongo.startSession()），MongoDB驱动程序和mongo外壳程序会创建一个隐式会话并将其与该操作相关联。

如果会话空闲时间超过30分钟，则MongoDB服务器会将会话标记为已过期，并可以随时关闭它。当MongoDB服务器关闭会话时，它还会终止所有正在进行的操作并打开与该会话关联的游标。这包括配置了30分钟noCursorTimeout或maxTimeMS30分钟以上的光标。

对于返回游标的操作，如果游标可能闲置了30分钟以上，请在显式会话中使用发出操作，Session.startSession()并使用refreshSessions命令定期刷新该会话。请参阅以获取更多信息。Session Idle Timeout

交易¶

db.collection.aggregate()可以在多文档交易中使用。

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

您也不能指定该explain选项。

对于在事务外部创建的游标，不能getMore在事务内部调用。
对于在事务中创建的游标，不能getMore在事务外部调用。

重要

在大多数情况下，与单文档写入相比，多文档事务产生的性能成本更高，并且多文档事务的可用性不应代替有效的架构设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）对于您的数据和用例将继续是最佳的。也就是说，在许多情况下，对数据进行适当的建模将最大程度地减少对多文档交易的需求。

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

客户端断开¶

对于db.collection.aggregate()不包含$out或$merge阶段的操作：

从MongoDB 4.2开始，如果发出db.collection.aggregate() 断开连接的客户端在操作完成之前断开连接，则MongoDB将标记db.collection.aggregate()为终止（即killOp在操作上）。

例子¶

以下示例使用orders包含以下文档的集合：

复制

{ _id: 1, cust_id: "abc1", ord_date: ISODate("2012-11-02T17:04:11.102Z"), status: "A", amount: 50 }
{ _id: 2, cust_id: "xyz1", ord_date: ISODate("2013-10-01T17:04:11.102Z"), status: "A", amount: 100 }
{ _id: 3, cust_id: "xyz1", ord_date: ISODate("2013-10-12T17:04:11.102Z"), status: "D", amount: 25 }
{ _id: 4, cust_id: "xyz1", ord_date: ISODate("2013-10-11T17:04:11.102Z"), status: "D", amount: 125 }
{ _id: 5, cust_id: "abc1", ord_date: ISODate("2013-11-12T17:04:11.102Z"), status: "A", amount: 25 }

分组并计算总和¶

以下聚合操作选择状态等于的文档"A"，将匹配的文档按cust_id字段分组，并根据字段的总和计算total每个cust_id字段的 amount，然后按total字段的降序对结果进行排序：

复制

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

该操作返回一个包含以下文档的游标：

复制

{ "_id" : "xyz1", "total" : 100 }
{ "_id" : "abc1", "total" : 75 }

该mongo壳自动遍历返回的光标打印结果。请参阅在mongo Shell中迭代游标以在shell中手动处理游标mongo。

返回有关聚合管道操作的信息¶

以下示例用于db.collection.explain()查看有关聚合管道执行计划的详细信息。

复制

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

该操作将返回一个文档，其中详细说明了聚合管道的处理。例如，除其他细节外，文档还可以显示所使用的操作的索引（如果有）。[1] 如果orders集合是分片集合，则文档还将显示分片与合并操作之间的分工，对于目标查询，目标分片也将显示。

注意

explain输出文档的目标读者是人，而不是机器，并且输出格式在各个发行版之间可能会发生变化。

您可以通过将executionStats或allPlansExecution解释模式传递给 db.collection.explain()方法来查看更多详细的解释输出。

[1]	索引过滤器会影响所用索引的选择。有关详细信息，请参见索引过滤器。

使用外部排序执行大型排序操作¶

聚合管道阶段具有最大的内存使用限制。要处理大型数据集，请将 allowDiskUseoption设置true为启用以将数据写入临时文件，如以下示例所示：

复制

var results = db.stocks.aggregate(
                                   [
                                     { $project : { cusip: 1, date: 1, price: 1, _id: 0 } },
                                     { $sort : { cusip : 1, date: 1 } }
                                   ],
                                   {
                                     allowDiskUse: true
                                   }
                                 )

从MongoDB 4.2开始，事件探查器日志消息和诊断日志消息包括一个usedDisk 指示符，指示是否有任何聚合阶段由于内存限制而将数据写入临时文件。

指定初始批量大小¶

要为游标指定初始批处理大小，请对该选项使用以下语法cursor：

复制

cursor: { batchSize: <int> }

例如，以下聚合操作指定游标的初始批处理大小0：

复制

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

“ a batchSize” 0表示第一批产品为空，可用于快速返回游标或失败消息，而无需进行大量服务器端工作。与其他MongoDB游标一样，为OP_GET_MORE操作指定后续的批处理大小。

该mongo壳自动遍历返回的光标打印结果。请参阅在mongo Shell中迭代游标以在shell中手动处理游标mongo。

指定归类¶

3.4版的新功能。

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

集合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 } }
);

注意

如果执行涉及多个视图的聚合（例如with $lookup或）$graphLookup，则这些视图必须具有相同的排序规则。

有关整理字段的说明，请参见整理文档。

提示索引¶

3.6版的新功能。

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

复制

db.foodColl.insert([
   { _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 }
])

创建以下索引：

复制