db.collection.aggregate()

在本页面

Definition

Parameter Type Description
pipeline array 数据聚合操作或阶段的序列。有关详情，请参见聚合管道运算符。


在 2.6 版中进行了更改：该方法仍然可以将管道阶段作为单独的参数而不是数组中的元素接受；但是，如果不将pipeline指定为数组，则不能指定options参数。
| options |文档|可选。 aggregate()传递给aggregate命令的其他选项。
2.6 版中的新增功能：仅当您将pipeline指定为数组时才可用。

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

Field Type Description
explain boolean 可选的。指定返回有关管道处理的信息。有关示例，请参见返回汇总管道操作信息。


2.6 版中的新功能。
| allowDiskUse |布尔值|可选。允许写入临时文件。设置为true时，大多数聚合操作可以将数据写入dbPath目录中的_tmp子目录，但以下情况除外：

$graphLookup stage
$group阶段中使用的$addToSet累加器表达式(从版本 3.6.17 开始)
$group阶段中使用的$push累加器表达式(从版本 3.6.17 开始)
有关allowDiskUse的示例，请参见使用外部排序执行大型排序操作。
2.6 版中的新功能。
| cursor |文档|可选。指定游标的“初始”批处理大小。 cursor字段的值是带有字段batchSize的文档。有关语法和示例，请参见指定初始批次大小。
2.6 版中的新功能。
| maxTimeMS |非负整数|可选。指定用于游标的处理操作的时间限制(以毫秒为单位)。如果未为 maxTimeMS 指定值，则操作不会超时。值0明确指定默认的无限制行为。
MongoDB 使用与db.killOp()相同的机制终止超出其分配的时间限制的操作。 MongoDB 仅在其指定的interrupt points之一处终止操作。
| bypassDocumentValidation |布尔值|可选。仅当您指定$out聚合运算符时才可用。
使db.collection.aggregate在操作过程中绕过文档验证。这使您可以插入不符合验证要求的文档。
版本 3.2 中的新功能。
| readConcern |文档|可选。指定read concern。
readConcern 选项具有以下语法：
在版本 3.6 中更改。
readConcern: { level: <value> }
可能的阅读关注级别为：
"local"。这是默认的阅读关注级别。
"available"。当未指定读取操作和因果一致的会话和“ level”时，这是针对次要对象的读取的默认值。查询返回实例的最新数据。
"majority"。可用于使用WiredTiger 存储引擎的副本集。
"linearizable"。仅可用于primary上的读取操作。
有关阅读关注级别的更多信息，请参阅阅读关注级别。
对于"local"(默认)或"majority"读关注级别，您可以指定afterClusterTime选项以使读操作返回满足级别要求和在群集时间之后指定的数据。有关更多信息，请参见读取操作和因果一致的会话。
| collation |文档|可选。
指定用于操作的collation。
Collation允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。
排序规则选项具有以下语法：
collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}
指定排序规则时，locale字段为必填字段；所有其他排序规则字段都是可选的。有关字段的说明，请参见Collation Document。
如果未指定排序规则，但是集合具有默认排序规则(请参见db.createCollection())，则该操作将使用为集合指定的排序规则。
如果没有为集合或操作指定排序规则，则 MongoDB 使用先前版本中使用的简单二进制比较进行字符串比较。
您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。
3.4 版中的新功能。
| hint |字符串或文档|可选。用于聚合的索引。索引位于运行聚合的初始集合/视图上。
通过索引名称或索引规范文档指定索引。

Note





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



3.6 版中的新功能。
| comment |字符串|可选。用户可以指定任意字符串，以帮助通过数据库概要分析器，currentOp 和日志来跟踪操作。
3.6 版中的新功能。

返回： A cursor到聚合管道操作的最后阶段生成的文档，或者，如果包含explain选项，则该文档提供有关聚合操作处理的详细信息。
如果管道包含$out运算符，则aggregate()返回空游标。有关更多信息，请参见$out。
在 2.6 版中进行了更改：db.collection.aggregate()方法返回一个游标，并且可以返回任何大小的结果集。早期版本将所有结果返回到一个文档中，并且结果集的大小限制为 16 MB。

Behavior

Error Handling

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

Cursor Behavior

在mongo shell 中，如果未使用var关键字将db.collection.aggregate()返回的光标分配给变量，则mongo shell 将自动将光标最多迭代 20 次。有关在mongo shell 中处理游标的信息，请参见在 mongo Shell 中迭代游标。

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

cursor.hasNext()

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

See also

有关更多信息，请参见Aggregation Pipeline，Aggregation Reference，聚合管道限制和aggregate。

会话空闲超时

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

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

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

Examples

以下示例使用包含以下文档的集合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字段分组，并根据amount字段的总和为每个cust_id字段计算total，然后按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 shell 自动迭代返回的光标以打印结果。有关在mongo shell 中手动处理游标的信息，请参见在 mongo Shell 中迭代游标。

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

以下聚合操作将选项explain设置为true，以返回有关聚合操作的信息。

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

该操作返回带有文档的游标，该文档包含有关聚合管道处理的详细信息。例如，除其他细节外，文档还可以显示所使用的操作的索引(如果有)。 [1]如果orders集合是分片集合，则文档还将显示分片和合并操作之间的分工，对于目标查询，也将显示目标分片。

Note

explain输出文档的目标 Reader 是人，而不是机器，并且输出格式可能在各个发行版之间进行更改。

mongo shell 自动迭代返回的光标以打印结果。有关在mongo shell 中手动处理游标的信息，请参见在 mongo Shell 中迭代游标。

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

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

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

指定初始批次大小

要为游标指定初始批处理大小，请对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 }
                     }
                   )

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

mongo shell 自动迭代返回的光标以打印结果。有关在mongo shell 中手动处理游标的信息，请参见在 mongo Shell 中迭代游标。

指定排序规则

3.4 版的新功能。

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

集合myColl具有以下文档：

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

以下聚合操作包括collation选项：

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

Note

如果执行涉及多个视图的聚合(例如$lookup或$graphLookup)，则这些视图必须具有相同的collation。

有关整理字段的说明，请参见Collation Document。

提示索引

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 }
])

创建以下索引：

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 } }
)

Override readConcern

对副本集的以下操作指定Read Concern到"majority"来读取已确认已写入大多数节点的数据的最新副本。

Note

从 MongoDB 3.6 开始，默认情况下启用对读取关注"majority"的支持。对于 MongoDB 3.6.1-3.6.x，您可以禁用阅读关注"majority"。有关更多信息，请参见禁用多数阅读关注。

  • 为确保单个线程可以读取其自己的写入，请对副本集的主数据库使用"majority"读取关注和"majority"写入关注。

  • 要使用read concern级别"majority"，不能包含$out阶段。

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

db.restaurants.aggregate(
   [ { $match: { rating: { $lt: 5 } } } ],
   { readConcern: { level: "majority" } }
)
[1] Index Filters会影响所用索引的选择。有关详情，请参见Index Filters。

指定 Comment

名为movies的集合包含以下格式的文档：

{
  "_id" : ObjectId("599b3b54b8ffff5d1cd323d8"),
  "title" : "Jaws",
  "year" : 1975,
  "imdb" : "tt0073195"
}

以下聚合操作查找 1995 年创建的电影，并包含comment选项以在logs，db.system.profile集合和db.currentOp中提供跟踪信息。

db.movies.aggregate( [ { $match: { year : 1995 } } ], { comment : "match_all_movies_from_1995" } ).pretty()

然后，在启用了概要分析的系统上，您可以查询system.profile集合以查看所有最近的类似聚合，如下所示：

db.system.profile.find( { "command.aggregate": "movies", "command.comment" : "match_all_movies_from_1995" } ).sort( { ts : -1 } ).pretty()

这将以以下格式返回一组探查器结果：

{
  "op" : "command",
  "ns" : "video.movies",
  "command" : {
    "aggregate" : "movies",
    "pipeline" : [
      {
        "$match" : {
          "year" : 1995
        }
      }
    ],
    "comment" : "match_all_movies_from_1995",
    "cursor" : {

    },
    "$db" : "video"
  },
  ...
}

应用程序可以对 Comments 中的任意信息进行编码，以便更轻松地通过系统跟踪或识别特定操作。例如，应用程序可能会附加一个字符串 Comments，其中包含其进程 ID，线程 ID，Client 端主机名和发出命令的用户。

首页