db.collection.aggregate()

在本页面

定义

  • db.collection. aggregate(管道,选项)

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

参数

类型

描述

pipeline

array

一系列数据聚合操作或阶段。有关详细信息,请参阅聚合管道运算符。 在 version 2.6 中更改:该方法仍然可以接受管道阶段作为单独的 arguments 而不是 array 中的元素;但是,如果未将pipeline指定为 array,则无法指定options参数。

options

document

可选的。 aggregate()传递给aggregate命令的其他选项。 version 2.6 中的新内容:仅当您将pipeline指定为 array 时才可用。

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

字段

类型

描述

explain

boolean

可选的。指定 return 有关管道处理的信息。有关 example,请参见返回有关聚合管道操作的信息。 version 2.6 中的新内容。 在多文档交易中不可用。

allowDiskUse

boolean

可选的。允许写入临时文件。设置为时 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

document

可选的。指定游标的初始批处理大小。 cursor字段的 value 是一个带有batchSize字段的文档。有关语法和 example,请参阅指定初始批量大小。 version 2.6 中的新内容。

maxTimeMS

non-negative integer

可选的。指定处理游标操作的 time 限制(以毫秒为单位)。如果没有为 maxTimeMS 指定 value,则操作不会 timeout。 0的 value 显式指定默认的无界行为。 MongoDB 使用与db.killOp()相同的机制终止超出其分配的 time 限制的操作。 MongoDB 仅在其指定的中断点之一处终止操作。

bypassDocumentValidation

boolean

可选的。仅在指定$out或$merge]聚合阶段时可用。 在操作期间启用db.collection.aggregate以绕过文档验证。这使您可以插入不符合验证要求的文档。 version 3.2 中的新内容。

readConcern

document

可选的。指定读关注。 readConcern 选项具有以下语法: 在 version 3.6 中更改。 readConcern: { level: <value> } 可能的阅读关注级别为: “local”。这是 level 的默认读取问题。 “available”。当阅读操作和 Causally Consistent Sessions和“level”未指定时,这是对二级的读取的默认值。查询返回实例的最新数据。 “manority”。适用于使用WiredTiger 存储引擎的副本集。 “linerizable”。仅适用于主的读取操作。 有关读取关注级别的更多信息,请参阅读关注级别。 从MongoDB 4.2开始,该$out阶段不能与读取关注一起使用"linearizable"。也就是说,如果您为指定了"linearizable"读取关注 db.collection.aggregate(),则不能将$out阶段包括 在管道中。 该$merge阶段不能与已关注的内容一起使用"linearizable"。也就是说,如果您为指定了 "linearizable"读取关注 db.collection.aggregate(),则不能将$merge阶段包括 在管道中。

collation

document

可选的。 指定要用于操作的整理。 整理允许用户为 string 比较指定 language-specific 规则,例如字母和重音标记的规则。 排序规则选项具有以下语法: 排序规则:{ locale:<string>, caseLevel:<boolean>, caseFirst:<string>, strength:<int>, numericOrdering:<boolean>, alternate:<string>, maxVariable:<string>, backwards :<boolean> } 指定排序规则时,locale字段是必填字段;所有其他校对字段都是可选的。有关字段的说明,请参阅整理文件。 如果未指定排序规则但集合具有默认排序规则(请参阅db.createCollection(),则操作将使用为集合指定的排序规则。 如果没有为集合或操作指定排序规则,MongoDB 使用先前版本中用于 string 比较的简单二进制比较。 您无法为操作指定多个排序规则。对于 example,您不能为每个字段指定不同的排序规则,或者如果使用排序执行查找,则不能对查找使用一个排序规则,而对排序使用另一个排序规则。 version 3.4 中的新内容。

hint

string or document

可选的。用于聚合的索引。索引位于初始 collection/view,聚合为 run。 通过索引 name 或索引规范文档指定索引。 注意 hint不适用于$lookup$graphLookup阶段。 version 3.6 中的新内容。

comment

string

可选的。用户可以指定任意 string 以帮助通过数据库探查器,currentOp 和日志跟踪操作。 version 3.6 中的新内容。

writeConcern

document

可选的。表示 与or 阶段一起使用的[写关注点](的文档。$out $merge 忽略对$outor $merge阶段使用默认的写关注。

返回值:

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

行为

错误处理

如果发生错误,aggregate()帮助程序将抛出 exception。

游标行为

在mongo shell 中,如果从db.collection.aggregate()返回的游标未使用var关键字分配给变量,则mongo shell 会自动迭代光标 20 次。请参阅在 mongo Shell 中迭代一个 Cursor以处理mongo shell 中的游标。

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

cursor.hasNext() cursor.next() cursor.toArray() cursor.forEach()

cursor.map() cursor.objsLeftInBatch() cursor.itcount() cursor.pretty()

也可以看看

有关更多信息,请参阅聚合管道,聚合参考,聚合管道限制和聚合。

会话

版本4.0中的新功能。

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

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

会话空闲超时

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

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

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

事务

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

但是,事务中不允许以下阶段:

  • $collStats

  • $currentOp

  • $indexStats

  • $listLocalSessions

  • $listSessions

  • $out

  • $merge

  • $planCacheStats

您也不能指定该explain选项。

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

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

重要

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

有关其他事务使用方面的注意事项(例如运行时限制和操作日志大小限制),另请参见 生产注意事项。

客户端断开

对于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字段对匹配文档进行分组,并从amount字段的总和计算每个cust_id字段的total,并按降序 order 中的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 中迭代一个 Cursor。

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

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

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

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

注意

explain输出文档的预期 readers 是人类,而不是机器,输出格式可能会在不同版本之间发生变化。

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

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

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

聚合管道阶段有最大 memory 使用限制。要处理大型数据集,请将allowDiskUse选项设置为true以启用将数据写入临时 files,如下面的示例所示:

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

从MongoDB 4.2开始,事件profiler log massages和diagnostic log massages包括一个usedDisk 指示符,指示是否有任何聚合阶段由于内存限制而将数据写入临时文件。

指定初始批量大小

要指定游标的初始批处理大小,请对cursor选项使用以下语法:

cursor: { batchSize: <int> }

对于 example,以下聚合操作指定游标的初始批处理大小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表示空的第一批,对于快速返回游标或失败消息而不执行重要的 server-side 工作非常有用。与其他 MongoDB 游标一样,将后续批量大小指定为OP_GET_MORE操作。

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

指定排序规则

version 3.4 中的新内容。

整理允许用户为 string 比较指定 language-specific 规则,例如字母和重音标记的规则。

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

注意

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

有关归类字段的说明,请参阅整理文件。

提示索引

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

覆盖 readConcern

使用该readConcern选项可以指定操作的读取关注点。

您不能将$out$merge阶段与阅读关注结合使用"linearizable"。也就是说,如果您为指定了"linearizable"读取关注 db.collection.aggregate(),则不能在管道中包括任何一个阶段。

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

注意

  • 要使用“多数”的阅读关注 level,replica sets 必须使用WiredTiger 存储引擎并选举protocol version 1。从 MongoDB 3.6 开始,默认情况下启用对读取问题“多数”的支持。对于 MongoDB 3.6.1 - 3.6.x,您可以禁用读取关注“多数”。有关更多信息,请参阅禁用阅读关注多数。

  • 要确保单个线程可以读取自己的写入,请对副本集的主要使用“多数”读取关注和“多数”写入问题。

  • 要使用“多数”的阅读关注 level,您不能包含$out阶段。

  • 无论阅读关注 level 如何,节点上的最新数据可能无法反映系统中数据的最新 version。

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

指定 Comment

名为movies的集合包含格式如下的文档:

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

以下聚合操作查找在 1995 年创建的影片,并包含comment选项以在logsdb.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"
},
...
}

应用程序可以编码 order 中的任意信息,以便更轻松地跟踪或识别系统中的特定操作。例如,application 可能附加 string comment,其中包含 process ID,线程 ID,client 主机名和发出命令的用户。

译者:李冠飞

校对: