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中处理游标的信息，请参阅在mongoh中迭代游标。

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:对于不包括$out或$merge阶段的db.collection.aggregate()操作：

Starting in MongoDB 4.2, if the client that issued db.collection.aggregate() disconnects before the operation completes, MongoDB marks db.collection.aggregate() for termination using killOp.从MongoDB 4.2开始，如果发出db.collection.aggregate()的客户端在操作完成前断开连接，MongoDB会使用killOp标记db.collection.aggregate()终止。

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字段的总和计算每个cust_id域的合计，然后按total字段降序对结果进行排序：

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. 自动迭代返回的游标以打印结果。See Iterate a Cursor in mongosh for handling cursors manually in mongosh.有关在mongosh中手动处理游标的信息，请参阅在mongoh中迭代游标。

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()方法，可以查看更详细的解释输出。

Interaction with allowDiskUseByDefault与allowDiskUseByDefault交互

Starting in MongoDB 6.0, pipeline stages that require more than 100 megabytes of memory to execute write temporary files to disk by default. 从MongoDB 6.0开始，需要超过100MB内存才能执行的管道阶段默认情况下会将临时文件写入磁盘。In earlier verisons of MongoDB, you must pass { allowDiskUse: true } to individual find and aggregate commands to enable this behavior.在MongoDB的早期版本中，必须将{ allowDiskUse: true }传递给单个find和aggregate命令才能启用此行为。

Individual find and aggregate commands may override the allowDiskUseByDefault parameter by either:单独的find和aggregate命令可以通过以下方式覆盖allowDiskUseByDefault参数：

• Using { allowDiskUse: true } to allow writing temporary files out to disk when allowDiskUseByDefault is set to false当allowDiskUseByDefault设置为false时，使用{ allowDiskUse: true }允许将临时文件写入磁盘
• Using { allowDiskUse: false } to prohibit writing temporary files out to disk when allowDiskUseByDefault is set to true当allowDiskUseByDefault设置为true时，使用{ allowDiskUse: false }禁止将临时文件写入磁盘

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

The { cursor: { batchSize: 0 } } document, which specifies the size of the initial batch size, indicates an empty first batch. 指定初始批大小的{ cursor: { batchSize: 0 } }文档表示第一批为空。This batch size is useful for quickly returning a cursor or failure message without doing significant server-side work.这个批量大小对于快速返回游标或失败消息非常有用，而不需要做大量的服务器端工作。

To specify batch size for subsequent getMore operations (after the initial batch), use the batchSize field when running the getMore command.要为后续的getMore操作指定批处理大小（在初始批处理之后），请在运行getMore命令时使用batchSize字段。

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

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:以下聚合操作包括collation选项：

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