# Aggregation Pipeline Operators

Note

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

## Expression Operators

These expression operators are available to construct expressions for use in the aggregation pipeline stages.

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

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

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.
`\$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 its integer.

### 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.
`\$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.
`\$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.

### 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).
`\$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.