聚合管道的快速参考

进入MongoDB中文手册（4.2版本）目录

注意
有关运算符的特定的详细信息，包括语法和示例，请单击运算符并跳转转到其参考页。

1 阶段

1.1 阶段(db.collection.aggregate)

在db.collection.aggregate方法中，聚合管道出现在一个数组中。文件依次经过各个阶段。$out，$merge和$geoNear以外的所有阶段可以在管道中出现多次。

db.collection.aggregate( [ { <stage> }, ... ] )

阶段	描述
$addFields	将新字段添加到文档。与$project，$addFields重塑流中的每个文档相似 ；具体而言，通过向输出文档添加新字段，该文档既包含输入文档中的现有字段，又包含新添加的字段。 $set是$addFields的别名。
$bucket	根据指定的表达式和存储区(bucket)边界将传入文档分类为多个组，称为存储桶(buckets)。
$bucketAuto	根据指定的表达式将传入文档分类为特定数量的组，称为存储桶(buckets)。尝试将文档平均分配到指定数量的存储区中的时候自动确定存储区边界。
$collStats	返回有关集合或视图的统计信息。
$count	返回聚合管道的阶段的文档数。
$facet	在同一阶段的同一组输入文档上处理多个聚合管道。支持在一个阶段中创建能够表征多维或多面数据的多面聚合( multi-faceted aggregations)。
$geoNear	根据与地理空间点的接近程度返回有序的文档流。包含用于地理空间数据的功能$match，$sort和$limit。输出文档包括附加距离字段，并且可以包括位置标识符字段。
$graphLookup	对集合执行递归搜索。向每个输出文档添加一个新的数组字段，其中包含对该文档的递归搜索的遍历结果。
$group	按指定的标识符表达式对输入文档进行分组，并将累加器表达式（如果指定）应用于每个组。消耗所有输入文档，并在每个不同的组中输出一个文档。输出文档仅包含标识符字段，如果指定，还包含累积字段。
$indexStats	返回有关集合每个索引使用情况的统计信息。
$limit	将未修改的前n个文档传递到管道，其中n是指定的限制。对于每个输入文档，输出一个文档（对于前n个文档）或零文档（在前n个文档之后）。
$listSessions	列出所有传播到system.sessions集合且已经活动足够长时间的会话。
$lookup	对同一数据库中的另一个集合执行左外部连接(left outer join)，来过滤“连接”集合中的文档并加以处理。
$match	筛选文档流，仅允许匹配的文档未经修改地传递到下一个管道阶段。 $match使用标准的MongoDB查询。对于每个输入文档，输出一个文档（匹配）或零文档（不匹配）。
$merge	将聚合管道的结果文档写入集合。该阶段可以将结果合并（插入新文档，合并文档，替换文档，保留现有文档，使操作失败，使用自定义更新管道处理文档）到输出集合中。$merge阶段必须用于管道中的最后一个阶段。 4.2版中的新功能。
$out	将聚合管道的结果文档写入集合。$out阶段必须用于管道中的最后一个阶段。
$planCacheStats	返回集合的计划缓存信息。
$project	重塑流中的每个文档，例如通过添加新字段或删除现有字段。对于每个输入文档，输出一个文档。 另请参阅用于删除现有字段的$unset。
$redact	通过基于文档本身存储的信息，通过限制每个文档的内容的方式来重塑流中的每个文档。包含$project和的功能$match。可用于实施字段级修订。对于每个输入文档，输出一个或零个文档。
$replaceRoot	用指定的嵌入式文档替换一个文档。该操作将替换输入文档中的所有现有字段，包括_id字段。指定在输入文档中嵌入的文档，将嵌入的文档提升到顶层。 $replaceWith是$replaceRoot阶段的别名 。
$replaceWith	用指定的嵌入式文档替换文档。该操作将替换输入文档中的所有现有字段，包括该_id字段。指定在输入文档中嵌入的文档，将嵌入的文档提升到顶层。 $replaceWith是$replaceRoot阶段的别名 。
$sample	从其输入中随机选择指定数量的文档。
$set	将新字段添加到文档。与 $project，$set重塑流中的每个文档相似；具体而言，通过向输出文档添加新字段，该文档既包含输入文档中的现有字段，又包含新添加的字段。 $set是$addFields阶段的别名。
$skip	跳过前n个文档，其中n是指定的跳过数量，并将其余未修改的文档传递到管道。对于每个输入文档，输出零个文档（对于前n个文档）或一个文档（如果在前n个文档之后）。
$sort	通过指定的排序键对文档流重新排序。只有顺序改变；这些文档保持不变。对于每个输入文档，输出一个文档。
$sortByCount	根据指定表达式的值对传入文档进行分组，然后计算每个不同组中的文档数。
$unset	从文档中删除/排除字段。 $unset是$project删除字段的阶段的别名。
$unwind	从输入文档中解构一个数组字段，以输出每个元素的文档。每个输出文档用元素值替换数组。对于每个输入文档，输出n个文档，其中n是数组元素的数量，对于空数组可以为零。

1.2 阶段(db.aggregate)

从3.6版开始，MongoDB还提供以下 db.aggregate方法：

db.aggregate( [ { <stage> }, ... ] )

以下阶段使用db.aggregate()方法而不是db.collection.aggregate()方法。

阶段	描述
$currentOp	返回有关MongoDB部署的活动和(或)休眠操作的信息。
$listLocalSessions	列出在当前连接mongos或mongod实例上使用的所有当前的活动会话。这些会话可能尚未传播到system.sessions集合。

1.3 用于刷新的阶段

从MongoDB 4.2开始，您可以使用使用聚合管道通过以下方法进行更新：

命令	mongo Shell方法
findAndModify	db.collection.findOneAndUpdate() db.collection.findAndModify()
update	db.collection.updateOne() db.collection.updateMany() db.collection.update() Bulk.find.update() Bulk.find.updateOne() Bulk.find.upsert()

对于更新，管道可以包括以下阶段：

• $addFields 及其别名$set,
• $project 及其别名$unset,
• $replaceRoot及其别名$replaceWith。

也可以看看:聚合管道更新

2 表达式

表达式可以包括字段路径， 字面量，系统变量，表达式对象和表达式运算符。表达式可以嵌套。

2.1 字段路径

聚合表达式使用字段路径访问输入文档中的字段。要指定字段路径，请在字段名或带点号的字段名（如果该字段在嵌入式文档中）之前加一个美元符号$。例如， "$user"指定字段的字段路径user或 “$user.name"指定字段的字段路径"user.name”。
“$<field>“等效于”$$CURRENT.<field>”，其中 CURRENT是默认为当前对象根目录的系统变量，除非在特定阶段另有说明。

2.2 聚合变量

MongoDB提供了各种用于表达式的聚合系统变量。要访问变量，请在变量名称前添加$$。例如：

变量	通过$$访问	简要描述
NOW	$$NOW	返回当前日期时间值，该值在部署的所有成员之间相同，并且在整个聚合管道中保持不变。（在4.2+版本中可用）
CLUSTER_TIME	$$CLUSTER_TIME	返回当前时间戳值，该值在部署的所有成员之间相同，并且在整个聚合管道中保持不变。仅适用于副本集和分片群集。（在4.2+版本中可用）
ROOT	$$ROOT	引用根文档，即顶级文档。
CURRENT	$$CURRENT	引用字段路径的开始，默认情况下为， ROOT但可以更改。
REMOVE	$$REMOVE	允许有条件地排除字段。（在3.6+版本中可用）
DESCEND	$$DESCEND	$redact表达式的允许结果之一。
PRUNE	$$PRUNE	$redact表达式的允许结果之一。
KEEP	$$KEEP	$redact表达式的允许结果之一。

有关这些变量的更详细说明，请参见系统变量。

2.3 字面量

字面量可以是任何类型。但是，MongoDB将以美元符号$开头的字符串字面量解析为字段的路径，将表达式对象中的数字/布尔字面量解析为投影标志。为避免解析字面量，请使用$literal表达式。

2.4 表达式对象

表达式对象具有以下形式：

{ <field1>: <expression1>, ... }

如果表达式是数字或布尔字面量，则MongoDB会将字面量视为投影标记（例如包含字段1或true），仅在$project阶段中有效。为了避免将数字或布尔字面量视为投影标记，请使用$literal表达式来包装数字或布尔字面量。

3 运算符表达式

运算符表达式类似于带有参数的函数。通常，这些表达式采用参数数组并具有以下形式：

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

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

{ <operator>: <argument> }

为了避免在参数是字面量数组的情况下解析歧义，必须将字面量数组包装在$literal表达式中，或者保留指定参数列表的外部数组。

3.1 算术表达式运算符

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

名称	描述
$abs	返回数字的绝对值。
$add	添加数字并返回总和，或者添加数字和日期并返回新日期。如果添加数字和日期，则将数字视为毫秒。接受任意数量的参数表达式，但最多只能一个表达式解析为日期。
$ceil	返回大于或等于指定数字的最小整数。
$divide	返回第一个数字除以第二个数字的结果。接受两个参数表达式。
$exp	将e提高到指定的指数。
$floor	返回小于或等于指定数字的最大整数。
$ln	计算数字的自然对数。
$log	以指定的底数计算数字的对数。
$log10	计算数字的以10为底的对数。
$mod	返回第一个数字的余数除以第二个数字。接受两个参数表达式。
$multiply	乘以数字可返回乘积。接受任意数量的参数表达式。
$pow	将数字提高到指定的指数。
$round	将数字四舍五入为整数或指定的小数位。
$sqrt	计算平方根。
$subtract	返回从第一个值减去第二个值的结果。如果两个值是数字，则返回差值。如果两个值是日期，则返回以毫秒为单位的差。如果两个值是日期和毫秒数，则返回结果日期。接受两个参数表达式。如果两个值是日期和数字，请首先指定date参数，因为从数字中减去日期没有意义。
$trunc	将数字截断为整数或指定的小数位。

3.2 数组表达式运算符

名称	描述
$arrayElemAt	返回指定数组索引处的元素。
$arrayToObject	将键值对数组转换为文档。
$concatArrays	连接数组以返回连接的数组。
$filter	选择数组的子集以返回仅包含与过滤条件匹配的元素的数组。
$in	返回一个布尔值，指示指定的值是否在数组中。
$indexOfArray	在数组中搜索指定值的出现，并返回第一次出现的数组索引。如果未找到子字符串，则返回-1。
$isArray	确定操作数是否为数组。返回一个布尔值。
$map	对数组的每个元素应用子表达式，并按顺序返回结果值的数组。接受命名参数。
$objectToArray	将文档转换为代表键值对的文档数组。
$range	根据用户定义的输入输出包含整数序列的数组。
$reduce	将表达式应用于数组中的每个元素，并将它们组合为单个值。
$reverseArray	返回具有相反顺序元素的数组。
$size	返回数组中元素的数量。接受单个表达式作为参数。
$slice	返回数组的子集。
$zip	将两个数组合并在一起。

3.3 布尔表达式运算符

布尔表达式将其参数表达式评估为布尔值，并返回布尔值作为结果。
除了false布尔值，布尔表达式将如下内容计算为false：null，0，和undefined 的值。布尔表达式将所有其他值评估为true，包括非零数字值和数组。

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

3.4 比较表达式运算符

比较表达式返回一个布尔值，但$cmp 返回一个数字。
比较表达式采用两个参数表达式，并且对不同类型的值使用指定的BSON比较顺序来比较值和类型。

名称	描述
$cmp	如果这两个值是相等返回0，如果第一个值大于所述第二值返回1，如果所述第一值小于第二返回-1。
$eq	如果值相等则返回true。
$gt	如果第一个值大于第二个值，则返回true。
$gte	如果第一个值大于或等于第二个值，则返回true。
$lt	如果第一个值小于第二个值，则返回true。
$lte	如果第一个值小于或等于第二个值返回true。
$ne	如果值不相等，则返回true。

3.5 条件表达式运算符

名称	描述
$cond	一个三元运算符，它对一个表达式求值，并根据结果返回其他两个表达式之一的值。接受有序列表中的三个表达式或三个命名参数。
$ifNull	如果第一个表达式的结果为空，则返回第一个表达式的非空结果或第二个表达式的结果。空结果包含未定义值或缺少字段的实例。接受两个表达式作为参数。第二个表达式的结果可以为空。
$switch	计算一系列用例表达式。当它找到一个计算结果为true的表达式时，$switch执行一个指定的表达式并退出控制流程。

3.6 日期表达式运算符

以下运算符返回日期对象或日期对象的组成部分：

名称	描述
$dateFromParts	给定日期的组成部分，构造一个BSON Date对象。
$dateFromString	将日期/时间字符串转换为日期对象。
$dateToParts	返回包含日期组成部分的文档。
$dateToString	以格式字符串返回日期。
$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格式返回年份。年份从第1周的星期一（ISO 8601）开始，到最后一周的星期日（ISO 8601）结束。
$millisecond	以0到999之间的数字返回日期的毫秒数。
$minute	以0到59之间的数字返回日期的分钟。
$month	以1（一月）至12（十二月）之间的数字返回日期的月份。
$second	以0到60之间的数字返回日期的秒数（（秒）。
$toDate	将值转换为日期。 版本4.0中的新功能。
$week	返回日期的星期数，其范围是0（该年的第一个星期日之前的局部星期）和53（闰年）之间的数字。
$year	以数字形式返回日期的年份（例如2014）。

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

名称	描述
$add	添加数字和日期并返回新日期。如果添加数字和日期，则将数字视为毫秒。接受任意数量的参数表达式，但最多只能一个表达式解析为日期。
$subtract	返回从第一个值减去第二个值的结果。如果两个值是日期，则返回以毫秒为单位的差。如果两个值是日期和毫秒数，则返回结果日期。接受两个参数表达式。如果两个值是日期和数字，请首先指定date参数，因为从数字中减去日期没有意义。

3.7 字面量表达式运算符

名称	描述
$literal	返回一个没有解析的值。用于聚合管道可以解释为表达式的值。例如，$literal对以$开头的字符串使用表达式，以避免将其解析为字段路径。

3.8 对象表达式运算符

名称	描述
$mergeObjects	将多个文档合并为一个文档。 3.6版的新功能。
$objectToArray	将文档转换为代表键值对的文档数组。 3.6版的新功能。

3.9 集(Set)表达式运算符

集表达式对数组执行集运算，将数组视为集。集表达式将忽略每个输入数组中的重复条目以及元素的顺序。
如果set操作返回一个set，则该操作会滤除结果中的重复项，并输出仅包含唯一条目的数组。输出数组中元素的顺序未指定。
如果一组包含嵌套数组元素，该组表达并不会下降到嵌套数组计算，而是计算顶层数组。

名称	描述
$allElementsTrue	如果没有一个集(set)的元素计算为false则返回true，否则，返回false。接受单个参数表达式。
$anyElementTrue	如果集(set)中的任何元素都为true，则返回true；否则，返回false。接受单个参数表达式。
$setDifference	返回具有出现在第一个集(set)中但不出现在第二个集中(set)的元素的集(set)；即执行第二个集相对于第一个集的相对补(relative complement)。正好接受两个参数表达式。
$setEquals	如果输入集在过滤掉重复的元素后(distinct)具有相同的元素返回true。接受两个或多个参数表达式。
$setIntersection	返回具有出现在所有输入集中的元素的集合。接受任意数量的参数表达式。
$setIsSubset	第一个集合的所有元素是否出现在第二个集合中，包括第一个集合等于第二个集合时返回true；即不是严格的子集。正好接受两个参数表达式。
$setUnion	返回带有出现在任何输入集中的元素的集合。

3.10 字符串表达式运算符

字符串表达式（ $concat除外），仅对ASCII字符的字符串具有明确定义的行为。
$concat 行为是明确定义的，与所使用的字符无关。

名称	描述
$concat	连接任意数量的字符串。
$dateFromString	将日期/时间字符串转换为日期对象。
$dateToString	以格式字符串返回日期。
$indexOfBytes	在字符串中搜索子字符串的出现，并返回第一次出现的UTF-8字节索引( byte index)。如果未找到子字符串，则返回-1。
$indexOfCP	在字符串中搜索子字符串的出现，并返回第一次出现的UTF-8编码点索引(code point index)。如果未找到子字符串，则返回-1
$ltrim	从字符串开头删除空格或指定的字符。 版本4.0中的新功能。
$regexFind	将正则表达式（regex）应用于字符串，并返回第一个匹配的子字符串的信息。 4.2版中的新功能。
$regexFindAll	将正则表达式（regex）应用于字符串，并返回所有匹配的子字符串的信息。 4.2版中的新功能。
$regexMatch	将正则表达式（regex）应用于字符串，并返回一个布尔值，该布尔值指示是否找到匹配项。 4.2版中的新功能。
$rtrim	从字符串末尾删除空格或指定的字符。 版本4.0中的新功能。
$split	根据分隔符将字符串拆分为子字符串。返回子字符串数组。如果在字符串中未找到分隔符，则返回包含原始字符串的数组。
$strLenBytes	返回字符串中UTF-8编码的字节数。
$strLenCP	返回字符串中UTF-8 代编码点(code point)的数量。
$strcasecmp	执行不区分大小写的字符串比较并返回： 0如果两个字符串相等，1则第一个字符串大于第二个-1字符串，并且第一个字符串小于第二个字符串。
$substr	不推荐使用。使用$substrBytes或 $substrCP。
$substrBytes	返回字符串的子字符串。从字符串中指定的UTF-8字节索引（从零开始）处的字符开始，并继续指定的字节数。
$substrCP	返回字符串的子字符串。从字符串中指定的UTF-8 代码点（CP/code point）索引（从零开始）处的字符开始，并继续指定的代码点数。
$toLower	将字符串转换为小写。接受单个参数表达式。
$toString	将值转换为字符串。 版本4.0中的新功能。
$trim	从字符串的开头和结尾删除空格或指定的字符。 版本4.0中的新功能。
$toUpper	将字符串转换为大写。接受单个参数表达式。

3.11 文本表达式运算符

名称	描述
$meta	使用全文检索元数据。

3.12 三角表达式运算符

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

名称	描述
$sin	返回以弧度为单位的值的正弦值。
$cos	返回以弧度为单位的值的余弦值。
$tan	返回以弧度为单位的值的切线。
$asin	返回弧度值的反正弦（弧正弦）。
$acos	返回以弧度为单位的值的反余弦（弧余弦）。
$atan	返回弧度值的反正切（弧切线）。
$atan2	返回弧度的反正切（弧切线），其中和是分别传递给表达式的第一个和第二个值。y / xyx
$asinh	返回弧度值的反双曲正弦（双曲反正弦）。
$acosh	返回弧度值的反双曲余弦（双曲反余弦）。
$atanh	返回弧度值的反双曲正切（双曲反正切）。
$degreesToRadians	将值从度转换为弧度。
$radiansToDegrees	将值从弧度转换为度。

3.13 类型表达式运算符

名称	描述
$convert	将值转换为指定的类型。 版本4.0中的新功能。
$toBool	将值转换为布尔值。 版本4.0中的新功能。
$toDate	将值转换为日期。 版本4.0中的新功能。
$toDecimal	将值转换为Decimal128。 版本4.0中的新功能。
$toDouble	将值转换为双精度。 版本4.0中的新功能。
\toInt	将值转换为整数。 版本4.0中的新功能。
\toLong	将值转换为long。 版本4.0中的新功能。
$toObjectId	将值转换为ObjectId。 版本4.0中的新功能。
$toString	将值转换为字符串。 版本4.0中的新功能。
$type	返回该字段的BSON数据类型。

3.14 累加器（$group）

累加器是可以在$group阶段中使用的运算符，它们在文档通过管道处理时保持其状态（例如，总计，最大值，最小值和相关数据）。
当在$group阶段中用作累加器时，这些运算符将单个表达式作为输入，对每个输入文档计算一次该表达式，并为共享相同组键的文档组维护其阶段。

名称	描述
$addToSet	返回每个组的唯一表达式值的数组。数组元素的顺序未定义。
$avg	返回数值的平均值。忽略非数字值。
$first	从每个组的第一个文档返回一个值。仅当文档按定义的顺序定义顺序时。
$last	从每个组的最后一个文档返回一个值。仅当文档按定义的顺序定义顺序时。
$max	返回每个组的最高表达式值。
$mergeObjects	返回通过组合每个组的输入文档而创建的文档。
$min	返回每个组的最低表达式值。
$push	返回每个组的表达式值数组。
$stdDevPop	返回输入值的总体标准偏差。
$stdDevSamp	返回输入值的样本标准偏差。
$sum	返回数值的总和。忽略非数字值。

3.15 累加器（在其他阶段中）

某些可用作$group阶段的累加器的运算符也可用于其他阶段，但不能用作累加器。当在其他阶段使用这些运算符时，它们不会保持其状态，并且可以将单个参数或多个参数用作输入。有关详细信息，请参阅特定的运算符页面。
在版本3.2中更改。
下面的累加器运算符也可在$project,$addFields和$set阶段。

名称	描述
$avg	返回每个文档的指定表达式或表达式列表的平均值。忽略非数字值。
$max	返回每个文档的指定表达式或表达式列表的最大值
$min	返回每个文档的指定表达式或表达式列表的最小值
$stdDevPop	返回输入值的总体标准偏差。
$stdDevSamp	返回输入值的样本标准偏差。
$sum	返回数值的总和。忽略非数字值。

3.16 变量表达式运算符

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

进入MongoDB中文手册（4.2版本）目录