Contents x
    Transformation Pipeline Expressions
    • 12 Minutes to read
    • Dark
      Light
    Contents

    Transformation Pipeline Expressions

    • 12 Minutes to read
    • Dark
      Light
    Article summary

    On this page, you will find a comprehensive list of the following data transformation pipeline expressions:

    For more information on types of expressions, refer to the article on Transformation Pipeline.

    Aggregation Variables

    VariableDescription
    $$NOWReturns the current datetime value. Remains constant across all stages of the aggregation pipeline.
    $$CLUSTER_TIMEProvides the current timestamp in replica sets and sharded clusters. Consistent across all deployment members and throughout the pipeline stages.
    $$ROOTRefers to the top-level document currently in the aggregation pipeline stage.
    $$CURRENTPoints to the start of the field path being processed. It starts the same as ROOT and is modifiable, which affects the interpretation of $ field path accesses.
    $$REMOVEEvaluates to a missing value to conditionally exclude fields. Used in $project to omit fields.
    $$DESCENDAn allowable outcome of a $redact stage.
    $$PRUNEAnother possible result of a $redact stage, indicating the removal of data.
    $$KEEPAn outcome of $redact stage indicating that the data should be retained.

    Operator Expressions

    Basic Operations

    Data Types and Structures

    Advanced Operations

    Accumulators

    Arithmetic Expression Operators

    Arithmetic expression operators are mathematical operations on numbers, with some supporting date arithmetic.

    OperatorDescription
    $absReturns the absolute value of a number.
    $addAdds numbers or adds milliseconds to a date. Accepts multiple arguments with at most one date.
    $ceilRounds up to the nearest integer.
    $divideDivides the first number by the second. Requires two arguments.
    $expRaises e to a given exponent.
    $floorRounds down to the nearest integer.
    $lnComputes the natural log of a number.
    $logComputes the log of a number for a given base.
    $log10Computes the base 10 logarithm of a number.
    $modReturns the remainder after division. Requires two arguments.
    $multiplyMultiplies numbers. Accepts multiple arguments.
    $powRaises a number to a given exponent.
    $roundRounds a number to the nearest integer or specified decimal place.
    $sqrtComputes the square root of a number.
    $subtractSubtracts numbers, dates, or subtracts milliseconds from a date. Requires two arguments, with date first if used.
    $truncTruncates a number to an integer or specified decimal place.

    Array Expression Operators

    OperatorDescription
    $arrayElemAtRetrieves the element at a specified array index.
    $arrayToObjectTransforms an array of key-value pairs into a document.
    $concatArraysConcatenates multiple arrays.
    $filterFilters an array based on a condition.
    $firstRetrieves the first array element (different from $first accumulator).
    $inChecks if a value exists in an array; returns boolean.
    $indexOfArrayFinds the first occurrence of a value in an array or returns -1 if not found.
    $isArrayChecks if the operand is an array; returns boolean.
    $lastRetrieves the last array element (different from $last accumulator).
    $mapApplies a subexpression to each array element, returning an array of results.
    $objectToArrayConverts a document into an array of key-value pair documents.
    $rangeGenerates an array of integers based on user-defined parameters.
    $reduceCombines array elements using an expression into a single value.
    $reverseArrayReverses the order of array elements.
    $sizeCounts elements in an array.
    $sliceExtracts a portion of an array.
    $zipMerges two arrays into one.

    Boolean Expression Operators

    Boolean expressions return a boolean result based on their arguments. They interpret null, 0, and undefined as false. All other values, including non-zero numbers and arrays, are interpreted as true.

    OperatorDescription
    $andReturns true if all argument expressions are true.
    $notInverts the boolean value of its argument.
    $orReturns true if at least one of its argument expressions is true.

    Comparison Expression Operators

    Comparison expressions compare both value and type of two arguments, using the BSON comparison order for different types. $cmp uniquely returns a number, while others return a boolean.

    OperatorDescription
    $cmpOutputs 0 for equivalent values, 1 if the first is greater, and -1 if the first is less.
    $eqTrue when values are equivalent.
    $gtTrue when the first value exceeds the second.
    $gteTrue when the first value is greater or matches the second.
    $ltTrue when the first value is smaller than the second.
    $lteTrue when the first value is smaller or matches the second.
    $neTrue when values are not equivalent.

    Conditional Expression Operators

    OperatorDescription
    $condEvaluates the first expression and, based on its result, returns the value from either the second or third expression. Can accept three ordered expressions or three named parameters.
    $ifNullIf the first expression is null, undefined, or missing, returns the result of the second expression. Accepts two expressions; the second one can also return null.
    $switchChecks multiple case expressions. On the first true case, executes the corresponding expression and exits.

    Custom Aggregation Expression Operators

    OperatorDescription
    $accumulatorAllows creation of a custom accumulator for use in aggregation pipelines.
    $functionAllows creation of a custom JavaScript function for use in expressions.

    Data Size Operators

    OperatorDescription
    $binarySizeReturns the byte size of a string or binary data value's content.
    $bsonSizeReturns the byte size of a document when encoded as BSON (bsontype Object).

    Date Expression Operators

    OperatorDescription
    $dateFromPartsConstructs a BSON Date object from its constituent parts.
    $dateFromStringConverts a date/time string to a BSON Date object.
    $dateToPartsReturns the constituent parts of a date as a document.
    $dateToStringFormats the date as a string.
    $dayOfMonthReturns the day of the month as a number (1-31).
    $dayOfWeekReturns the weekday number (1 for Sunday to 7 for Saturday).
    $dayOfYearReturns the day number of the year (1-366).
    $hourReturns the hour component (0-23).
    $isoDayOfWeekReturns the weekday number in ISO 8601 format (1 for Monday to 7 for Sunday).
    $isoWeekReturns the ISO 8601 week number (1-53).
    $isoWeekYearReturns the year number as per ISO 8601.
    $millisecondReturns the milliseconds component (0-999).
    $minuteReturns the minute component (0-59).
    $monthReturns the month number (1 for January to 12 for December).
    $secondReturns the seconds component (0-60).
    $toDateConverts a value to a Date. New in version 4.0.
    $weekReturns the week number (0 for the partial week before the first Sunday to 53 for a leap year).
    $yearReturns the year as a number.

    It is possible to use the following arithmetic operators to work with date operands.

    OperatorDescription
    $addAdds numbers to a date, treating numbers as milliseconds. At most, one argument can resolve to a date.
    $subtractSubtracts values; if both are dates, returns difference in milliseconds. With a date and number, returns the resulting date. Specify the date first when subtracting a number from it.

    Literal Expression Operator

    OperatorDescription
    $literalReturns a value without interpretation. Useful for values that may be mistaken as expressions, especially strings starting with $. Prevents accidental field path parsing.

    Miscellaneous Operators

    OperatorDescription
    $randReturns a random float between 0 and 1.
    $sampleRateSelects documents randomly based on a given rate. The chosen count is roughly the rate's percentage of the total documents.

    Object Expression Operators

    OperatorDescription
    $mergeObjectsCombines multiple documents into one.
    $objectToArrayConverts a document into an array of documents representing key-value pairs.

    Set Expression Operators

    Set expressions operate on arrays, treating them as sets. They filter out any duplicate entries within each array and do not guarantee a specific order for the elements in the resulting array. Nested arrays are evaluated at the top level without delving into their individual elements.

    OperatorDescription
    $allElementsTrueEvaluates if all elements in a set are true. Accepts a single argument.
    $anyElementTrueEvaluates if at least one element in a set is true. Accepts a single argument.
    $setDifferenceReturns elements that are in the first set but not in the second, essentially performing a relative complement. Requires two arguments.
    $setEqualsChecks if the input sets contain the same distinct elements. Can accept two or more arguments.
    $setIntersectionReturns elements common to all input sets. Can accept any number of arguments.
    $setIsSubsetChecks if all elements of the first set are present in the second, but not necessarily vice versa. Requires two arguments.
    $setUnionCombines and returns elements from all input sets without duplicates.

    String Expression Operators

    String expressions primarily operate with well-defined behavior on ASCII character strings. However, the $concat function is an exception, exhibiting consistent behavior regardless of the character set.

    OperatorDescription
    $concatConcatenates any number of strings.
    $dateFromStringConverts a date/time string to a date object.
    $dateToStringReturns the date as a formatted string.
    $indexOfBytesSearches a string for a substring and returns the UTF-8 byte index of the first occurrence. Returns -1 if not found.
    $indexOfCPSearches a string and returns the UTF-8 code point index of the first occurrence of a substring. Returns -1 if not found.
    $ltrimRemoves whitespace or specified characters from the beginning of a string.
    $regexFindApplies a regex to a string and returns information on the first matched substring.
    $regexFindAllApplies a regex to a string and returns information on all matched substrings.
    $regexMatchApplies a regex to a string and returns a boolean indicating if a match is found.
    $replaceOneReplaces the first instance of a matched string in the input.
    $replaceAllReplaces all instances of a matched string in the input.
    $rtrimRemoves whitespace or specified characters from the end of a string. New in version 4.0.
    $splitSplits a string based on a delimiter and returns an array of substrings.
    $strLenBytesReturns the number of UTF-8 encoded bytes in a string.
    $strLenCPReturns the number of UTF-8 code points in a string.
    $strcasecmpPerforms case-insensitive string comparison and returns 0 if equivalent, 1 if the first is greater, -1 if less.
    $substrDeprecated. Use $substrBytes or $substrCP instead.
    $substrBytesReturns a substring starting at a specified UTF-8 byte index and continues for a specified number of bytes.
    $substrCPReturns a substring starting at a specified UTF-8 code point index and continues for a specified number of code points.
    $toLowerConverts a string to lowercase.
    $toStringConverts a value to a string.
    $trimRemoves whitespace or specified characters from the start and end of a string.
    $toUpperConverts a string to uppercase.

    Text Expression Operators

    OperatorDescription
    $metaRetrieves specific metadata about a document during aggregation, such as the relevance score from a text search.

    Trigonometry Expression Operators

    Trigonometry expressions handle trigonometric operations on numerical values. When working with angles, these expressions always use radians. For conversions between degrees and radians, utilize $degreesToRadians and $radiansToDegrees.

    OperatorDescription
    $sinReturns the sine of a value measured in radians.
    $cosReturns the cosine of a value measured in radians.
    $tanReturns the tangent of a value measured in radians.
    $asinReturns the inverse sin (arc sine) of a value in radians.
    $acosReturns the inverse cosine (arc cosine) of a value in radians.
    $atanReturns the inverse tangent (arc tangent) of a value in radians.
    $atan2Returns 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.
    $asinhReturns the inverse hyperbolic sine (hyperbolic arc sine) of a value in radians.
    $acoshReturns the inverse hyperbolic cosine (hyperbolic arc cosine) of a value in radians.
    $atanhReturns the inverse hyperbolic tangent (hyperbolic arc tangent) of a value in radians.
    $sinhReturns the hyperbolic sine of a value measured in radians.
    $coshReturns the hyperbolic cosine of a value measured in radians.
    $tanhReturns the hyperbolic tangent of a value measured in radians.
    $degreesToRadiansConverts a value from degrees to radians.
    $radiansToDegreesConverts a value from radians to degrees.

    Type Expression Operators

    OperatorDescription
    $convertConverts a value to a specified type.
    $isNumberReturns true if the expression resolves to an integer, decimal, double, or long; otherwise, returns false.
    $toBoolConverts a value to a boolean.
    $toDateConverts a value to a date.
    $toDecimalConverts a value to Decimal128.
    $toDoubleConverts a value to a double.
    $toIntConverts a value to an integer.
    $toLongConverts a value to a long.
    $toObjectIdConverts a value to an ObjectId.
    $toStringConverts a value to a string.
    $typeReturns the BSON data type of the field.

    Accumulators ($group)

    In the $group stage{target=_blank} of the aggregation pipeline, accumulators are essential operators that keep track of data states such as totals, peaks, troughs, and more. Each accumulator evaluates an expression for every document in its group. The unique feature of these operators is their ability to retain their state across documents with the same group key.

    OperatorDescription
    $accumulatorReturns the result of a user-defined accumulator function.
    $addToSetReturns an array of unique expression values for each group.
    $avgCalculates the average of numerical values. Excludes non-numeric values.
    $firstRetrieves a value from the first document in each group. Defined order is necessary for consistent results.
    $lastRetrieves a value from the last document in each group. Defined order is necessary for consistent results.
    $maxIdentifies the highest expression value in each group.
    $mergeObjectsCombines input documents to create a single document for each group.
    $minIdentifies the lowest expression value in each group.
    $pushProduces an array of expression values for each group.
    $stdDevPopCalculates the population standard deviation of input values.
    $stdDevSampCalculates the sample standard deviation of input values.
    $sumSums up numerical values in each group. Excludes non-numeric values.

    Accumulators (in Other Stages)

    Some operators that are available as accumulators for the $group stage{target=_blank} 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.

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

    NameDescription
    $avgComputes an average for the given expression or set of expressions per document, ignoring non-numeric values.
    $firstRetrieves a value from the initial document in each group. Order matters if documents follow a specific sequence.
    $lastGleans a value from the last document in each group. Document sequence matters for a defined order.
    $maxDetermines the peak value from the provided expression or set of expressions for every document.
    $minIdentifies the lowest value from the designated expression or collection of expressions per document.
    $stdDevPopComputes the overall standard deviation from the input values.
    $stdDevSampCalculates the sample standard deviation from the input values.
    $sumAggregates the sum of numerical entries, excluding non-numeric ones.

    Variable Expression Operators

    NameDescription
    $letDefines variables for use in a subexpression's scope and returns its result. It accepts named parameters and can take any number of argument expressions.
    Was this article helpful?
    What's Next