表达式

表达式是 MQL 组件，可解析为值，而不会修改其输入。您可以在以下上下文中使用它们：

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

在 MongoDB 查询语言中，您可以从以下组件构建表达式：

组件	例子
常量	`3`
操作符	`$add`
字段路径表达式	`"$<path.to.field>"`

示例，{ $add: [ 3, "$inventory.total" ] } 是由 $add操作符和两个操作数组成的表达式：

常量 3
字段路径表达式 "$inventory.total"

表达式返回将 3 添加到输入文档中路径 inventory.total 处的值的结果。

表达式操作符接收一个数组作为参数，并具有以下形式：

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

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

{ <operator>: <argument> }

算术操作符

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

名称	说明
`$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`	返回第一个值减去第二个值后的结果。如果这两个值均为日期，则返回以毫秒为单位的差值。如果这两个值一个为日期而另一个为数字（以毫秒为单位），则返回生成的日期。接受两个参数表达式。如果这两个值一个为日期而另一个为数字，请先指定日期参数，因为用数字减去日期没有意义。

与累加器相关的表达式

一些 $group 累加器也可用作表达式，可以计算输入参数或输入数组的值。

以下操作符是累加器，但它们也可用作接受值大量作为输入的表达式。

名称	说明
`$avg`	返回每个文档中指定表达式或表达式列表的平均值。忽略非数字值。
`$first`	返回组中第一个文档的表达式结果。
`$last`	返回群组中最后一份文档的表达式结果。
`$max`	返回每个文档的指定表达式或表达式列表的最大值。
`$median`	返回中位数（第 50 百分位数）的近似标量值。 7.0版本新增。：
`$min`	返回每个文档的指定表达式或表达式列表的最小值。
`$percentile`	返回与指定的各百分位数一一对应的标量值数组。 7.0版本新增。：
`$stdDevPop`	返回输入值的总体标准偏差。
`$stdDevSamp`	返回输入值的样本标准偏差。
`$sum`	返回数值的总和。忽略非数字值。

字面表达式操作符

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

其他操作符

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

对象操作符

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

设置操作符

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

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

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

名称	说明
`$allElementsTrue`	如果集合中没有元素计算结果为 `false` ，则返回 `true`，否则返回 `false`。接受单个参数表达式。
`$anyElementTrue`	如果集合中的任何元素的计算结果为 `true`，则返回 `true`；否则，返回 `false`。接受单个参数表达式。
`$setDifference`	返回集合，其中的元素出现在第一个集合中，但没有出现在第二个集合中；即执行第二个集合相对于第一个集合的相对补集。实际接受两个参数表达式。
`$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。

变量操作符

名称	说明
`$let`	定义要在子表达式范围内使用的变量，并返回这些子表达式的结果。接受已命名的参数。接受任意数量的参数表达式。

窗口运算符

窗口操作符从集合（称为窗口）中定义的文档范围返回值。窗口在 $setWindowFields 阶段定义，从 MongoDB 5.0 开始可用。

以下窗口操作符可在 $setWindowFields 阶段使用。

名称	说明
`$addToSet`	返回对每份文档应用表达式所产生的所有唯一值的数组。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$avg`	返回指定表达式的平均值。忽略非数字值。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$bottom`	根据指定的排序顺序返回组内的底部元素。 5.2版本新增。：可在 `$group` 和 `$setWindowFields` 阶段使用。
`$bottomN`	根据指定的排序顺序，返回群组内后 `n` 个字段的聚合。 5.2版本新增。：可在 `$group` 和 `$setWindowFields` 阶段使用。
`$count`	返回群组或窗口中的文档数。有别于 `$count` 管道阶段。 5.0版本新增。：
`$covariancePop`	返回两个数值表达式的总体协方差。 5.0版本新增。：
`$covarianceSamp`	返回两个数值表达式的样本协方差。 5.0版本新增。：
`$denseRank`	返回某文档在 `$setWindowFields` 阶段分区中相对于其他文档的位置（称为排名）。这些排名没有差异。并列可获得相同排名。 5.0版本新增。：
`$derivative`	返回指定窗口内的平均变化率。 5.0版本新增。：
`$documentNumber`	返回文档在 `$setWindowFields` 阶段分区中的位置（称为文档编号）并列会导致相邻文件编号不同。 5.0版本新增。：
`$expMovingAvg`	返回数值表达式的指数移动平均值。 5.0版本新增。：
`$first`	返回组或窗口中第一个文档的表达式的结果。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$integral`	返回曲线下面积的近似值。 5.0版本新增。：
`$last`	返回组或窗口中最后一份文档的表达式结果。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$linearFill`	使用基于周围字段值的线性插值 `null`来填充窗口中的和缺失字段。可在 `$setWindowFields` 阶段使用。 5.3版本新增。：
`$locf`	最后一次的观察结果被延续了下来。将窗口中 `null` 和缺失字段的值设置为该字段的最后一个非 null 值。可在 `$setWindowFields` 阶段使用。 5.2版本新增。：
`$max`	返回对每份文档应用表达式所得的最大值。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$min`	返回对每份文档应用表达式所得的最小值。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$minN`	返回组中 `n` 个最小值元素的聚合。与 `$minN` 数组操作符不同。 5.2版本新增。：在 `$group`、`$setWindowFields` 中可用，以及用作表达式
`$push`	返回对每个文档应用表达式后所得值的数组。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$rank`	返回一个文档在 `$setWindowFields` 阶段分区中相对于其他文档的位置（称为排名）。 5.0版本新增。：
`$shift`	返回在 `$setWindowFields` 阶段的分区中，应用于某一文档的表达式的值。该文档通过与当前文档的相对位置进行指定。 5.0版本新增。：
`$stdDevPop`	返回对每个文档应用数值表达式所得的总体标准差。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$stdDevSamp`	返回对每个文档应用数值表达式所得的样本标准差。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$sum`	返回对每份文档应用数字表达式所得的总和。在版本5.0中进行了更改。：可在 `$setWindowFields` 阶段使用。
`$top`	根据指定的排序顺序返回群组内第一个元素。 5.2版本新增。：可在 `$group` 和 `$setWindowFields` 阶段使用。
`$topN`	根据指定的排序顺序，返回群组内前 `n` 个字段的聚合。 5.2版本新增。：可在 `$group` 和 `$setWindowFields` 阶段使用。

后退

$where

来年

$abs