• Aggregation >
• Aggregation Reference >
• Aggregation Pipeline Quick Reference

Aggregation Pipeline Quick Reference

Note

For details on specific operator, including syntax and examples, click on the specific operator to go to its reference page.

Stages

Stages (db.collection.aggregate)

In the db.collection.aggregate method, pipeline stages appear in an array. Documents pass through the stages in sequence. All except the $out, $merge, and $geoNear stages can appear multiple times in a pipeline.

copy

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

Stage	Description
$addFields	Adds new fields to documents. Similar to $project, $addFields reshapes each document in the stream; specifically, by adding new fields to output documents that contain both the existing fields from the input documents and the newly added fields. $set is an alias for $addFields.
$bucket	Categorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries.
$bucketAuto	Categorizes incoming documents into a specific number of groups, called buckets, based on a specified expression. Bucket boundaries are automatically determined in an attempt to evenly distribute the documents into the specified number of buckets.
$collStats	Returns statistics regarding a collection or view.
$count	Returns a count of the number of documents at this stage of the aggregation pipeline.
$facet	Processes multiple aggregation pipelines within a single stage on the same set of input documents. Enables the creation of multi-faceted aggregations capable of characterizing data across multiple dimensions, or facets, in a single stage.
$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.
$graphLookup	Performs a recursive search on a collection. To each output document, adds a new array field that contains the traversal results of the recursive search for that document.
$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.
$indexStats	Returns statistics regarding the use of each index for the collection.
$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).
$listSessions	Lists all sessions that have been active long enough to propagate to the system.sessions collection.
$lookup	Performs a left outer join to another collection in the same database to filter in documents from the “joined” collection for processing.
$match	Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).
$merge	Writes the resulting documents of the aggregation pipeline to a collection. The stage can incorporate (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom update pipeline) the results into an output collection. To use the $merge stage, it must be the last stage in the pipeline. New in version 4.2.
$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.
$planCacheStats	Returns plan cache information for a collection.
$project	Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document. See also $unset for removing existing fields.
$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 documents.
$replaceRoot	Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level. $replaceWith is an alias for $replaceRoot stage.
$replaceWith	Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level. $replaceWith is an alias for $replaceRoot stage.
$sample	Randomly selects the specified number of documents from its input.
$set	Adds new fields to documents. Similar to $project, $set reshapes each document in the stream; specifically, by adding new fields to output documents that contain both the existing fields from the input documents and the newly added fields. $set is an alias for $addFields stage.
$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).
$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.
$sortByCount	Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group.
$unionWith	Performs a union of two collections; i.e. combines pipeline results from two collections into a single result set. New in version 4.4.
$unset	Removes/excludes fields from documents. $unset is an alias for $project stage that removes fields.
$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.

Stages (db.aggregate)

Starting in version 3.6, MongoDB also provides the db.aggregate method:

copy

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

The following stages use the db.aggregate() method and not the db.collection.aggregate() method.

Stage	Description
$currentOp	Returns information on active and/or dormant operations for the MongoDB deployment.
$listLocalSessions	Lists all active sessions recently in use on the currently connected mongos or mongod instance. These sessions may have not yet propagated to the system.sessions collection.

Stages Available for Updates

Starting in MongoDB 4.2, you can use the aggregation pipeline for updates in:

Command	mongo Shell Methods
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()

For the updates, the pipeline can consist of the following stages:

• $addFields and its alias $set
• $project and its alias $unset
• $replaceRoot and its alias $replaceWith.

See also

Updates with Aggregation Pipeline

Expressions

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

Field Paths

Aggregation expressions use field path to access fields in the input documents. To specify a field path, prefix the field name or the dotted field name (if the field is in the embedded document) with a dollar sign $. 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, unless stated otherwise in specific stages.

Aggregation Variables

MongoDB provides various aggregation system variables for use in expressions. To access variables, prefix the variable name with $$. For example:

Variable	Access via $$	Brief Description
NOW	$$NOW	Returns the current datetime value, which is same across all members of the deployment and remains constant throughout the aggregation pipeline. (Available in 4.2+)
CLUSTER_TIME	$$CLUSTER_TIME	Returns the current timestamp value, which is same across all members of the deployment and remains constant throughout the aggregation pipeline. For replica sets and sharded clusters only. (Available in 4.2+)
ROOT	$$ROOT	References the root document, i.e. the top-level document.
CURRENT	$$CURRENT	References the start of the field path, which by default is ROOT but can be changed.
REMOVE	$$REMOVE	Allows for the conditional exclusion of fields. (Available in 3.6+)
DESCEND	$$DESCEND	One of the allowed results of a $redact expression.
PRUNE	$$PRUNE	One of the allowed results of a $redact expression.
KEEP	$$KEEP	One of the allowed results of a $redact expression.

For a more detailed description of these variables, see system variables.

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:

copy

{ <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:

copy

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

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

copy

{ <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.

Arithmetic Expression Operators

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

Name	Description
$abs	Returns the absolute value of a number.
$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.
$ceil	Returns the smallest integer greater than or equal to the specified number.
$divide	Returns the result of dividing the first number by the second. Accepts two argument expressions.
$exp	Raises e to the specified exponent.
$floor	Returns the largest integer less than or equal to the specified number.
$ln	Calculates the natural log of a number.
$log	Calculates the log of a number in the specified base.
$log10	Calculates the log base 10 of a number.
$mod	Returns the remainder of the first number divided by the second. Accepts two argument expressions.
$multiply	Multiplies numbers to return the product. Accepts any number of argument expressions.
$pow	Raises a number to the specified exponent.
$round	Rounds a number to to a whole integer or to a specified decimal place.
$sqrt	Calculates the square root.
$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.
$trunc	Truncates a number to a whole integer or to a specified decimal place.

Array Expression Operators

$arrayElemAt	Returns the element at the specified array index.
$arrayToObject	Converts an array of key value pairs to a document.
$concatArrays	Concatenates arrays to return the concatenated array.
$filter	Selects a subset of the array to return an array with only the elements that match the filter condition.
$first	Returns the first array element. Distinct from $first accumulator.
$in	Returns a boolean indicating whether a specified value is in an array.
$indexOfArray	Searches an array for an occurrence of a specified value and returns the array index of the first occurrence. If the substring is not found, returns -1.
$isArray	Determines if the operand is an array. Returns a boolean.
$last	Returns the last array element. Distinct from $last accumulator.
$map	Applies a subexpression to each element of an array and returns the array of resulting values in order. Accepts named parameters.
$objectToArray	Converts a document to an array of documents representing key-value pairs.
$range	Outputs an array containing a sequence of integers according to user-defined inputs.
$reduce	Applies an expression to each element in an array and combines them into a single value.
$reverseArray	Returns an array with the elements in reverse order.
$size	Returns the number of elements in the array. Accepts a single expression as argument.
$slice	Returns a subset of an array.
$zip	Merge two arrays together.

Boolean Expression Operators

Boolean expressions evaluate their 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.

Name	Description
$and	Returns true only when all its expressions evaluate 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.
$or	Returns true when any of its expressions evaluates to true. Accepts any number of argument expressions.

Comparison Expression Operators

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.

Conditional Expression Operators

Name	Description
$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.
$switch	Evaluates a series of case expressions. When it finds an expression which evaluates to true, $switch executes a specified expression and breaks out of the control flow.

Custom Aggregation Expression Operators

Name	Description
$accumulator	Defines a custom accumulator function. New in version 4.4.
$function	Defines a custom function. New in version 4.4.

Data Size Expression Operators

The following operators return the size of a data element:

Name	Description
$binarySize	Returns the size of a given string or binary data value’s content in bytes.
$bsonSize	Returns the size in bytes of a given document (i.e. bsontype Object) when encoded as BSON.

Date Expression Operators

The following operators returns date objects or components of a date object:

Name	Description
$dateFromParts	Constructs a BSON Date object given the date’s constituent parts.
$dateFromString	Converts a date/time string to a date object.
$dateToParts	Returns a document containing the constituent parts of a date.
$dateToString	Returns the date as a formatted string.
$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).
$dayOfYear	Returns the day of the year for a date as a number between 1 and 366 (leap year).
$hour	Returns the hour for a date as a number between 0 and 23.
$isoDayOfWeek	Returns the weekday number in ISO 8601 format, ranging from 1 (for Monday) to 7 (for Sunday).
$isoWeek	Returns the week number in ISO 8601 format, ranging from 1 to 53. Week numbers start at 1 with the week (Monday through Sunday) that contains the year’s first Thursday.
$isoWeekYear	Returns the year number in ISO 8601 format. The year starts with the Monday of week 1 (ISO 8601) and ends with the Sunday of the last week (ISO 8601).
$millisecond	Returns the milliseconds of a date as a number between 0 and 999.
$minute	Returns the minute for a date as a number between 0 and 59.
$month	Returns the month for a date as a number between 1 (January) and 12 (December).
$second	Returns the seconds for a date as a number between 0 and 60 (leap seconds).
$toDate	Converts value to a Date. New in version 4.0.
$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).
$year	Returns the year for a date as a number (e.g. 2014).

The following arithmetic operators can take date operands:

Name	Description
$add	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 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.

Literal Expression Operator

Name	Description
$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.

Object Expression Operators

Name	Description
$mergeObjects	Combines multiple documents into a single document. New in version 3.6.
$objectToArray	Converts a document to an array of documents representing key-value pairs. New in version 3.6.

Set Expression Operators

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.

Name	Description
$allElementsTrue	Returns true if no element of a set evaluates to false, otherwise, returns false. Accepts a single argument expression.
$anyElementTrue	Returns true if any elements of a set evaluate to true; otherwise, returns false. Accepts a single argument expression.
$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.
$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.
$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.
$setUnion	Returns a set with elements that appear in any of the input sets.

String Expression Operators

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.

Name	Description
$concat	Concatenates any number of strings.
$dateFromString	Converts a date/time string to a date object.
$dateToString	Returns the date as a formatted string.
$indexOfBytes	Searches a string for an occurrence of a substring and returns the UTF-8 byte index of the first occurrence. If the substring is not found, returns -1.
$indexOfCP	Searches a string for an occurrence of a substring and returns the UTF-8 code point index of the first occurrence. If the substring is not found, returns -1
$ltrim	Removes whitespace or the specified characters from the beginning of a string. New in version 4.0.
$regexFind	Applies a regular expression (regex) to a string and returns information on the first matched substring. New in version 4.2.
$regexFindAll	Applies a regular expression (regex) to a string and returns information on the all matched substrings. New in version 4.2.
$regexMatch	Applies a regular expression (regex) to a string and returns a boolean that indicates if a match is found or not. New in version 4.2.
$replaceOne	Replaces the first instance of a matched string in a given input. New in version 4.4.
$replaceAll	Replaces all instances of a matched string in a given input. New in version 4.4.
$rtrim	Removes whitespace or the specified characters from the end of a string. New in version 4.0.
$split	Splits a string into substrings based on a delimiter. Returns an array of substrings. If the delimiter is not found within the string, returns an array containing the original string.
$strLenBytes	Returns the number of UTF-8 encoded bytes in a string.
$strLenCP	Returns the number of UTF-8 code points in a string.
$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.
$substr	Deprecated. Use $substrBytes or $substrCP.
$substrBytes	Returns the substring of a string. Starts with the character at the specified UTF-8 byte index (zero-based) in the string and continues for the specified number of bytes.
$substrCP	Returns the substring of a string. Starts with the character at the specified UTF-8 code point (CP) index (zero-based) in the string and continues for the number of code points specified.
$toLower	Converts a string to lowercase. Accepts a single argument expression.
$toString	Converts value to a string. New in version 4.0.
$trim	Removes whitespace or the specified characters from the beginning and end of a string. New in version 4.0.
$toUpper	Converts a string to uppercase. Accepts a single argument expression.

Text Expression Operator

Name	Description
$meta	Access available per-document metadata related to the aggregation operation.

Trigonometry Expression Operators

Trigonometry expressions perform trigonometric operations on numbers. Values that represent angles are always input or output in radians. Use $degreesToRadians and $radiansToDegrees to convert between degree and radian measurements.

Name	Description
$sin	Returns the sine of a value that is measured in radians.
$cos	Returns the cosine of a value that is measured in radians.
$tan	Returns the tangent of a value that is measured in radians.
$asin	Returns the inverse sin (arc sine) of a value in radians.
$acos	Returns the inverse cosine (arc cosine) of a value in radians.
$atan	Returns the inverse tangent (arc tangent) of a value in radians.
$atan2	Returns the inverse tangent (arc tangent) of y / x in radians, where y and x are the first and second values passed to the expression respectively.
$asinh	Returns the inverse hyperbolic sine (hyperbolic arc sine) of a value in radians.
$acosh	Returns the inverse hyperbolic cosine (hyperbolic arc cosine) of a value in radians.
$atanh	Returns the inverse hyperbolic tangent (hyperbolic arc tangent) of a value in radians.
$degreesToRadians	Converts a value from degrees to radians.
$radiansToDegrees	Converts a value from radians to degrees.

Type Expression Operators

Name	Description
$convert	Converts a value to a specified type. New in version 4.0.
$isNumber	Returns boolean true if the specified expression resolves to an integer, decimal, double, or long. Returns boolean false if the expression resolves to any other BSON type, null, or a missing field. New in version 4.4.
$toBool	Converts value to a boolean. New in version 4.0.
$toDate	Converts value to a Date. New in version 4.0.
$toDecimal	Converts value to a Decimal128. New in version 4.0.
$toDouble	Converts value to a double. New in version 4.0.
$toInt	Converts value to an integer. New in version 4.0.
$toLong	Converts value to a long. New in version 4.0.
$toObjectId	Converts value to an ObjectId. New in version 4.0.
$toString	Converts value to a string. New in version 4.0.
$type	Return the BSON data type of the field.

Accumulators ($group)

Available for use in the $group stage, accumulators are operators that maintain their state (e.g. totals, maximums, minimums, and related data) as documents progress through the pipeline.

When used as accumulators in the $group stage, these operators take as input a single expression, evaluating the expression once for each input document, and maintain their stage for the group of documents that share the same group key.

Name	Description
$accumulator	Returns the result of a user-defined accumulator function.
$addToSet	Returns an array of unique expression values for each group. Order of the array elements is undefined.
$avg	Returns an average of numerical values. 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. Distinct from the $first array operator.
$last	Returns a value from the last document for each group. Order is only defined if the documents are in a defined order. Distinct from the $last array operator.
$max	Returns the highest expression value for each group.
$mergeObjects	Returns a document created by combining the input documents for each group.
$min	Returns the lowest expression value for each group.
$push	Returns an array of expression values for each group.
$stdDevPop	Returns the population standard deviation of the input values.
$stdDevSamp	Returns the sample standard deviation of the input values.
$sum	Returns a sum of numerical values. Ignores non-numeric values.

Accumulators (in Other Stages)

Some operators that are available as accumulators for the $group stage are also available for use in other stages but not as accumulators. When used in these other stages, these operators do not maintain their state and can take as input either a single argument or multiple arguments. For details, refer to the specific operator page.

Changed in version 3.2.

The following accumulator operators are also available in the $project, $addFields, and $set stages.

Name	Description
$avg	Returns an average of the specified expression or list of expressions for each document. Ignores non-numeric values.
$max	Returns the maximum of the specified expression or list of expressions for each document
$min	Returns the minimum of the specified expression or list of expressions for each document
$stdDevPop	Returns the population standard deviation of the input values.
$stdDevSamp	Returns the sample standard deviation of the input values.
$sum	Returns a sum of numerical values. Ignores non-numeric values.

Variable Expression Operators

Name	Description
$let	Defines variables for use within the scope of a subexpression and returns the result of the subexpression. Accepts named parameters. Accepts any number of argument expressions.

Index of Expression Operators

$abs $accumulator $acos $acosh $add $addToSet $allElementsTrue $and $anyElementTrue $arrayElemAt $arrayToObject $asin $asinh $atan $atan2 $atanh $avg $binarySize $bsonSize $ceil $cmp $concat $concatArrays $cond $convert $cos $dateFromParts $dateFromString $dateToParts $dateToString $dayOfMonth $dayOfWeek $dayOfYear

$degreesToRadians $divide $eq $exp $filter $first (array) $first (accumulator) $floor $function $gt $gte $hour $ifNull $in $indexOfArray $indexOfBytes $indexOfCP $isArray $isNumber $isoDayOfWeek $isoWeek $isoWeekYear $last (array) $last (accumulator) $let $literal $ln $log $log10 $lt $lte $ltrim $map

$max $mergeObjects $meta $millisecond $min $minute $mod $month $multiply $ne $not $objectToArray $or $pow $push $radiansToDegrees $range $reduce $regexFind $regexFindAll $regexMatch $replaceOne $replaceAll $reverseArray $round $rtrim $second $setDifference $setEquals $setIntersection $setIsSubset $setUnion $sin

$size $slice $split $sqrt $stdDevPop $stdDevSamp $strLenBytes $strLenCP $strcasecmp $substr $substrBytes $substrCP $subtract $sum $switch $tan $toBool $toDate $toDecimal $toDouble $toInt $toLong $toLower $toObjectId $toString $toUpper $trim $trunc $type $week $year $zip

←   Aggregation Reference Aggregation Commands  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.