聚合操作符

聚合管道操作符与 MongoDB Atlas 和本地部署环境兼容。

注意

有关特定操作符（包括事务语法和示例）的详细信息，请单击该操作符的参考页面链接。

兼容性

您可以对在以下环境中托管的部署使用聚合管道操作符：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

表达式运算符

表达式操作符类似于接受参数的函数。通常，这些操作符采用参数数组，并具有以下形式：

{ <operator>: [ <argument1>, <argument2> ... ] }

如果操作符接受单个参数，则可以省略指定参数列表的外部数组：

{ <operator>: <argument> }

如果该参数是一个字面数组，为避免解析歧义，必须在 $literal 表达式中使用该字面数组，或者保留指定参数列表的外部数组。

本页列出了可用于构造表达式的可用操作符。表达式用于以下 MQL 上下文中：

某些聚合管道阶段，如 $project、$addFields 和 $group
使用 $expr 的查询谓词内部
查找查询投影

算术表达式操作符

算术表达式对数字执行数学运算。一些算术表达式也可以支持日期算术。

名称	说明
`$abs`	返回一个数字的绝对值。
`$add`	添加数字以返回总和，或添加数字和日期以返回新日期。如果添加数字和日期，则将数字视为毫秒。接受任意数量的参数表达式，但一个表达式最多只能解析为一个日期。
`$ceil`	返回大于或等于指定数字的最小整数。
`$divide`	返回第一个数字除以第二个数字的结果。接受两个参数表达式。
`$exp`	将 e 提升到指定的指数。
`$floor`	返回小于或等于指定数字最大整数。
`$ln`	计算数字的自然对数。
`$log`	以指定基数计算数字的对数。
`$log10`	计算一个数字以 10 为底的对数。
`$mod`	返回第一个数字除以第二个数字的余数。接受两个参数表达式。
`$multiply`	将数字相乘以返回乘积。接受任意数量的参数表达式。
`$pow`	将一个数字提升到指定的指数。
`$round`	将数字舍入到整数或指定的小数位。
`$sqrt`	计算平方根。
`$subtract`	返回第一个值减去第二个值后的结果。如果这两个值均为数字，则返回差值。如果这两个值均为日期，则返回以毫秒为单位的差值。如果这两个值一个为日期而另一个为数字（以毫秒为单位），则返回生成的日期。接受两个参数表达式。如果这两个值一个为日期而另一个为数字，请先指定日期参数，因为用数字减去日期没有意义。
`$trunc`	将数字截断为整数或指定的小数位。

数组表达式操作符

名称	说明
`$arrayElemAt`	返回位于指定数组索引处的元素。
`$arrayToObject`	将键值对数组转换为文档。
`$concatArrays`	连接数组以返回连接后的数组。
`$filter`	选择数组的子集，以返回仅包含与筛选条件匹配的元素的数组。
`$firstN`	从数组开头返回指定数量的元素。与 `$firstN` 累加器不同。
`$in`	返回一个布尔值，它可表示指定的值是否在数组中。
`$indexOfArray`	搜索数组中出现的指定值，并返回首次出现的数组索引。数组索引从零开始。
`$isArray`	确定操作数是否为数组。返回一个布尔值。
`$lastN`	从数组末尾返回指定数量的元素。与 `$lastN` 累加器不同。
`$map`	对数组的每个元素应用子表达式，并按顺序返回生成值的数组。接受已命名的参数。
`$maxN`	返回数组中 `n` 个最大值。与 `$maxN` 累加器不同。
`$minN`	返回数组中 `n` 个最小值。与 `$minN` 累加器不同。
`$objectToArray`	将文档转换为表示键值对的文档数组。
`$range`	根据用户定义的输入，输出一个包含整数序列的数组。
`$reduce`	将表达式应用于数组中的每个元素，并将它们组合成一个值。
`$reverseArray`	返回元素顺序相反的数组。
`$size`	返回数组中元素的个数。接受单个表达式作为参数。
`$slice`	返回数组的子集。
`$sortArray`	对数组的元素进行排序。
`$zip`	将两个数组进行合并。

按位操作符

名称	说明
`$bitAnd`	返回对 `int` 或`long` 值的数组执行按位 `and` 操作的结果。 6.3 版本中的新功能。
`$bitNot`	返回对单个参数或包含单个 `int` 或 `long` 值的数组执行按位 `not` 操作的结果。 6.3 版本中的新功能。
`$bitOr`	返回对 `int` 或`long` 值的数组执行按位 `or` 操作的结果。 6.3 版本中的新功能。
`$bitXor`	返回对 `int` 和 `long` 值的数组执行按位 `xor`（排他或）操作的结果。 6.3 版本中的新功能。

布尔表达式操作符

布尔表达式可将其参数表达式作为布尔值进行计算，并返回一个布尔值以作为结果。

除 false 布尔值之外，布尔表达式还将以下值计算为 false：null、0 和 undefined 值。布尔表达式将所有其他值计算为 true，包括非零数值和数组。

名称	说明
`$and`	仅当所有表达式的计算结果均为 `true` 时才返回 `true`。接受任意数量的参数表达式。
`$not`	返回与参数表达式相反的布尔值。接受单个参数表达式。
`$or`	当任何表达式的计算结果为 `true` 时，返回 `true`。接受任意数量的参数表达式。

比较表达式操作符

比较表达式返回一个布尔值，但 $cmp 除外，它返回一个数字。

比较表达式接受两个参数表达式，并使用不同类型的值的指定 BSON 比较顺序来比较值和类型。

名称	说明
`$cmp`	如果两个值相等，则返回 `0`；如果第一个值大于第二个值，则返回 `1`；如果第一个值小于第二个值，则返回 `-1`。
`$eq`	如果这些值相等，则返回 `true`。
`$gt`	如果第一个值大于第二个值，则返回 `true`。
`$gte`	如果第一个值大于等于第二个值，则返回 `true`。
`$lt`	如果第一个值小于第二个值，则返回 `true`。
`$lte`	如果第一个值小于等于第二个值，则返回 `true`。
`$ne`	如果值不相等，则返回 `true`。

条件表达式操作符

名称	说明
`$cond`	一种三元运算符，它可用于计算一个表达式，并根据结果返回另外两个表达式之一的值。接受有序列表中的三个表达式或三个已命名的参数。
`$ifNull`	返回第一个表达式的非空结果；或者，如果第一个表达式生成空结果，则返回第二个表达式的结果。Null 结果包含未定义值或缺失字段的情况。接受两个表达式以作为参数。第二个表达式的结果可能为 null。
`$switch`	对一系列 case 表达式求值。当它找到计算结果为 `true` 的表达式时，`$switch` 会执行指定表达式并脱离控制流。

自定义聚合表达式操作符

名称	说明
`$accumulator`	定义自定义累加器函数。
`$function`	定义自定义函数。

数据大小操作符

以下操作符返回数据元素的大小：

名称	说明
`$binarySize`	返回给定字符串或二进制数据值内容的大小（以字节为单位）。
`$bsonSize`	以字节为单位返回给定文档（即 bsontype `Object`) 的大小（当编码为 BSON 时）。

日期表达式操作符

以下操作符返回日期对象或日期对象的组件：

名称	说明
`$dateAdd`	向日期对象添加多个时间单位。
`$dateDiff`	返回两个日期之间的差值。
`$dateFromParts`	根据日期的组成部分构造一个 BSON 日期对象。
`$dateFromString`	将日期/时间字符串转换为日期对象。
`$dateSubtract`	从日期对象中减去多个时间单位。
`$dateToParts`	返回包含日期组成部分的文档。
`$dateToString`	以格式化字符串的形式返回日期。
`$dateTrunc`	截断日期。
`$dayOfMonth`	以介于 1 和 31 之间的数字返回某一日期的“月中的某一天”。
`$dayOfWeek`	以 1（星期日）和 7（星期六）之间的数字形式返回以星期表示的日期。
`$dayOfYear`	以 1 到 366（闰年）之间的数字形式返回返回日期的年月日。
`$hour`	以数字形式返回日期中的小时部分（0 到 23）。
`$isoDayOfWeek`	以 ISO 8601 格式返回工作日数字，范围为 `1`（星期一）到 `7`（星期日）。
`$isoWeek`	以 ISO 8601 格式返回周数，范围从 `1` 到 `53`。周数从 `1` 开始，即包含一年中第一个星期四的那个星期（星期一到星期日）。
`$isoWeekYear`	以 ISO 8601 格式返回年份号。一年从第一周的星期一 (ISO 8601) 开始，到最后一周的星期日 (ISO 8601) 结束。
`$millisecond`	以 0 到 999 之间的数字形式返回日期的毫秒数。
`$minute`	返回日期的分钟数（0 到 59）。
`$month`	以 1（一月）到 12（十二月）之间的数字形式返回日期的月份。
`$second`	以 0 到 60 之间的数字返回日期的秒数（跳秒）。
`$toDate`	将数值转换为日期。
`$week`	以 0（一年中第一个星期日之前的部分周）和 53（闰年）之间的数字形式返回日期的周数。
`$year`	以数字形式返回日期的年份（例如 2014）。

以下算术操作符可以使用日期操作数：

名称	说明
`$add`	添加数字和日期以返回新日期。如果添加数字和日期，则将数字视为毫秒。接受任意数量的参数表达式，但一个表达式最多只能解析为一个日期。
`$subtract`	返回第一个值减去第二个值后的结果。如果这两个值均为日期，则返回以毫秒为单位的差值。如果这两个值一个为日期而另一个为数字（以毫秒为单位），则返回生成的日期。接受两个参数表达式。如果这两个值一个为日期而另一个为数字，请先指定日期参数，因为用数字减去日期没有意义。

字面值表达式操作符

名称	说明
`$literal`	返回一个值而不进行解析。用于聚合管道可解释为表达式的值。例如，对以美元符号 (`$`) 开头的字符串使用 `$literal` 表达式，以避免解析为字段路径。

其他操作符

名称	说明
`$getField`	从文档中返回指定字段的值。您可以使用 `$getField` 检索名称中包含句点 (`.`) 或以美元符号 (`$`) 开头的字段的值。版本 5.0 中的新增功能。
`$rand`	返回介于 0 和 1 之间的随机浮点数。
`$sampleRate`	以给定的采样率随机选择文档。虽然每次运行所选文件的确切数量各不相同，但所选数量近似于以文件总数百分比表示的采样率。
`$toHashedIndexKey`	使用 MongoDB 用于创建哈希索引的相同哈希函数计算并返回输入表达式的哈希值。

对象表达式操作符

名称	说明
`$mergeObjects`	将多个文档合并为一个文档。
`$objectToArray`	将文档转换为表示键值对的文档数组。
`$setField`	添加、更新或删除文档中的指定字段。您可以使用 `$setField` 添加、更新或删除名称包含句点 (`.`) 或以美元符号 (`$`) 开头的字段。版本 5.0 中的新增功能。

集表达式操作符

集合表达式对数组执行集合操作，将数组视为集合。集合表达式会忽略每个输入数组中的重复条目和元素的顺序。

如果集操作返回一个集，则该操作会筛选掉结果中的重复项，以输出仅包含唯一条目的数组。输出数组中元素的顺序未指定。

如果集合包含嵌套数组元素，则集合表达式不会进入嵌套数组，而是在顶层计算数组。

名称	说明
`$allElementsTrue`	如果集合中没有元素计算结果为 `false` ，则返回 `true`，否则返回 `false`。接受单个参数表达式。
`$anyElementTrue`	如果集合中的任何元素的计算结果为 `true`，则返回 `true`；否则，返回 `false`。接受单个参数表达式。
`$setDifference`	返回一个集，其中包含出现在第一个集中但未出现在第二个集中的元素； ie 执行相对补第二组相对于第一组的大小。只接受两个参数表达式。
`$setEquals`	如果输入集具有相同的不同元素，则返回 `true`。接受两个或多个参数表达式。
`$setIntersection`	返回一个集，其中包含出现在所有输入集中的元素。接受任意数量的参数表达式。
`$setIsSubset`	如果第一个集的所有元素都出现在第二个集中，包括当第一个集等于第二个集时，即不是严格子集，则返回 `true`。实际接受两个参数表达式。
`$setUnion`	返回一个集，其中包含出现在任何输入集中的元素。

字符串表达式操作符

字符串表达式，除了 $concat 之外，字符串表达式只对 ASCII 字符串有明确定义的行为。

$concat 行为是明确定义的，无论使用什么字符。

名称	说明
`$concat`	连接任意数量的字符串。
`$dateFromString`	将日期/时间字符串转换为日期对象。
`$dateToString`	以格式化字符串的形式返回日期。
`$indexOfBytes`	搜索字符串中出现的子字符串，并返回首次出现的 UTF-8 字节索引。如果未找到该子字符串，则返回 `-1`。
`$indexOfCP`	在字符串中搜索子字符串的出现位置，并返回第一次出现时的 UTF-8 码位索引。如果未找到该子字符串，则返回 `-1`
`$ltrim`	删除字符串开头和结尾的空白或指定字符。
`$regexFind`	将正则表达式应用于字符串，并返回第一个匹配子字符串的信息。
`$regexFindAll`	将正则表达式 (regex) 应用于字符串，并返回有关所有匹配子字符串的信息。
`$regexMatch`	将正则表达式 (regex) 应用于字符串并返回一个布尔值，它可表示是否已找到匹配项。
`$replaceOne`	替换给定输入中匹配字符串的第一个实例。
`$replaceAll`	替换给定输入中匹配字符串的所有实例。
`$rtrim`	删除字符串结尾的空白或指定字符。
`$split`	根据分隔符将字符串拆分为子字符串。返回子字符串数组。如果在字符串中找不到分隔符，则返回包含原始字符串的数组。
`$strLenBytes`	返回字符串中 UTF-8 编码的字节数。
`$strLenCP`	返回字符串中 UTF-8 代码点的数量。
`$strcasecmp`	执行不区分大小写的字符串比较并返回：如果两个字符串相等，则返回 `0`；如果第一个字符串大于第二个字符串，则返回 `1`；如果第一个字符串小于第二个字符串，则返回 `-1`。
`$substr`	已弃用。使用`$substrBytes` 或 `$substrCP`。
`$substrBytes`	返回字符串的子串。从字符串中指定的 UTF-8 字节索引（从零开始）处的字符开始，持续指定的字节数。
`$substrCP`	返回字符串的子串。从字符串中指定 UTF-8 代码点 (CP) 索引（从零开始）处的字符开始，持续指定的代码点数。
`$toLower`	将字符串转换为小写。接受单个参数表达式。
`$toString`	将值转换为字符串。
`$trim`	删除字符串开头和结尾的空白或指定字符。
`$toUpper`	将字符串转换为大写。接受单个参数表达式。

文本表达式操作符

名称	说明
`$meta`	访问与聚合操作相关的每个文档的可用元数据。

时间戳表达式操作符

时间戳表达式操作符从时间戳返回值。

名称	说明
`$tsIncrement`	以 `long` 形式返回时间戳中的递增序数。 5.1 版本中的新功能。
`$tsSecond`	以 `long` 形式返回时间戳中的秒数。 5.1 版本中的新功能。

三角函数表达式操作符

三角表达式对数字执行三角运算。示角度的值始终以弧度为单位输入或输出。使用 $degreesToRadians 和 $radiansToDegrees 在度数和弧度测量值之间转换。

名称	说明
`$sin`	返回以弧度为单位测量的某一值的正弦值。
`$cos`	返回以弧度为单位测量的某一值的余弦。
`$tan`	返回以弧度为单位来测量的某一值的正切值。
`$asin`	以弧度为单位返回值的反正弦。
`$acos`	以弧度为单位返回值的反余弦。
`$atan`	以弧度为单位返回某一值的反切值（弧正切值）。
`$atan2`	以弧度为单位返回 `y / x` 的反正切，其中 `y` 和 `x` 分别为传递给该表达式的第一个值和第二个值。
`$asinh`	以弧度为单位返回数值的反双曲正弦（双曲弧正弦）值。
`$acosh`	以弧度为单位返回数值的反双曲余弦（双曲弧余弦）值。
`$atanh`	以弧度为单位返回数值的反双曲正切（双曲弧切）值。
`$sinh`	返回以弧度为单位来测量的某一值的双曲正弦值。
`$cosh`	返回以弧度为单位的值的双曲余弦值。
`$tanh`	以弧度为单位返回数值的双曲正切值。
`$degreesToRadians`	将值从度数转换为弧度。
`$radiansToDegrees`	将值从弧度转换为度数。

类型表达式操作符

名称	说明
`$convert`	将数值转换为指定类型。
`$isNumber`	如果指定表达式解析为 `integer`、`decimal`、`double` 或 `long`，则返回布尔值 `true`。如果表达式解析为任何其他 BSON 类型、`null` 或缺失字段，返回布尔值 `false`。
`$toBool`	将值转换为布尔值。
`$toDate`	将数值转换为日期。
`$toDecimal`	将值转换为 Decimal128。
`$toDouble`	将值转换为 double。
`$toInt`	将值转换为整数。
`$toLong`	将值转换为长整数。
`$toObjectId`	将值转换为 ObjectId。
`$toString`	将值转换为字符串。
`$type`	返回字段的 BSON 数据类型。
`$toUUID`	将字符串转换为 UUID。

累加器 (`$group, $bucket, $bucketAuto, $setWindowFields` )

聚合累加器操作符：

在文件通过聚合管道时保持其状态。
返回总计值、最大值、最小值和其他值。
可在以下聚合管道阶段中使用：
- $bucket
- $bucketAuto
- $group
- $setWindowFields，从 MongoDB 5.0 开始（除非使用 $accumulator 或 $mergeObjects 操作符，它们不能与 $setWindowFields 一起使用）

5.0 版本中的更改。

名称	说明
`$accumulator`	返回用户定义的累加器函数的结果。
`$addToSet`	返回每个群组的唯一表达式值数组。未定义数组元素的排序。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$avg`	返回数值的平均值。忽略非数字值。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$bottom`	根据指定的排序顺序返回组内的底部元素。 5.2 版本中的新增功能。可在 `$group` 和 `$setWindowFields` 阶段使用。
`$bottomN`	根据指定的排序顺序，返回群组内后 `n` 个字段的聚合。 5.2 版本中的新增功能。可在 `$group` 和 `$setWindowFields` 阶段使用。
`$count`	返回群组中的文档数。有别于 `$count` 管道阶段。 5.0 版新增功能：可在 `$group` 和 `$setWindowFields` 阶段使用。
`$first`	返回组中第一个文档的表达式结果。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$firstN`	返回群组内前 `n` 个元素的聚合。仅当文档按定义的顺序排列时才有意义。与 `$firstN` 数组操作符不同。 5.2 版新增功能：可在 `$group`、表达式和 `$setWindowFields` 阶段使用。
`$last`	返回群组中最后一份文档的表达式结果。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$lastN`	返回群组内后 `n` 个元素的聚合。仅当文档按定义的顺序排列时才有意义。与 `$lastN` 数组操作符不同。 5.2 版新增功能：可在 `$group`、表达式和 `$setWindowFields` 阶段使用。
`$max`	返回每个群组的最大表达式值。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$maxN`	返回群组中 `n` 个最大值元素的聚合。与 `$maxN` 数组操作符不同。 5.2 版本中的新增功能。在 `$group`、`$setWindowFields` 中可用，以及用作表达式
`$median`	返回中位数（第 50 百分位数）的近似标量值。 7.0 版本中的新增功能。此操作符可在以下阶段用作累加器： `$group` `$setWindowFields` 它也可用作聚合表达式。
`$mergeObjects`	返回通过组合每个组的输入文档创建的文档。
`$min`	返回每个群组的最小表达式值。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$minN`	返回组中 `n` 个最小值元素的聚合。与 `$minN` 数组操作符不同。 5.2 版本中的新增功能。在 `$group`、`$setWindowFields` 中可用，以及用作表达式
`$percentile`	返回与指定的各百分位数一一对应的标量值数组。 7.0 版本中的新增功能。此操作符可在以下阶段用作累加器： `$group` `$setWindowFields` 它也可用作聚合表达式。
`$push`	返回每组中文档的大量表达式值。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$stdDevPop`	返回输入值的总体标准偏差。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$stdDevSamp`	返回输入值的样本标准偏差。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$sum`	返回数值的总和。忽略非数字值。 5.0 版中的更改：可在 `$setWindowFields` 阶段使用。
`$top`	根据指定的排序顺序返回群组内第一个元素。 5.2 版本中的新增功能。可在 `$group` 和 `$setWindowFields` 阶段使用。
`$topN`	根据指定的排序顺序，返回群组内前 `n` 个字段的聚合。 5.2 版本中的新增功能。可在 `$group` 和 `$setWindowFields` 阶段使用。

累加器（其他阶段中）

一些可用作 $group 阶段累加器的操作符也可用于其他阶段，但不能作为累加器。用于其他阶段使用，这些操作符不维护其状态，并且可以将单个参数或多个参数作为输入。有关详细信息，请参阅特定操作符页面。