MongoDB request DSL • opensavvy.ktmongo.dsl.aggregation • AggregationOperators

AggregationOperators¶

interface AggregationOperators : ValueOperators, ArrayValueOperators, ComparisonValueOperators, ConditionalValueOperators, ArithmeticValueOperators, StringValueOperators, TrigonometryValueOperators, TypeValueOperators

DSL to instantiate aggregation values, available in most aggregation stages.

What are aggregation values?¶

In MongoDB, operators targeting regular queries and aggregation pipelines often have the same name but a different syntax. Using KtMongo, operators keep the same name and syntax for both usages, but the way they are used in practice is still quite different. For example, compare $eq` (query)`](../../opensavvy.ktmongo.dsl.query/-filter-query/eq.html) and [$eq(aggregation).

In regular queries, operators do not have a return type, and invoking them immediately adds them to the current query. If multiple operators are called within the operation lambda, each of them is added to the query: operators "bind" themselves on invoking. Operators always take a field as first operand, and value as second operand. As an example:

users.find {
    User::age gt 18
    User::scores[0] eq 10
}

which generates:

{ "$and": [{ "$eq": { "age": 18 } }, { "$eq": { "scores.0": 10 } }] }

In aggregations, operators have a return type and only the last value of a block is taken into account, just like in regular Kotlin code. We can use regular variables to store parts of a more complex expression. Operators accept multiple aggregation values which must conform to some type requirements. As an example:

users.find {
    expr { // Use aggregation values in a regular find() request
        val maxScore = of(User::scores).max()
        maxScore lt of(15)
    }
}

which generates:

{ "expr": { "lt": [{ "$max": "$scores" }, { "$literal": 15 }] } }

As you can see, we use the of method to convert from Kotlin values or from field names to aggregation values. Because each side of an operator accepts an aggregation value, we can thus compare multiple fields from the same document, use conditionals or other complex requests.

In this example, we used the $expr query predicate to write an aggregation value within a regular query. $expr requires returning a boolean, so the last operator of the value needed to be a boolean-returning operator, which $lt is one of. In other contexts, aggregation values can be typed with any other document type.

When writing your first aggregation pipelines, keep in mind that only the last value of each lambda is used, just like when calling Kotlin functions that return a value that is unused.

Operators¶

Access values:

$literal

Conditionally compute values:

Compare values:

Arithmetic operators:

Array operators:

Document operators:

$getField

String operators:

Type operators:

Trigonometric operators and angle management:

Inheritors¶

Properties¶

`context`¶

abstract val context:

`field`¶

open val <Root, Type> KProperty1<Root, Type>.field: Field<Root, Type>

Converts a Kotlin property into a Field.

`isArray`¶

open val <R : Any> Value<R, *>.isArray: Value<R, Boolean>

Determines if this value is an array.

`isNumber`¶

open val <R : Any> Value<R, *>.isNumber: Value<R, Boolean>

Determines if this value is a number.

`length`¶

open val <Context : Any> Value<Context, String?>.length: Value<Context, Int?>

Returns the number of code points in the specified string.

`lengthUTF8`¶

open val <Context : Any> Value<Context, String?>.lengthUTF8: Value<Context, Int?>

Returns the number of UTF-8 encoded bytes in the specified string.

`type`¶

open val <R : Any> Value<R, *>.type: Value<R, >

Gets the BsonType of the current value.

Functions¶

`abs`¶

open fun <Context : Any, Result : Number?> abs(value: Value<Context, Result>): Value<Context, Result>

The absolute value of a number.

`acos`¶

open fun <Context : Any> acos(value: Value<Context, Double?>): Value<Context, Double?>

The inverse cosine (arc cosine) of a value, in radians.

`acosh`¶

open fun <Context : Any> acosh(value: Value<Context, Double?>): Value<Context, Double?>

The inverse hyperbolic cosine (hyperbolic arc cosine) of a value, in radians.

`asin`¶

open fun <Context : Any> asin(value: Value<Context, Double?>): Value<Context, Double?>

The inverse sine (arc sine) of a value, in radians.

`asinh`¶

open fun <Context : Any> asinh(value: Value<Context, Double?>): Value<Context, Double?>

The inverse hyperbolic sine (hyperbolic arc sine) of a value, in radians.

`atan`¶

open fun <Context : Any> atan(value: Value<Context, Double?>): Value<Context, Double?>

The inverse tangent (arc tangent) of a value, in radians.

`atanh`¶

open fun <Context : Any> atanh(value: Value<Context, Double?>): Value<Context, Double?>

The inverse hyperbolic tangent (hyperbolic arc tangent) of a value, in radians.

`ceil`¶

open fun <Context : Any, Result : Number?> ceil(value: Value<Context, Result>): Value<Context, Result>

The smallest integer greater than or equal to the specified value.

`concat`¶

open infix fun <Context : Any> Value<Context, String>.concat(other: Value<Context, String>): Value<Context, String>

Concatenates two strings together.

`cond`¶

open fun <R : Any, T> cond(condition: Value<R, Boolean>, ifTrue: Value<R, T>, ifFalse: Value<R, T>): Value<R, T>

Decides between two values depending on the evaluation of a boolean value.

`cos`¶

open fun <Context : Any> cos(value: Value<Context, Double?>): Value<Context, Double?>

The cosine of a value that is measured in radians.

`cosh`¶

open fun <Context : Any> cosh(value: Value<Context, Double?>): Value<Context, Double?>

The hyperbolic cosine of a value that is measured in radians.

`div`¶

open operator fun <Context : Any, Result> Value<Context, Result>.div(other: Value<Context, Result>): Value<Context, Result>

Divides one aggregation value by another.

open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: KProperty1<Root, Child>): Value<Context, Child>

Refers to field as a nested field of the current value.

open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: Field<Root, Child>): Value<Context, Child>

Refers to field as a nested field of the current value.

open operator fun <Root, Parent, Child> KProperty1<Root, Parent>.div(child: KProperty1<Parent & Any, Child>): Field<Root, Child>

Refers to child as a nested field of the current field.

`eq`¶

open infix fun <Context : Any, Result> Value<Context, Result>.eq(other: Value<Context, Result>): Value<Context, Boolean>

Compares two aggregation values and returns true if they are equivalent.

`filter`¶

open fun <Context : Any, T> Collection<T>.filter(limit: Value<Context, Number>? = null, variableName: String = "this", predicate: AggregationOperators.(Value<Any, T>) -> Value<T & Any, Boolean>): Value<Context, List<T>>

Selects a subset of an array to return based on the specified predicate, similarly to kotlin.collections.filter.

open fun <Context : Any, T> KProperty1<Context, Collection<T>>.filter(limit: Value<Context, Number>? = null, variableName: String = "this", predicate: AggregationOperators.(Value<Any, T>) -> Value<T & Any, Boolean>): Value<Context, List<T>>

Selects a subset of an array to return based on the specified predicate, similarly to kotlin.collections.filter.

open fun <Context : Any, T> Value<Context, Collection<T>>.filter(limit: Value<Context, Number>? = null, variableName: String = "this", predicate: AggregationOperators.(Value<Any, T>) -> Value<T & Any, Boolean>): Value<Context, List<T>>

Selects a subset of an array to return based on the specified predicate, similarly to kotlin.collections.filter.

open fun <Context : Any, T> Field<Context, Collection<T>>.filter(limit: Value<Context, Number>? = null, variableName: String = "this", predicate: AggregationOperators.(Value<Any, T>) -> Value<T & Any, Boolean>): Value<Context, List<T>>

Selects a subset of an array to return based on the specified predicate, similarly to kotlin.collections.filter.

`floor`¶

open fun <Context : Any, Result : Number?> floor(value: Value<Context, Result>): Value<Context, Result>

The largest integer less than or equal to the specified value.

`get`¶

open operator fun <Root, Type> KProperty1<Root, Collection<Type>>.get(index: Int): Field<Root, Type>

Refers to a specific item in an array, by its index.

open operator fun <Root, Type> KProperty1<Root, Map<String, Type>>.get(index: String): Field<Root, Type>

Refers to a specific item in a map, by its name.

`gt`¶

open infix fun <Context : Any, Result> Value<Context, Result>.gt(other: Value<Context, Result>): Value<Context, Boolean>

`gte`¶

open infix fun <Context : Any, Result> Value<Context, Result>.gte(other: Value<Context, Result>): Value<Context, Boolean>

`lowercase`¶

open fun <Context : Any> Value<Context, String?>.lowercase(): Value<Context, String?>

Converts a string to lowercase, returning the result.

`lt`¶

open infix fun <Context : Any, Result> Value<Context, Result>.lt(other: Value<Context, Result>): Value<Context, Boolean>

`lte`¶

open infix fun <Context : Any, Result> Value<Context, Result>.lte(other: Value<Context, Result>): Value<Context, Boolean>

`map`¶

open fun <Context : Any, T, R> Collection<T>.map(variableName: String = "this", transform: AggregationOperators.(Value<Any, T>) -> Value<Context, R>): Value<Context, List<R>>

Applies a transform to all elements in an array and returns the array with the applied results, similar to kotlin.collections.map.

open fun <Context : Any, T, R> KProperty1<Context, Collection<T>>.map(variableName: String = "this", transform: AggregationOperators.(Value<Any, T>) -> Value<Context, R>): Value<Context, List<R>>

Applies a transform to all elements in an array and returns the array with the applied results, similar to kotlin.collections.map.

open fun <Context : Any, T, R> Value<Context, Collection<T>>.map(variableName: String = "this", transform: AggregationOperators.(Value<Any, T>) -> Value<Context, R>): Value<Context, List<R>>

Applies a transform to all elements in an array and returns the array with the applied results, similar to kotlin.collections.map.

open fun <Context : Any, T, R> Field<Context, Collection<T>>.map(variableName: String = "this", transform: AggregationOperators.(Value<Any, T>) -> Value<Context, R>): Value<Context, List<R>>

Applies a transform to all elements in an array and returns the array with the applied results, similar to kotlin.collections.map.

`minus`¶

open operator fun <Context : Any, Result> Value<Context, Result>.minus(other: Value<Context, Result>): Value<Context, Result>

Subtracts one aggregation value from another.

`ne`¶

open infix fun <Context : Any, Result> Value<Context, Result>.ne(other: Value<Context, Result>): Value<Context, Boolean>

Compares two aggregation values and returns true if they are not equivalent.

`of`¶

open fun <Result> of(value: Result): Value<Any, Result>

Refers to a Kotlin value within an aggregation value.

open fun of(value: ): Value<Any, >

Refers to a BsonType within an aggregation value.

open fun <Context : Any, Result> of(field: KProperty1<Context, Result>): Value<Context, Result>

Refers to a field within an aggregation value.

open fun <Context : Any, Result> of(field: Field<Context, Result>): Value<Context, Result>

Refers to a field within an aggregation value.

`plus`¶

open operator fun <Context : Any, Result> Value<Context, Result>.plus(other: Value<Context, Result>): Value<Context, Result>

Sums two aggregation values.

`replace`¶

open fun <Context : Any> Value<Context, String?>.replace(find: String, replacement: String): Value<Context, String?>

Replaces all instances of find with a replacement string.

open fun <Context : Any> Value<Context, String?>.replace(find: Value<Context, String?>, replacement: Value<Context, String?>): Value<Context, String?>

Replaces all instances of find with a replacement string.

`replaceFirst`¶

open fun <Context : Any> Value<Context, String?>.replaceFirst(find: String, replacement: String): Value<Context, String?>

Replaces the first instance of find with a replacement string.

open fun <Context : Any> Value<Context, String?>.replaceFirst(find: Value<Context, String?>, replacement: Value<Context, String?>): Value<Context, String?>

Replaces the first instance of find with a replacement string.

`sin`¶

open fun <Context : Any> sin(value: Value<Context, Double?>): Value<Context, Double?>

The sine of a value that is measured in radians.

`sinh`¶

open fun <Context : Any> sinh(value: Value<Context, Double?>): Value<Context, Double?>

The hyperbolic sine of a value that is measured in radians.

`sorted`¶

open fun <Context : Any, T> Collection<T>.sorted(): Value<Context, List<T>>

Sorts an array based on its elements, in ascending order.

open fun <Context : Any, T> KProperty1<Context, Collection<T>>.sorted(): Value<Context, List<T>>

Sorts an array based on its elements, in ascending order.

open fun <Context : Any, T> Value<Context, Collection<T>>.sorted(): Value<Context, List<T>>

Sorts an array based on its elements, in ascending order.

open fun <Context : Any, T> Field<Context, Collection<T>>.sorted(): Value<Context, List<T>>

Sorts an array based on its elements, in ascending order.

`sortedBy`¶

open fun <Context : Any, T> Collection<T>.sortedBy(order: SortOptionDsl<T & Any>.() -> Unit): Value<Context, List<T>>

Sorts an array based on fields of its elements.

open fun <Context : Any, T> KProperty1<Context, Collection<T>>.sortedBy(order: SortOptionDsl<T & Any>.() -> Unit): Value<Context, List<T>>

Sorts an array based on fields of its elements.

open fun <Context : Any, T> Value<Context, Collection<T>>.sortedBy(order: SortOptionDsl<T & Any>.() -> Unit): Value<Context, List<T>>

Sorts an array based on fields of its elements.

open fun <Context : Any, T> Field<Context, Collection<T>>.sortedBy(order: SortOptionDsl<T & Any>.() -> Unit): Value<Context, List<T>>

Sorts an array based on fields of its elements.

`sortedDescending`¶

open fun <Context : Any, T> Collection<T>.sortedDescending(): Value<Context, List<T>>

Sorts an array based on its elements, in descending order.

open fun <Context : Any, T> KProperty1<Context, Collection<T>>.sortedDescending(): Value<Context, List<T>>

Sorts an array based on its elements, in descending order.

open fun <Context : Any, T> Value<Context, Collection<T>>.sortedDescending(): Value<Context, List<T>>

Sorts an array based on its elements, in descending order.

open fun <Context : Any, T> Field<Context, Collection<T>>.sortedDescending(): Value<Context, List<T>>

Sorts an array based on its elements, in descending order.

`split`¶

open fun <Context : Any> Value<Context, String>.split(delimiter: String): Value<Context, List<String>?>

Divides a string into an array of substrings based on a delimiter.

open fun <Context : Any> Value<Context, String>.split(delimiter: Value<Context, String>): Value<Context, List<String>?>

Divides a string into an array of substrings based on a delimiter.

`substring`¶

open fun <Context : Any> Value<Context, String?>.substring(indexes: IntRange): Value<Context, String?>

Returns the substring of a string.

open fun <Context : Any> Value<Context, String?>.substring(startIndex: Value<Context, Int>, length: Value<Context, Int>): Value<Context, String?>

Returns the substring of a string.

`substringUTF8`¶

open fun <Context : Any> Value<Context, String?>.substringUTF8(indexes: IntRange): Value<Context, String?>

Returns the substring of a string.

open fun <Context : Any> Value<Context, String?>.substringUTF8(startIndex: Value<Context, Int>, byteCount: Value<Context, Int>): Value<Context, String?>

Returns the substring of a string.

`switch`¶

open fun <R : Any, T> switch(vararg cases: <Value<R, Boolean>, Value<R, T>>, default: Value<R, T>? = null): Value<R, T>

Selects one value based on multiple conditions.

`take`¶

open fun <Context : Any, T> Collection<T>.take(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the first limit elements in an array, similar to kotlin.collections.take.

open fun <Context : Any, T> KProperty1<Context, Collection<T>>.take(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the first limit elements in an array, similar to kotlin.collections.take.

open fun <Context : Any, T> Value<Context, Collection<T>>.take(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the first limit elements in an array, similar to kotlin.collections.take.

open fun <Context : Any, T> Field<Context, Collection<T>>.take(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the first limit elements in an array, similar to kotlin.collections.take.

`takeLast`¶

open fun <Context : Any, T> Collection<T>.takeLast(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the last limit elements in an array, similar to kotlin.collections.takeLast.

open fun <Context : Any, T> KProperty1<Context, Collection<T>>.takeLast(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the last limit elements in an array, similar to kotlin.collections.takeLast.

open fun <Context : Any, T> Value<Context, Collection<T>>.takeLast(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the last limit elements in an array, similar to kotlin.collections.takeLast.

open fun <Context : Any, T> Field<Context, Collection<T>>.takeLast(limit: Value<Context, Number>): Value<Context, List<T>>

Returns the last limit elements in an array, similar to kotlin.collections.takeLast.

`tan`¶

open fun <Context : Any> tan(value: Value<Context, Double?>): Value<Context, Double?>

The tangent of a value that is measured in radians.

`tanh`¶

open fun <Context : Any> tanh(value: Value<Context, Double?>): Value<Context, Double?>

The hyperbolic tangent of a value that is measured in radians.

`times`¶

open operator fun <Context : Any, Result> Value<Context, Result>.times(other: Value<Context, Result>): Value<Context, Result>

Multiplies two or more aggregation values.

`toBoolean`¶

open fun <R : Any> Value<R, *>.toBoolean(): Value<R, Boolean>

Converts this value to a BsonType.Boolean.

`toDegrees`¶

open fun <Context : Any> Value<Context, Double>.toDegrees(): Value<Context, Double>

Converts an angle in radians to an angle in degrees.

`toDouble`¶

open fun <R : Any> Value<R, *>.toDouble(): Value<R, Double>

Converts this value to a BsonType.Double.

`toInstant`¶

open fun <R : Any> Value<R, *>.toInstant(): Value<R, >

Converts this value to an Instant (BsonType.Datetime).

`toInt`¶

open fun <R : Any> Value<R, *>.toInt(): Value<R, Int>

Converts this value to an Int (BsonType.Int32).

`toLong`¶

open fun <R : Any> Value<R, *>.toLong(): Value<R, Long>

Converts this value to an Long (BsonType.Int64).

`toObjectId`¶

open fun <R : Any> Value<R, *>.toObjectId(): Value<R, >

Converts this value to an ObjectId.

`toRadians`¶

open fun <Context : Any> Value<Context, Double>.toRadians(): Value<Context, Double>

Converts an angle in degrees to an angle in radians.

`toText`¶

open fun <R : Any> Value<R, *>.toText(): Value<R, String>

Converts this value to a String.

`toUuid`¶

open fun <R : Any> Value<R, *>.toUuid(): Value<R, >

Converts a string value to a Uuid (BsonType.BinaryData).

`trim`¶

open fun <Context : Any> Value<Context, String?>.trim(): Value<Context, String?>

Removes whitespace characters, including null, or the specified characters from the beginning and end of a string.

open fun <Context : Any> Value<Context, String?>.trim(vararg characters: Char): Value<Context, String?>

Removes the specified characters from the beginning and end of a string.

open fun <Context : Any> Value<Context, String?>.trim(characters: Value<Context, String?>): Value<Context, String?>

Removes the specified characters from the beginning and end of a string.

`trimEnd`¶

open fun <Context : Any> Value<Context, String?>.trimEnd(): Value<Context, String?>

Removes whitespace characters, including null, or the specified characters from the end of a string.

open fun <Context : Any> Value<Context, String?>.trimEnd(vararg characters: Char): Value<Context, String?>

Removes the specified characters from the end of a string.

open fun <Context : Any> Value<Context, String?>.trimEnd(characters: Value<Context, String?>): Value<Context, String?>

Removes the specified characters from the end of a string.

`trimStart`¶

open fun <Context : Any> Value<Context, String?>.trimStart(): Value<Context, String?>

Removes whitespace characters, including null, or the specified characters from the beginning of a string.

open fun <Context : Any> Value<Context, String?>.trimStart(vararg characters: Char): Value<Context, String?>

Removes the specified characters from the beginning of a string.

open fun <Context : Any> Value<Context, String?>.trimStart(characters: Value<Context, String?>): Value<Context, String?>

Removes the specified characters from the beginning of a string.

`uppercase`¶

open fun <Context : Any> Value<Context, String?>.uppercase(): Value<Context, String?>

Converts a string to uppercase, returning the result.

AggregationOperators¶

What are aggregation values?¶

Operators¶

See also¶

Inheritors¶

Properties¶

Functions¶