聚合管道快速参考
注意
有关特定操作符(包括事务语法和示例)的详细信息,请单击该操作符的参考页面链接。
您可以在用户界面中为MongoDB Atlas托管的部署构建聚合管道。
阶段(Stages)
阶段 (db.collection.aggregate
)
在 db.collection.aggregate()
方法中,管道阶段出现在数组中。文档按顺序经历这些阶段。除$out
、 $merge
和$geoNear
阶段之外的所有阶段都可以在管道中出现多次。
db.collection.aggregate( [ { <stage> }, ... ] )
阶段 | 说明 |
---|---|
为文档添加新字段。与 | |
根据指定的表达式和存储桶边界将传入的文档分为多个组(称为存储桶)。 | |
根据指定的表达式,将接收到的文档归类到特定数量的群组中(称为“存储桶”)。自动确定存储桶边界,以尝试将文档均匀地分配到指定数量的存储桶中。 | |
返回集合的 Change Stream 游标。此阶段只能在 aggregation pipeline 中发生一次,并且必须作为第一阶段发生。 | |
返回有关集合或视图的统计信息。 | |
返回聚合管道此阶段的文档数量计数。 有别于 | |
在单个阶段内处理同一组输入文档上的多个聚合管道。支持创建多分面聚合,能够在单个阶段中跨多个维度或分面描述数据特征。 | |
对集合执行递归搜索。为每个输出文档添加一个新数组字段,其中包含该文档的递归搜索遍历结果。 | |
按指定的标识符表达式对输入文档进行分组,并将累加器表达式(如果指定)应用于每个群组。接收所有输入文档,并为每个不同群组输出一个文档。输出文档仅包含标识符字段和累积字段(如果指定)。 | |
返回有关集合的每个索引使用情况的统计信息。 | |
将未修改的前 n 个文档传递到管道,其中 n 为指定的限制。对于每个输入文档,输出一个文档(针对前 n 个文档)或零个文档(前 n 个文档之后)。 | |
列出活动时间足够长、足以传播到 system.sessions 集合的所有会话。 | |
对同一 数据库中的另一个集合执行左外连接,以过滤“已连接”集合中的文档以便进行处理。 | |
筛选文档流以仅允许匹配的文档将未修改的文档传入下一管道阶段。 $match 使用标准 MongoDB 查询。对于每个输入文档,输出一个文档(一个匹配项)或零个文档(无匹配项)。 | |
将 aggregation pipeline 的结果文档写入集合。该阶段可将结果(插入新文档、合并文档、替换文档、保留现有文档、操作失败、使用自定义更新管道处理文档)纳入输出集合。要使用 $merge 阶段,它必须是管道中的最后一个阶段。 | |
将 aggregation pipeline 的结果文档写入集合。要使用 $out 阶段,它必须是管道中的最后一个阶段。 | |
返回集合的计划缓存信息。 | |
重塑流中的每个文档,例如添加新的字段或删除现有字段。对于每个输入文档,输出一个文档。 另请参阅 | |
用指定的嵌入文档替换文档。该操作会替换输入文档中的所有现有字段,包括
| |
用指定的嵌入文档替换文档。该操作会替换输入文档中的所有现有字段,包括
| |
从其输入中随机选择指定数量的文件。 | |
对 Atlas 集合中的一个或多个字段执行全文搜索。 注意
| |
为文档添加新字段。与
| |
将文档分组到窗口中,并将一个或多个操作符应用于每个窗口中的文档。 版本 5.0 中的新增功能。 | |
跳过前 n 个文档,其中 n 是指定的跳过编号,并将未修改的剩余文档传递到管道。对于每个输入文档,输出零个文档(对于前 n 个文档)或一个文档(如果在前 n 个文档之后)。 | |
按指定的排序键对文档流重新排序。仅顺序会改变,而文档则保持不变。对于每个输入文档,输出一个文档。 | |
根据指定表达式的值对传入文档进行分组,然后计算每个不同群组中的文档数量。 | |
执行两个集合的联合;即将两个集合的管道结果合并到一个结果集中。 | |
对输入文档中的某一数组字段进行解构,以便为每个元素输出文档。每个输出文档均会将此数组替换为元素值。对于每个输入文档,输出 n 个文档,其中 n 为数组元素的数量,且对于空数组可为零。 |
阶段 (db.aggregate
)
从版本 3.6 开始,MongoDB 还提供db.aggregate()
方法:
db.aggregate( [ { <stage> }, ... ] )
以下阶段使用 db.aggregate()
方法,而不是 db.collection.aggregate()
方法。
阶段 | 说明 |
---|---|
返回集合的 Change Stream 游标。此阶段只能在 aggregation pipeline 中发生一次,并且必须作为第一阶段发生。 | |
返回 MongoDB 部署的活动和/或休眠操作的信息。 | |
可更新的阶段
从 MongoDB 4.2 开始,您可以使用聚合管道进行更新:
命令 | mongosh 方法 |
---|---|
对于更新,该管道可以由以下阶段组成:
$addFields
及其别名$set
表达式
表达式可以包含字段路径、文字、系统变量、表达式对象和表达式操作符。 表达式可以嵌套。
字段路径
聚合表达式使用字段路径访问输入文档中的字段。要指定字段路径,请在字段名称或虚线字段名称(如果该字段位于嵌入式文档中)前添加美元符号 $
。例如,用 "$user"
指定 user
字段的字段路径,或用 "$user.name"
指定 "user.name"
字段的字段路径。
"$<field>"
等效于 "$$CURRENT.<field>"
,其中 CURRENT
为系统变量,而它默认为当前对象的根(除非在特定阶段另行说明)。
聚合变量
MongoDB 提供了各种用于表达式的聚合系统变量。要访问变量,请在变量名称前加上$$
前缀。 例如:
变量 | 访问方式: $$ | 简要说明 |
---|---|---|
$$NOW | 返回当前日期时间值,该值在部署的所有成员中都是相同的,并且在整个聚合管道中保持不变。 (4.2 及更高版本中可用) | |
$$CLUSTER_TIME | 返回当前时间戳值,该值在部署的所有成员中都是相同的,并且在整个聚合管道中保持不变。 仅适用于副本集和分片集群。 (4.2 及更高版本中可用) | |
$$ROOT | 引用根文档,即顶层文档。 | |
$$CURRENT | 引用字段路径(Field Path)的起始位置,默认为 ROOT ,但可以更改。 | |
$$REMOVE | 允许有条件地排除字段。(3.6 及更高版本中可用) | |
$$DESCEND | $redact 表达式的允许结果之一。 | |
$$PRUNE | $redact 表达式的允许结果之一。 | |
$$KEEP | $redact 表达式的允许结果之一。 |
有关这些变量的更详细说明,请参阅系统变量。
文字
文字可以是任何类型。 但是, MongoDB将以美元符号 $
开头的string字面量解析为字段的路径,并将表达式对象中的数字/布尔字面量解析为投影标志。 要避免解析字面量,请使用$literal
表达式。
表达式对象
表达式对象具有以下形式:
{ <field1>: <expression1>, ... }
如果表达式是数值或布尔字面量,MongoDB 会将这些字面量视为投影标志(例如 1
或true
以包括该字段),仅在$project
阶段有效。 为避免将数字或布尔字面量视为投影标志,请使用$literal
表达式来包装数字或布尔字面量。
操作符表达式
操作符表达式类似于接受参数的函数。通常,这些表达式采用参数数组,并具有以下形式:
{ <operator>: [ <argument1>, <argument2> ... ] }
如果操作符接受单个参数,则可以省略指定参数列表的外部数组:
{ <operator>: <argument> }
如果该参数是一个字面数组,为避免解析歧义,必须在 $literal
表达式中包装此字面数组,或者保留用来指定参数列表的外部数组。
算术表达式操作符
算术表达式对数字执行数学运算。一些算术表达式也可以支持日期算术。
名称 | 说明 |
---|---|
返回一个数字的绝对值。 | |
添加数字以返回总和,或添加数字和日期以返回新日期。如果添加数字和日期,则将数字视为毫秒。接受任意数量的参数表达式,但一个表达式最多只能解析为一个日期。 | |
返回大于或等于指定数字的最小整数。 | |
返回第一个数字除以第二个数字的结果。接受两个参数表达式。 | |
将 e 提升到指定的指数。 | |
返回小于或等于指定数字
最大整数。 | |
计算数字的自然对数。 | |
以指定基数计算数字的对数。 | |
计算一个数字以 10 为底的对数。 | |
返回第一个数字除以第二个数字的余数。接受两个参数表达式。 | |
将数字相乘以返回乘积。接受任意数量的参数表达式。 | |
将一个数字提升到指定的指数。 | |
将数字舍入到整数或指定的小数位。 | |
计算平方根。 | |
返回第一个值减去第二个值后的结果。如果这两个值均为数字,则返回差值。如果这两个值均为日期,则返回以毫秒为单位的差值。如果这两个值一个为日期而另一个为数字(以毫秒为单位),则返回生成的日期。接受两个参数表达式。如果这两个值一个为日期而另一个为数字,请先指定日期参数,因为用数字减去日期没有意义。 | |
将数字截断为整数或指定的小数位。 |
数组表达式操作符
名称 | 说明 |
---|---|
返回位于指定数组索引处的元素。 | |
将键值对数组转换为文档。 | |
连接数组以返回连接后的数组。 | |
选择数组的子集,以返回仅包含与筛选条件匹配的元素的数组。 | |
返回第一个数组元素。 与 $first 累加器不同。 | |
返回一个布尔值,它可表示指定的值是否在数组中。 | |
搜索数组中出现的指定值,并返回首次出现的数组索引。如果未找到该子字符串,则返回 -1 。 | |
确定操作数是否为数组。返回一个布尔值。 | |
返回最后一个数组元素。 与 $last 累加器不同。 | |
对数组的每个元素应用子表达式,并按顺序返回生成值的数组。接受已命名的参数。 | |
将文档转换为表示键值对的文档数组。 | |
根据用户定义的输入,输出一个包含整数序列的数组。 | |
将表达式应用于数组中的每个元素,并将它们组合成一个值。 | |
返回元素顺序相反的数组。 | |
返回数组中元素的个数。接受单个表达式作为参数。 | |
返回数组的子集。 | |
将两个数组进行合并。 |
布尔表达式操作符
布尔表达式可将其参数表达式作为布尔值进行计算,并返回一个布尔值以作为结果。
除 false
布尔值之外,布尔表达式还将以下值计算为 false
:null
、0
和 undefined
值。布尔表达式将所有其他值计算为 true
,包括非零数值和数组。
比较表达式操作符
比较表达式返回一个布尔值,但 $cmp
除外,它返回一个数字。
比较表达式接受两个参数表达式,并使用不同类型的值的指定 BSON 比较顺序来比较值和类型。
条件表达式操作符
自定义聚合表达式操作符
名称 | 说明 |
---|---|
定义自定义累加器函数。 | |
定义自定义函数。 |
数据大小表达式操作符
以下操作符返回数据元素的大小:
名称 | 说明 |
---|---|
返回给定字符串或二进制数据值内容的大小(以字节为单位)。 | |
以字节为单位返回给定文档(即 bsontype Object ) 的大小(当编码为 BSON 时)。 |
日期表达式操作符
以下操作符返回日期对象或日期对象的组件:
名称 | 说明 |
---|---|
向日期对象添加多个时间单位。 | |
返回两个日期之间的差值。 | |
根据日期的组成部分构造一个 BSON 日期对象。 | |
将日期/时间字符串转换为日期对象。 | |
从日期对象中减去多个时间单位。 | |
返回包含日期组成部分的文档。 | |
以格式化字符串的形式返回日期。 | |
截断日期。 | |
以介于 1 和 31 之间的数字返回某一日期的“月中的某一天”。 | |
以 1(星期日)和 7(星期六)之间的数字形式返回以星期表示的日期。 | |
以 1 到 366(闰年)之间的数字形式返回返回日期的年月日。 | |
以数字形式返回日期中的小时部分(0 到 23)。 | |
以 ISO 8601 格式返回工作日数字,范围为 1 (星期一)到 7 (星期日)。 | |
以 ISO 8601 格式返回周数,范围从 1 到 53 。周数从 1 开始,即包含一年中第一个星期四的那个星期(星期一到星期日)。 | |
以 ISO 8601 格式返回年份号。一年从第一周的星期一 (ISO 8601) 开始,到最后一周的星期日 (ISO 8601) 结束。 | |
以 0 到 999 之间的数字形式返回日期的毫秒数。 | |
返回日期的分钟数(0 到 59)。 | |
以 1(一月)到 12(十二月)之间的数字形式返回日期的月份。 | |
以 0 到 60 之间的数字返回日期的秒数(跳秒)。 | |
将数值转换为日期。 | |
以 0(一年中第一个星期日之前的部分周)和 53(闰年)之间的数字形式返回日期的周数。 | |
以数字形式返回日期的年份(例如 2014)。 |
以下算术操作符可以使用日期操作数:
字面值表达式操作符
其他操作符
名称 | 说明 |
---|---|
从文档中返回指定字段的值。您可以使用 版本 5.0 中的新增功能。 | |
返回介于 0 和 1 之间的随机浮点数。 | |
以给定的采样率随机选择文档。虽然每次运行所选文件的确切数量各不相同,但所选数量近似于以文件总数百分比表示的采样率。 |
对象表达式操作符
名称 | 说明 |
---|---|
将多个文档合并为一个文档。 版本 3.6 中的新增功能。 | |
将文档转换为表示键值对的文档数组。 版本 3.6 中的新增功能。 | |
添加、更新或删除文档中的指定字段。您可以使用 版本 5.0 中的新增功能。 |
集表达式操作符
集合表达式对数组执行集合操作,将数组视为集合。集合表达式会忽略每个输入数组中的重复条目和元素的顺序。
如果集操作返回一个集,则该操作会筛选掉结果中的重复项,以输出仅包含唯一条目的数组。输出数组中元素的顺序未指定。
如果集合包含嵌套数组元素,则集合表达式不会进入嵌套数组,而是在顶层计算数组。
名称 | 说明 |
---|---|
如果集合中没有元素计算结果为 false ,则返回 true ,否则返回 false 。接受单个参数表达式。 | |
如果集合中的任何元素的计算结果为 true ,则返回 true ;否则,返回 false 。接受单个参数表达式。 | |
如果输入集具有相同的不同元素,则返回 true 。接受两个或多个参数表达式。 | |
返回一个集,其中包含出现在所有输入集中的元素。接受任意数量的参数表达式。 | |
true 如果第一个集合的所有元素都出现在第二个集合中(包括第一个集合等于第二个集合的情况),则返回 ;即不是 严格子集 。只接受两个参数表达式。 | |
返回一个集,其中包含出现在任何输入集中的元素。 |
字符串表达式操作符
字符串表达式,除了 $concat
之外,字符串表达式只对 ASCII 字符串有明确定义的行为。
$concat
行为是明确定义的,无论使用什么字符。
名称 | 说明 |
---|---|
连接任意数量的字符串。 | |
将日期/时间字符串转换为日期对象。 | |
以格式化字符串的形式返回日期。 | |
搜索字符串中出现的子字符串,并返回首次出现的 UTF-8 字节索引。如果未找到该子字符串,则返回 -1 。 | |
在字符串中搜索子字符串的出现位置,并返回第一次出现时的 UTF-8 码位索引。如果未找到该子字符串,则返回 -1 | |
删除字符串开头和结尾的空白或指定字符。 | |
将正则表达式应用于字符串,并返回第一个匹配子字符串的信息。 | |
将正则表达式 (regex) 应用于字符串,并返回有关所有匹配子字符串的信息。 | |
将正则表达式 (regex) 应用于字符串并返回一个布尔值,它可表示是否已找到匹配项。 | |
替换给定输入中匹配字符串的第一个实例。 | |
替换给定输入中匹配字符串的所有实例。 | |
删除字符串结尾的空白或指定字符。 | |
根据分隔符将字符串拆分为子字符串。返回子字符串数组。如果在字符串中找不到分隔符,则返回包含原始字符串的数组。 | |
返回字符串中 UTF-8 编码的字节数。 | |
返回字符串中 UTF-8 代码点的数量。 | |
执行不区分大小写的字符串比较并返回:如果两个字符串相等,则返回 0 ;如果第一个字符串大于第二个字符串,则返回 1 ;如果第一个字符串小于第二个字符串,则返回 -1 。 | |
已弃用。使用 $substrBytes 或 $substrCP 。 | |
返回字符串的子串。从字符串中指定的 UTF-8 字节索引(从零开始)处的字符开始,持续指定的字节数。 | |
返回字符串的子串。从字符串中指定 UTF-8 代码点 (CP) 索引(从零开始)处的字符开始,持续指定的代码点数。 | |
将字符串转换为小写。接受单个参数表达式。 | |
将值转换为字符串。 | |
删除字符串开头和结尾的空白或指定字符。 | |
将字符串转换为大写。接受单个参数表达式。 |
文本表达式操作符
名称 | 说明 |
---|---|
访问与聚合操作相关的每个文档的可用元数据。 |
三角函数表达式操作符
三角表达式对数字执行三角运算。示角度的值始终以弧度为单位输入或输出。使用 $degreesToRadians
和 $radiansToDegrees
在度数和弧度测量值之间转换。
名称 | 说明 |
---|---|
返回以弧度为单位测量的某一值的正弦值。 | |
返回以弧度为单位测量的某一值的余弦。 | |
返回以弧度为单位来测量的某一值的正切值。 | |
以弧度为单位返回值的反正弦。 | |
以弧度为单位返回值的反余弦。 | |
以弧度为单位返回某一值的反切值(弧正切值)。 | |
以弧度为单位返回 y / x 的反正切,其中 y 和 x 分别为传递给该表达式的第一个值和第二个值。 | |
以弧度为单位返回数值的反双曲正弦(双曲弧正弦)值。 | |
以弧度为单位返回数值的反双曲余弦(双曲弧余弦)值。 | |
以弧度为单位返回数值的反双曲正切(双曲弧切)值。 | |
返回以弧度为单位来测量的某一值的双曲正弦值。 | |
返回以弧度为单位的值的双曲余弦值。 | |
以弧度为单位返回数值的双曲正切值。 | |
将值从度数转换为弧度。 | |
将值从弧度转换为度数。 |
类型表达式操作符
名称 | 说明 |
---|---|
将数值转换为指定类型。 | |
将值转换为布尔值。 | |
将数值转换为日期。 | |
将值转换为 Decimal128。 | |
将值转换为双精度值。 | |
将值转换为整数。 | |
将值转换为长整数。 | |
将值转换为 ObjectId。 | |
将值转换为字符串。 | |
返回字段的 BSON 数据类型。 |
累加器 ($group, $bucket, $bucketAuto, $setWindowFields
)
聚合累加器操作符:
在文件通过聚合管道时保持其状态。
返回总计值、最大值、最小值和其他值。
可在以下聚合管道阶段中使用:
$setWindowFields
,从 MongoDB 5.0 开始(除非使用$accumulator
或$mergeObjects
操作符,它们不能与$setWindowFields
一起使用)
5.0 版本中的更改。
名称 | 说明 |
---|---|
返回用户定义的累加器函数的结果。 | |
返回每个群组的唯一表达式值数组。未定义数组元素的排序。 5.0 版中的更改:可在 | |
返回数值的平均值。忽略非数字值。 5.0 版中的更改:可在 | |
返回组中第一个文档的表达式结果。 5.0 版中的更改:可在 | |
返回群组中最后一份文档的表达式结果。 5.0 版中的更改:可在 | |
返回每个群组的最大表达式值。 5.0 版中的更改:可在 | |
返回通过组合每个组的输入文档创建的文档。 | |
返回每个群组的最小表达式值。 5.0 版中的更改:可在 | |
返回每组中文档的大量表达式值。 5.0 版中的更改:可在 | |
返回输入值的总体标准偏差。 5.0 版中的更改:可在 | |
返回输入值的样本标准偏差。 5.0 版中的更改:可在 | |
返回数值的总和。忽略非数字值。 5.0 版中的更改:可在 |
累加器(其他阶段中)
一些可用作 $group
阶段累加器的操作符也可用于其他阶段,但不能作为累加器。用于其他阶段使用,这些操作符不维护其状态,并且可以将单个参数或多个参数作为输入。有关详细信息,请参阅特定操作符页面。
5.0 版本中的更改。
以下累加器操作符在 $project
、$addFields
、$set
、(从 MongoDB 5.0 开始)$setWindowFields
阶段中也可用。
变量表达式操作符
名称 | 说明 |
---|---|
定义要在子表达式范围内使用的变量,并返回这些子表达式的结果。接受已命名的参数。 接受任意数量的参数表达式。 |
窗口运算符
版本 5.0 中的新增功能。
窗口操作符从集合(称为窗口)中定义的文档范围返回值。窗口在 $setWindowFields
阶段定义,从 MongoDB 5.0 开始可用。
以下窗口操作符可在 $setWindowFields
阶段使用。
名称 | 说明 |
---|---|
返回对每份文档应用表达式所产生的所有唯一值的数组。 5.0 版中的更改:可在 | |
返回指定表达式的平均值。忽略非数字值。 5.0 版中的更改:可在 | |
返回两个数值表达式的总体协方差。 版本 5.0 中的新增功能。 | |
返回两个数值表达式的样本协方差。 版本 5.0 中的新增功能。 | |
返回某文档在 版本 5.0 中的新增功能。 | |
返回指定窗口内的平均变化率。 版本 5.0 中的新增功能。 | |
返回文档在 版本 5.0 中的新增功能。 | |
返回数值表达式的指数移动平均值。 版本 5.0 中的新增功能。 | |
5.0 版中的更改:可在 | |
返回曲线下面积的近似值。 版本 5.0 中的新增功能。 | |
5.0 版中的更改:可在 | |
返回对每份文档应用表达式所得的最大值。 5.0 版中的更改:可在 | |
返回对每份文档应用表达式所得的最小值。 5.0 版中的更改:可在 | |
返回对每个文档应用表达式后所得值的数组。 5.0 版中的更改:可在 | |
返回一个文档在 版本 5.0 中的新增功能。 | |
返回在 版本 5.0 中的新增功能。 | |
返回对每个文档应用数值表达式所得的总体标准差。 5.0 版中的更改:可在 | |
返回对每个文档应用数值表达式所得的样本标准差。 5.0 版中的更改:可在 | |
返回对每份文档应用数字表达式所得的总和。 5.0 版中的更改:可在 |