聚合 >
聚合指南 >
聚合管道快速指南

聚合管道快速指南¶

阶段¶

管道阶段以数组的形式出现。文档会按顺序经过这些阶段。其中只有 $out 和 $geoNear 可以在一个管道中出现多次。

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

名称	描述
`$project`	修改流中的文档，比如增加或者移除一个字段。对于每一个输入文档，相应输出一个文档。
`$match`	对流中的文档进行过滤，仅允许符合条件的文档进入下一个阶段，过滤操作不会修改文档。 `$match` 操作使用Mongodb标准的查询条件。对于每一个输入文档，如果符合条件则输出这个文档，否则就丢弃该文档。
`$redact`	Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of `$project` and `$match`. Can be used to implement field level redaction. For each input document, outputs either one or zero document.
`$limit`	Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).
`$skip`	Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).
`$unwind`	Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array.
`$group`	Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields.
`$sort`	Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document.
`$geoNear`	Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of `$match`, `$sort`, and `$limit` for geospatial data. The output documents include an additional distance field and can include a location identifier field.
`$out`	Writes the resulting documents of the aggregation pipeline to a collection. To use the `$out` stage, it must be the last stage in the pipeline.

Expressions¶

Expressions can include field paths and system variables, literals, expression objects, and expression operators. Expressions can be nested.

Field Path and System Variables¶

Aggregation expressions use field path to access fields in the input documents. To specify a field path, use a string that prefixes with a dollar sign $ the field name or the dotted field name, if the field is in embedded document. For example, "$user" to specify the field path for the user field or "$user.name" to specify the field path to "user.name" field.

"$<field>" is equivalent to "$$CURRENT.<field>" where the CURRENT is a system variable that defaults to the root of the current object in the most stages, unless stated otherwise in specific stages. CURRENT can be rebound.

Along with the CURRENT system variable, other system variables are also available for use in expressions. To use user-defined variables, use $let and $map expressions. To access variables in expressions, use a string that prefixes the variable name with $$.

Literals¶

Literals can be of any type. However, MongoDB parses string literals that start with a dollar sign $ as a path to a field and numeric/boolean literals in expression objects as projection flags. To avoid parsing literals, use the $literal expression.

Expression Objects¶

Expression objects have the following form:

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

If the expressions are numeric or boolean literals, MongoDB treats the literals as projection flags (e.g. 1 or true to include the field), valid only in the $project stage. To avoid treating numeric or boolean literals as projection flags, use the $literal expression to wrap the numeric or boolean literals.

Operator Expressions¶

Operator expressions are similar to functions that take arguments. In general, these expressions take an array of arguments and have the following form:

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

If operator accepts a single argument, you can omit the outer array designating the argument list:

{ <operator>: <argument> }

To avoid parsing ambiguity if the argument is a literal array, you must wrap the literal array in a $literal expression or keep the outer array that designates the argument list.

Boolean Expressions¶

Boolean expressions evaluates its argument expressions as booleans and return a boolean as the result.

In addition to the false boolean value, Boolean expression evaluates as false the following: null, 0, and undefined values. The Boolean expression evaluates all other values as true, including non-zero numeric values and arrays.

名称	描述
`$and`	Returns `true` only when all its expressions evaluate to `true`. Accepts any number of argument expressions.
`$or`	Returns `true` when any of its expressions evaluates to `true`. Accepts any number of argument expressions.
`$not`	Returns the boolean value that is the opposite of its argument expression. Accepts a single argument expression.

Set Expressions¶

Set expressions performs set operation on arrays, treating arrays as sets. Set expressions ignores the duplicate entries in each input array and the order of the elements.

If the set operation returns a set, the operation filters out duplicates in the result to output an array that contains only unique entries. The order of the elements in the output array is unspecified.

If a set contains a nested array element, the set expression does not descend into the nested array but evaluates the array at top-level.

名称	描述
`$setEquals`	Returns `true` if the input sets have the same distinct elements. Accepts two or more argument expressions.
`$setIntersection`	Returns a set with elements that appear in all of the input sets. Accepts any number of argument expressions.
`$setUnion`	Returns a set with elements that appear in any of the input sets. Accepts any number of argument expressions.
`$setDifference`	Returns a set with elements that appear in the first set but not in the second set; i.e. performs a relative complement of the second set relative to the first. Accepts exactly two argument expressions.
`$setIsSubset`	Returns `true` if all elements of the first set appear in the second set, including when the first set equals the second set; i.e. not a strict subset. Accepts exactly two argument expressions.
`$anyElementTrue`	Returns `true` if any elements of a set evaluate to `true`; otherwise, returns `false`. Accepts a single argument expression.
`$allElementsTrue`	Returns `true` if no element of a set evaluates to `false`, otherwise, returns `false`. Accepts a single argument expression.

Comparison Expressions¶

Comparison expressions return a boolean except for $cmp which returns a number.

The comparison expressions take two argument expressions and compare both value and type, using the specified BSON comparison order for values of different types.

名称	描述
`$cmp`	Returns: `0` if the two values are equivalent, `1` if the first value is greater than the second, and `-1` if the first value is less than the second.
`$eq`	Returns `true` if the values are equivalent.
`$gt`	Returns `true` if the first value is greater than the second.
`$gte`	Returns `true` if the first value is greater than or equal to the second.
`$lt`	Returns `true` if the first value is less than the second.
`$lte`	Returns `true` if the first value is less than or equal to the second.
`$ne`	Returns `true` if the values are not equivalent.

Arithmetic Expressions¶

Arithmetic expressions perform mathematic operations on numbers. Some arithmetic expressions can also support date arithmetic.

名称	描述
`$add`	Adds numbers to return the sum, or adds numbers and a date to return a new date. If adding numbers and a date, treats the numbers as milliseconds. Accepts any number of argument expressions, but at most, one expression can resolve to a date.
`$subtract`	Returns the result of subtracting the second value from the first. If the two values are numbers, return the difference. If the two values are dates, return the difference in milliseconds. If the two values are a date and a number in milliseconds, return the resulting date. Accepts two argument expressions. If the two values are a date and a number, specify the date argument first as it is not meaningful to subtract a date from a number.
`$multiply`	Multiplies numbers to return the product. Accepts any number of argument expressions.
`$divide`	Returns the result of dividing the first number by the second. Accepts two argument expressions.
`$mod`	Returns the remainder of the first number divided by the second. Accepts two argument expressions.

String Expressions¶

String expressions, with the exception of $concat, only have a well-defined behavior for strings of ASCII characters.

$concat behavior is well-defined regardless of the characters used.

名称	描述
`$concat`	Concatenates any number of strings.
`$substr`	Returns a substring of a string, starting at a specified index position up to a specified length. Accepts three expressions as arguments: the first argument must resolve to a string, and the second and third arguments must resolve to integers.
`$toLower`	Converts a string to lowercase. Accepts a single argument expression.
`$toUpper`	Converts a string to uppercase. Accepts a single argument expression.
`$strcasecmp`	Performs case-insensitive string comparison and returns: `0` if two strings are equivalent, `1` if the first string is greater than the second, and `-1` if the first string is less than the second.

Text Search Expressions¶

名称	描述
`$meta`	Access text search metadata.

Array Expressions¶

名称	描述
`$size`	Returns the number of elements in the array. Accepts a single expression as argument.

Variable Expressions¶

名称	描述
`$map`	Applies a subexpression to each element of an array and returns the array of resulting values in order. Accepts named parameters.
`$let`	Defines variables for use within the scope of a subexpression and returns the result of the subexpression. Accepts named parameters.

Literal Expressions¶

名称	描述
`$literal`	Return a value without parsing. Use for values that the aggregation pipeline may interpret as an expression. For example, use a `$literal` expression to a string that starts with a `$` to avoid parsing as a field path.

Date Expressions¶

名称	描述
`$dayOfYear`	Returns the day of the year for a date as a number between 1 and 366 (leap year).
`$dayOfMonth`	Returns the day of the month for a date as a number between 1 and 31.
`$dayOfWeek`	Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday).
`$year`	Returns the year for a date as a number (e.g. 2014).
`$month`	Returns the month for a date as a number between 1 (January) and 12 (December).
`$week`	Returns the week number for a date as a number between 0 (the partial week that precedes the first Sunday of the year) and 53 (leap year).
`$hour`	Returns the hour for a date as a number between 0 and 23.
`$minute`	Returns the minute for a date as a number between 0 and 59.
`$second`	Returns the seconds for a date as a number between 0 and 60 (leap seconds).
`$millisecond`	Returns the milliseconds of a date as a number between 0 and 999.

Conditional Expressions¶

名称	描述
`$cond`	A ternary operator that evaluates one expression, and depending on the result, returns the value of one of the other two expressions. Accepts either three expressions in an ordered list or three named parameters.
`$ifNull`	Returns either the non-null result of the first expression or the result of the second expression if the first expression results in a null result. Null result encompasses instances of undefined values or missing fields. Accepts two expressions as arguments. The result of the second expression can be null.

Accumulators¶

Accumulators, available only for the $group stage, compute values by combining documents that share the same group key. Accumulators take as input a single expression, evaluating the expression once for each input document, and maintain their state for the group of documents.

名称	描述
`$sum`	Returns a sum for each group. Ignores non-numeric values.
`$avg`	Returns an average for each group. Ignores non-numeric values.
`$first`	Returns a value from the first document for each group. Order is only defined if the documents are in a defined order.
`$last`	Returns a value from the last document for each group. Order is only defined if the documents are in a defined order.
`$max`	Returns the highest expression value for each group.
`$min`	Returns the lowest expression value for each group.
`$push`	Returns an array of expression values for each group.
`$addToSet`	Returns an array of unique expression values for each group. Order of the array elements is undefined.

← 聚合指南 Aggregation Commands Comparison →