db.collection.aggregate()

Error Handling错误处理

If an error occurs, the aggregate() helper throws an exception.如果发生错误，aggregate()助手将抛出异常。

Cursor Behavior游标行为

In mongosh, if the cursor returned from the db.collection.aggregate() is not assigned to a variable using the var keyword, then mongosh automatically iterates the cursor up to 20 times. 在mongosh中，如果从db.collection.aggregate()返回的游标没有使用var关键字分配给变量，则mongosh会自动迭代游标最多20次。See Iterate a Cursor in mongosh for handling cursors in mongosh.有关在mongosh中处理游标的信息，请参阅在mongosh中迭代游标。

Cursors returned from aggregation only supports cursor methods that operate on evaluated cursors (i.e. cursors whose first batch has been retrieved), such as the following methods:从聚合返回的游标仅支持对评估的游标（即第一批已检索的游标）进行操作的游标方法，例如以下方法：

Sessions会话

For cursors created inside a session, you cannot call getMore outside the session.对于在会话内创建的游标，不能在会话外调用getMore。

Similarly, for cursors created outside of a session, you cannot call getMore inside a session.类似地，对于在会话外部创建的游标，不能在会话内部调用getMore。

Transactions事务

db.collection.aggregate() can be used inside multi-document transactions.可以在多文档事务中使用。

However, the following stages are not allowed within transactions:但是，事务中不允许以下阶段：

• $collStats
• $currentOp
• $indexStats
• $listLocalSessions
• $listSessions
• $out
• $merge
• $planCacheStats

You also cannot specify the explain option.您也不能指定explain选项。

• For cursors created outside of a transaction, you cannot call getMore inside the transaction.对于在事务外部创建的游标，不能在事务内部调用getMore。
• For cursors created in a transaction, you cannot call getMore outside the transaction.对于事务中创建的游标，不能在事务外部调用getMore。

Client Disconnection客户端断开连接

For db.collection.aggregate() operation that do not include the $out or $merge stages:对于不包括db.collection.aggregate()或$merge阶段的db.collection.aggregate()操作：

Starting in MongoDB 4.2, if the client that issued the db.collection.aggregate() disconnects before the operation completes, MongoDB marks the db.collection.aggregate() for termination (i.e. killOp on the operation).从MongoDB 4.2开始，如果发出db.collection.aggregate()的客户端在操作完成之前断开连接，MongoDB将db.collection.aggregate()标记为终止（即，在操作上killOp）。

Group by and Calculate a Sum分组并计算总和

The following aggregation operation selects documents with status equal to "A", groups the matching documents by the cust_id field and calculates the total for each cust_id field from the sum of the amount field, and sorts the results by the total field in descending order:以下聚合操作选择状态等于"A"的文档，按cust_id字段对匹配文档进行分组，并根据amount字段的total计算每个cust_ id字段的总和，并按总和字段按降序对结果进行排序：

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

The operation returns a cursor with the following documents:该操作返回包含以下文档的游标：

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

mongosh iterates the returned cursor automatically to print the results. mongosh自动迭代返回的游标以打印结果。See Iterate a Cursor in mongosh for handling cursors manually in mongosh.有关在mongosh中手动处理游标的信息，请参阅在mongosh中迭代游标。

Return Information on Aggregation Pipeline Operation返回聚合管道操作的信息

The following example uses db.collection.explain() to view detailed information regarding the execution plan of the aggregation pipeline.以下示例使用db.collection.explain()查看有关聚合管道执行计划的详细信息。

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

The operation returns a document that details the processing of the aggregation pipeline. For example, the document may show, among other details, which index, if any, the operation used. 该操作返回一个文档，详细说明聚合管道的处理。例如，除其他细节外，文档可以显示所使用的操作的索引（如果有的话）。[1] If the orders collection is a sharded collection, the document would also show the division of labor between the shards and the merge operation, and for targeted queries, the targeted shards.如果orders集合是分片集合，文档还将显示分片和合并操作之间的分工，对于目标查询，显示目标分片。

You can view more verbose explain output by passing the executionStats or allPlansExecution explain modes to the db.collection.explain() method.通过将executionStats或allPlansExecution解释模式传递给db.collection.explain()方法，可以查看更详细的解释输出。

Perform Large Sort Operation with External Sort使用外部排序执行大型排序操作

Each individual pipeline stage has a limit of 100 megabytes of RAM. 每个单独的流水线级的RAM限制为100兆字节。By default, if a stage exceeds this limit, MongoDB produces an error. 默认情况下，如果某个阶段超过此限制，MongoDB将生成错误。To allow pipeline processing to take up more space, set the allowDiskUse option to true to enable writing data to temporary files, as in the following example:要允许管道处理占用更多空间，请将allowDiskUse选项设置为true，以允许将数据写入临时文件，如下例所示：

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

Starting in MongoDB 4.2, the profiler log messages and diagnostic log messages includes a usedDisk indicator if any aggregation stage wrote data to temporary files due to memory restrictions.从MongoDB 4.2开始，如果任何聚合阶段由于内存限制而将数据写入临时文件，则探查器日志消息和诊断日志消息将包含一个usedDisk指示符。

Specify an Initial Batch Size指定初始批量大小

To specify an initial batch size for the cursor, use the following syntax for the cursor option:要为游标指定初始批大小，请使用以下语法作为cursor选项：

cursor: { batchSize: <int> }

For example, the following aggregation operation specifies the initial batch size of 0 for the cursor:例如，以下聚合操作指定游标的初始批大小为0：

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

A batchSize of 0 means an empty first batch and is useful for quickly returning a cursor or failure message without doing significant server-side work. batchSize为0表示第一批为空，对于快速返回游标或失败消息非常有用，而无需进行大量服务器端工作。Specify subsequent batch sizes to OP_GET_MORE operations as with other MongoDB cursors.与其他MongoDB游标一样，为OP_GET_MORE操作指定后续批处理大小。

mongosh iterates the returned cursor automatically to print the results. 自动迭代返回的游标以打印结果。See Iterate a Cursor in mongosh for handling cursors manually in mongosh.有关在mongosh中手动处理游标的信息，请参阅在mongosh中迭代游标。

Specify a Collation指定排序规则

Collation排序规则 allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.允许用户为字符串比较指定特定于语言的规则，如字母大小写和重音符号规则。

A collection myColl has the following documents:集合myColl具有以下文档：

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

The following aggregation operation includes the collation option:以下聚合操作包括排序规则选项：

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

For descriptions on the collation fields, see Collation Document.有关排序规则字段的说明，请参阅排序规则文档。

Hint an Index提示索引

Create a collection foodColl with the following documents:使用以下文档创建集合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 }
] )

Create the following indexes:创建以下索引：

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

The following aggregation operation includes the hint option to force the usage of the specified index:以下聚合操作包括hint选项以强制使用指定索引：

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

Override 覆盖readConcern

Use the readConcern option to specify the read concern for the operation.使用readConcern选项指定操作的读取关注点。

You cannot use the $out or the $merge stage in conjunction with read concern "linearizable". 您不能将$out或$merge阶段与读取关注点"linearizable"结合使用。That is, if you specify "linearizable" read concern for db.collection.aggregate(), you cannot include either stages in the pipeline.也就是说，如果为db.collection.aggregate()指定"linearizable"读取关注点，则不能在管道中包含任何阶段。

The following operation on a replica set specifies a Read Concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.对副本集的以下操作指定"majority"的读取关注点，以读取确认已写入大多数节点的数据的最新副本。

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

Specify a Comment指定注释

A collection named movies contains documents formatted as such:名为movies的集合包含格式如下的文档：

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

The following aggregation operation finds movies created in 1995 and includes the comment option to provide tracking information in the logs, the db.system.profile collection, and db.currentOp.下面的聚合操作将查找1995年创建的电影，并包括comment选项，以在logs、db.system.profile集合和db.currentOp中提供跟踪信息。

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

On a system with profiling enabled, you can then query the system.profile collection to see all recent similar aggregations, as shown below:在启用了分析的系统上，您可以查询system.profile集合以查看所有最近的类似聚合，如下所示：

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

This will return a set of profiler results in the following format:这将以以下格式返回一组探查器结果：

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

An application can encode any arbitrary information in the comment in order to more easily trace or identify specific operations through the system. 应用程序可以对注释中的任意信息进行编码，以便更容易地通过系统跟踪或识别特定操作。For instance, an application might attach a string comment incorporating its process ID, thread ID, client hostname, and the user who issued the command.例如，应用程序可能会附加一个字符串注释，其中包含进程ID、线程ID、客户端主机名和发出命令的用户。

Use Variables in let在let中使用变量

To define variables that you can access elsewhere in the command, use the let option.要定义可以在命令中其他位置访问的变量，请使用let选项。

Create a collection cakeSales containing sales for cake flavors:创建一个包含蛋糕口味销售的cakeSales集合：

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

The following example:以下示例：

• retrieves the cake that has a salesTotal greater than 3000, which is the cake with an _id of 2检索salesTotal大于3000的蛋糕，即_id为2的蛋糕
• defines a targetTotal variable in let, which is referenced in $gt as $$targetTotal在let中定义targetTotal变量，该变量在$gt中被引用为$$targetTotal

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