Aggregation Pipeline Operators
This page lists the supported MongoDB aggregation pipeline operators, with possible deviations.
Arithmetic
$abs
Example:
$abs: 1
$add
Example:
$add:
- "$field1"
- "$field2"
- "$field3"
$ceil
Example:
$ceil: 1
$divide
Example:
$divide:
- "$hours"
- 8
$exp
Example:
$exp: 2
$floor
Example:
$floor: 1
$ln
Example:
$ln: 1
$log
Example:
$log:
- 100
- 10
$log10
Example:
$log10: 1
$mod
Example:
$mod:
- "$myfield"
- 4
$multiply
Example:
$multiply:
- "$field1"
- "$field2"
- "$field3"
$pow
Example:
$pow:
- "$myfield"
- 2
$round
Example:
$round:
- "$value"
- 0
$sqrt
Example:
$sqrt: 25
$subtract
Example:
$subtract:
- "$field1"
- "$field2"
$trunc
Example:
$trunc:
- "$myfield"
- 0
Array
$arrayElemAt
Example:
$arrayElemAt:
-
- 0
- 1
- 3
- 1
$arrayToObject
Example:
$arrayToObject:
-
- "field1"
- 23
-
- "field2"
- 36
$concatArrays
Example:
$concatArrays:
- "$array1"
- "$array2"
- "$array3"
$elemMatch
This is actually a projection operator, but it just works on arrays and in a streaming setting it is more useful as an aggregation operator. The operator returns the first element of a given array that meets the condition.
Example:
$elemMatch:
- "$myarray"
- $gt:
1
$filter
Example:
$filter:
input: "$items"
as: "item"
cond:
$gte:
- "$$item.price"
- 100
$first
Example:
$first: "$myarray"
$in
Example:
$in:
- 2
- "$myarray"
$indexOfArray
Example:
$indexOfArray:
- "$myarray"
- 3
- 0
- 10
$isArray
Example:
$isArray: "$myfield"
$last
Example:
$last: "$myarray"
$map
Example:
$map:
input: "$myarray"
as: "el"
in:
$add:
- "$$el"
- 1
$objectToArray
Example:
$objectToArray
field1: 1
field2: 2
$range
Example:
$range:
- 0
- 10
- 2
$reduce
Example:
$reduce:
input: "$myarray"
initialValue: ""
in:
$concat:
- "$$value"
- "$$this"
$reverseArray
Example:
$reverseArray: "$myarray"
$size
Example:
$size: "$myarray"
$slice
Example:
$slice:
- "$myarray",
- 1
- 2
$zip
Example:
$zip:
- "$array1"
- "$array2"
Boolean
$and
Example:
$and:
- $gt:
- "$myfield"
- 0
- $lt:
- "$myfield"
- 10
$not
Example:
$not:
- $gt:
- "$myfield"
- 0
$or
Example:
$or:
- $lt:
- "$myfield"
- 10
- $gt:
- "$myfield"
- 20
Comparison
$cmp
Example:
$cmp:
- "$myfield"
- 100
$eq
Example:
$eq:
- "$myfield"
- 100
$gt
Example:
$gt:
- "$myfield"
- 100
$gte
Example:
$gte:
- "$myfield"
- 100
$lt
Example:
$lt:
- "$myfield"
- 100
$lte
Example:
$lte:
- "$myfield"
- 100
$ne
Example:
$ee:
- "$myfield"
- 100
Conditional
$cond
Example:
$cond:
if:
$gt:
- "$myfield"
- 10
then: 1
else: 0
$ifNull
This is the MongoDB 4.4 variant.
Example:
$ifNull:
- "$myfield"
- "My default value"
$switch
Example:
$switch:
branches:
- case:
$gt:
- "$myfield"
- 10
then: "large"
- case:
$gt:
- "$myfield"
- 0
then: "small"
default: "Unknown"
Literal
$literal
Example:
$literal:
$add:
- 2
- 3
Object
$mergeObjects
Example:
$mergeObjects:
- "$object1"
- "$object2"
- "$object3"
$objectToArray
See $objectToArray.
Set
$allElementsTrue
Example:
$allElementsTrue:
- "$field1"
- $eq:
- "$field2"
- 1
$anyElementTrue
Example:
$anyElementTrue:
- "$field1"
- $eq:
- "$field2"
- 1
$setDifference
Example:
$setDifference:
- "$array1"
- "$array2"
$setEquals
Example:
$setEquals:
- "$array1"
- "$array2"
$setIntersection
Example:
$setIntersection:
- "$array1"
- "$array2"
- "$array3"
$setIsSubset
Example:
$setIsSubset:
- "$array1"
- "$array2"
$setUnion
Example:
$setUnion:
- "$array1"
- "$array2"
- "$array3"
String
$base64Decode
Takes a Base 64 encoded string and returns the decoded string. Its value should be an expression that yields a string.
Example:
$base64Decode: "$field"
$base64Encode
Takes a string and returns the Base 64 encoded string. Its value should be an expression that yields a string.
Example:
$base64Encode: "$field"
$concat
Example:
$concat:
- "$field1"
- "$field2"
- "$field3"
$indexOfCP
Example:
$indexOfCP:
- "abcd"
- "bc"
- 0
- 3
$jsonToString
Converts a JSON value to a string representation.
Example:
$jsonToString: "$$ROOT"
$ltrim
Example:
$ltrim:
input: "$myfield"
$regexFind
Example:
$regexFind:
input: "$myfield"
regex: "/^test/"
$regexFindAll
Example:
$regexFindAll:
input: "$myfield"
regex: "/^test/"
$regexMatch
Example:
$regexMatch:
input: "$myfield"
regex: "/^test/"
$replaceAll
Example:
$replaceAll:
input: "$myfield"
find: "abc"
replacement: "ABC"
$replaceOne
Example:
$replaceOne:
input: "$myfield"
find: "abc"
replacement: "ABC"
$rtrim
Example:
$rtrim:
input: "$myfield"
$split
Example:
$split:
- "$myfield"
- ","
$strcasecmp
Example:
$strcasecmp:
- "$field1"
- "$field2"
$stringToJson
Parses a string and returns a JSON value. Its value should be an expression that yields a string.
Example:
$stringToJson: "$field"
$strLenCP
Example:
$strLenCP: "$myfield"
$substrCP
Example:
$substrCP:
- "abcd"
- 1
- 2
$toLower
Example:
$toLower: "$myfield"
$toString
Example:
$toString: 123
$toUpper
Example:
$toUpper: "$myfield"
$trim
Example:
$trim:
input: "$myfield"
$uriDecode
Takes a URI-encoded string and returns the decoded string. Its value should be an expression that yields a string.
Example:
$uriDecode: "$field"
$uriEncode
Takes a string and returns the URI-encoded string. Its value should be an expression that yields a string.
Example:
$uriEncode: "$field"
Trigonometry
$acos
Example:
$acos:
$divide:
- "$side_b"
- "$hypotenuse"
$acosh
Example:
$acosh : "$x-coordinate"
$asin
Example:
$asin:
$divide:
- "$side_b"
- "$hypotenuse"
$asinh
Example:
$asinh : "$x-coordinate"
$atan
Example:
$atan:
$divide:
- "$side_b"
- "$side_a"
$atan2
Example:
$atan2:
$divide:
- "$side_b"
- "$side_a"
$atanh
Example:
$atanh : "$x-coordinate"
$cos
Example:
$cos:
$degreesToRadians: "$angla_a:"
$cosh
Example:
$cosh:
$degreesToRadians: "$angle"
$degreesToRadians
Example:
$degreesToRadians: "$angle"
$radiansToDegrees
Example:
$radiansToDegrees: "$angle"
$sin
Example:
$sin:
$degreesToRadians: "$angle"
$sinh
Example:
$sinh:
$degreesToRadians: "$angle"
$tan
Example:
$tan:
$degreesToRadians: "$angle"
$tanh
Example:
$tanh:
$degreesToRadians: "$angle"
Type
$convert
Example:
$convert:
input: "hello"
to: "bool"
$toBool
Example:
$toBool: "hello"
$toDecimal
Example:
$toDecimal: "0.1"
$toDouble
Example:
$toDouble: "0.1"
$toInt
Example:
$toInt: "5"
$toLong
Example:
$toLong: "5"
$toString
Example:
$toString: 100
$type
Example:
$type: "$myfield"
Miscellaneous
$let
Example:
$let:
vars:
low: 1
high: "$$low"
in:
$gt:
- "$$low"
- "$$high"
$sort
The $sort extension operator receives an object with the mandatory field input, which should be an expression that yields an array. The optional field direction can have the values asc or desc, the former being the default. The optional field paths is a list of field paths. When it is present, only object values in the array are considered. They will be sorted hierarchically with the values extracted with the paths. So, if the values from the first path are equal, then the next path is tried and so on.
Example:
$sort:
input: "$myarray"
direction: "desc"
paths:
- "a.b.c"
- "a.d.e"
- "a.f"
$trace
You can wrap any expression with the $trace extension operator. This doesn't alter the result of the expression. When the log level of the Java logger net.pincette.mongo.expressions is set to INFO, the wrapped expression will be traced. If the level is FINEST all expressions are traced, regardless of the presence of the $trace operator.
Example:
$trace:
$toLower: "HELLO"
State Management
There are a few extension operators to help with state management, which is implemented with JSON Event Sourcing.
$jes-added
The expression of this operator is an object with the field pointer. It should be an expression that yields a JSON pointer. The operator returns true if the pointed field was added in the event.
Example:
type: "stream"
name: "myapp-mytype-added"
fromStream: "myapp-mytype-event"
pipeline:
- $match:
$expr:
$jes-added: "/myfield"
$jes-changed
The expression of this operator is an object with the fields pointer, from and to. Only the first field is mandatory. It should be an expression that yields a JSON pointer. The operator returns true if the pointed field has changed in the event. If both the from and to fields are present then the operator returns true when the pointed field in the event has transitioned between the two values produced by their expressions. In that case the event should be a full event, which has the _before field.
Example:
type: "stream"
name: "myapp-mytype-changed"
fromStream: "myapp-mytype-event-full"
pipeline:
- $match:
$expr:
$jes-changed:
pointer: "/myfield"
from: 0
to: 1
$jes-href
The expression of this operator is an object with the fields app, type and id. The latter is optional. All subexpressions should generate a string. The calculated value is the href path.
Example:
type: "stream"
name: "mystream"
fromStream: "myapp-mytype-aggregate"
pipeline:
- $set:
href:
$jes-href:
app: "myapp"
type: "myothertype"
id: "$otherId"
$jes-name-uuid
The expression of this operator is an object with the mandatory fields scope and key. The expression of the former should yield a string and that of the latter an integer. The result is a name-based UUID.
Example:
type: "stream"
name: "mystream"
fromStream: "myapp-mytype-aggregate"
pipeline:
- $set:
otherId:
$jes-name-uuid:
scope: "myentity"
key: "$myotherId"
$jes-removed
The expression of this operator is an object with the field pointer. It should be an expression that yields a JSON pointer. The operator returns true if the pointed field was removed in the event.
Example:
type: "stream"
name: "myapp-mytype-removed"
fromStream: "myapp-mytype-event"
pipeline:
- $match:
$expr:
$jes-removed: "/myfield"
$jes-uuid
This operator generates a UUID. It doesn't have an expression.
Example:
type: "stream"
name: "mystream"
fromStream: "myapp-mytype-aggregate"
pipeline:
- $set:
otherId:
$jes-uuid: null