ArrayValueOperators

interface ArrayValueOperators : ValueOperators

Operators to manipulate arrays.

To learn more about aggregation operators, see opensavvy.ktmongo.dsl.aggregation.AggregationOperators.

Inheritors

• AggregationOperators

Properties

context

@LowLevelApi



abstract override val context: BsonContext

The strategy used when converting from KProperty1 to Field.

field

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

Converts a Kotlin property into a Field.

Functions

average

open fun <Context : Any, T : Number> Value<Context, Collection<Number?>>.average(): Value<Context, T>

Returns the average of the elements in the array.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val averageScore: Double,
)

players.updateManyWithPipeline {
    set {
        Player::averageScore set Player::scores.average()
    }
}

External resources

• Official documentation

open fun <Context : Any, T : Number> Field<Context, Collection<Number?>>.average(): Value<Context, T>

Returns the average of the elements in the array.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val averageScore: Double,
)

players.updateManyWithPipeline {
    set {
        Player::averageScore set Player::scores.average()
    }
}

External resources

• Official documentation

open fun <Context : Any, T : Number> KProperty1<Context, Collection<Number?>>.average(): Value<Context, T>

Returns the average of the elements in the array.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val averageScore: Double,
)

players.updateManyWithPipeline {
    set {
        Player::averageScore set Player::scores.average()
    }
}

External resources

• Official documentation

open fun <Context : Any, T : Number> Iterable<Value<Context, Number?>>.average(): Value<Context, T>

Returns the average of the elements in the array.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val averageScore: Double,
)

players.updateManyWithPipeline {
    set {
        Player::averageScore set Player::scores.average()
    }
}

External resources

• Official documentation

open fun <Context : Any, T : Number> average(vararg input: Value<Context, Number?>): Value<Context, T>

Returns the average of the elements in the array.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val averageScore: Double,
)

players.updateManyWithPipeline {
    set {
        Player::averageScore set Player::scores.average()
    }
}

External resources

• Official documentation

open fun <Context : Any, T : Number> average(): Value<Context, T>

Deprecated (with error)

Computing the average of 0 elements makes no sense, you should specify the elements to average as the receiver or as arguments.

div

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.

Examples

class User(
    val name: String,
)

class Data(
    val users: List<User>,
    val userNames: List<Int>,
)

data.aggregate()
    .set {
        Data::userNames set Data::users.map { it / User::name }
    }

External resources

• Official documentation

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.

Examples

class User(
    val name: String,
)

class Data(
    val users: List<User>,
    val userNames: List<Int>,
)

data.aggregate()
    .set {
        Data::userNames set Data::users.map { it / User::name }
    }

External resources

• Official documentation

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'sfilter``.

The returned elements are in the original order.

Example

class Sensor(
    val measurements: List<Int>,
)

collection.updateManyWithPipeline {
    set {
        Sensor::measurements set (Sensor::measurements).filter { it gte of(0) }
    }
}

External resources

• Official documentation

Parameters

• limit: If set, specifies a maximum number of elements returned: only the first limit matching elements are returned, even if there are more matching elements. Must be greater or equal to 1, or be null.

• variableName: The name of the temporary variable passed to the predicate lambda, which represents the current element being iterated over. By default, "this". Setting this parameter is only useful when using nested filter or other similar calls, which could otherwise conflict.

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'sfilter``.

The returned elements are in the original order.

Example

class Sensor(
    val measurements: List<Int>,
)

collection.updateManyWithPipeline {
    set {
        Sensor::measurements set (Sensor::measurements).filter { it gte of(0) }
    }
}

External resources

• Official documentation

Parameters

• limit: If set, specifies a maximum number of elements returned: only the first limit matching elements are returned, even if there are more matching elements. Must be greater or equal to 1, or be null.

• variableName: The name of the temporary variable passed to the predicate lambda, which represents the current element being iterated over. By default, "this". Setting this parameter is only useful when using nested filter or other similar calls, which could otherwise conflict.

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'sfilter``.

The returned elements are in the original order.

Example

class Sensor(
    val measurements: List<Int>,
)

collection.updateManyWithPipeline {
    set {
        Sensor::measurements set (Sensor::measurements).filter { it gte of(0) }
    }
}

External resources

• Official documentation

Parameters

• limit: If set, specifies a maximum number of elements returned: only the first limit matching elements are returned, even if there are more matching elements. Must be greater or equal to 1, or be null.

• variableName: The name of the temporary variable passed to the predicate lambda, which represents the current element being iterated over. By default, "this". Setting this parameter is only useful when using nested filter or other similar calls, which could otherwise conflict.

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'sfilter``.

The returned elements are in the original order.

Example

class Sensor(
    val measurements: List<Int>,
)

collection.updateManyWithPipeline {
    set {
        Sensor::measurements set (Sensor::measurements).filter { it gte of(0) }
    }
}

External resources

• Official documentation

Parameters

• limit: If set, specifies a maximum number of elements returned: only the first limit matching elements are returned, even if there are more matching elements. Must be greater or equal to 1, or be null.

• variableName: The name of the temporary variable passed to the predicate lambda, which represents the current element being iterated over. By default, "this". Setting this parameter is only useful when using nested filter or other similar calls, which could otherwise conflict.

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.

open operator fun <Root, Type> Field<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> Field<Root, Map<String, Type>>.get(key: String): Field<Root, Type>

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

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::scores set Player::scores
            .map {
                it + of(1)
            }
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::scores set Player::scores
            .map {
                it + of(1)
            }
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::scores set Player::scores
            .map {
                it + of(1)
            }
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::scores set Player::scores
            .map {
                it + of(1)
            }
    }
}

External resources

• Official documentation

of

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

Refers to a field within an aggregation value.

Example

class Product(
    val acceptanceDate: Instant,
    val publishingDate: Instant,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::publishingDate) lt of(Product::acceptanceDate)
    }
}

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

Refers to a field within an aggregation value.

Example

class Product(
    val acceptanceDate: Instant,
    val publishingDate: Instant,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::publishingDate) lt of(Product::acceptanceDate)
    }
}

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

Refers to a Kotlin value within an aggregation value.

Example

class Product(
    val age: Int,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::age) lt of(15)
    }
}

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

Refers to a BsonType within an aggregation value.

Example

class Product(
    val age: Int,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::age).type eq of(BsonType.Int32)
    }
}

sorted

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

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

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val worstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sorted()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by elements in descending 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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val worstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sorted()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by elements in descending 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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val worstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sorted()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by elements in descending order.

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

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

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val worstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sorted()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by elements in descending order.

sortedBy

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.

Example

class Score(
    val value: Int,
)

class Player(
    val _id: ObjectId,
    val scores: List<Score>,
    val bestScores: List<Score>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedBy { ascending(Score::value) }
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sorted: Sort by the elements themselves (ascending order).

• ArrayValueOperators.sortedDescending: Sort by the elements themselves (descending order).

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.

Example

class Score(
    val value: Int,
)

class Player(
    val _id: ObjectId,
    val scores: List<Score>,
    val bestScores: List<Score>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedBy { ascending(Score::value) }
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sorted: Sort by the elements themselves (ascending order).

• ArrayValueOperators.sortedDescending: Sort by the elements themselves (descending order).

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.

Example

class Score(
    val value: Int,
)

class Player(
    val _id: ObjectId,
    val scores: List<Score>,
    val bestScores: List<Score>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedBy { ascending(Score::value) }
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sorted: Sort by the elements themselves (ascending order).

• ArrayValueOperators.sortedDescending: Sort by the elements themselves (descending order).

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.

Example

class Score(
    val value: Int,
)

class Player(
    val _id: ObjectId,
    val scores: List<Score>,
    val bestScores: List<Score>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedBy { ascending(Score::value) }
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sorted: Sort by the elements themselves (ascending order).

• ArrayValueOperators.sortedDescending: Sort by the elements themselves (descending order).

sortedDescending

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

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

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val bestScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedDescending()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by fields of elements.

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

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

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val bestScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedDescending()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by fields of elements.

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

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

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val bestScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedDescending()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by fields of elements.

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

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

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val bestScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::bestScores set Player::scores
            .sortedDescending()
            .take(5)
    }
}

External resources

• Official documentation

See also

• ArrayValueOperators.sortedBy: Sort by fields of elements.

• ArrayValueOperators.sortedDescending: Sort by fields of elements.

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val firstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::firstScores set Player::scores.take(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val firstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::firstScores set Player::scores.take(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val firstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::firstScores set Player::scores.take(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val firstScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::firstScores set Player::scores.take(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val lastScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::lastScores set Player::scores.takeLast(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val lastScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::lastScores set Player::scores.takeLast(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val lastScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::lastScores set Player::scores.takeLast(3)
    }
}

External resources

• Official documentation

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.

Example

class Player(
    val _id: ObjectId,
    val scores: List<Int>,
    val lastScores: List<Int>,
)

players.updateManyWithPipeline {
    set {
        Player::lastScores set Player::scores.takeLast(3)
    }
}

External resources

• Official documentation

unsafe

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: String): Field<Root, Child>

Refers to a field child of the current field, with no compile-time safety.

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: KProperty1<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: Field<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> Field<Root, *>.unsafe(child: KProperty1<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> Field<Root, *>.unsafe(child: Field<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Type, Child> Field<Root, Type>.unsafe(child: String): Field<Root, Child>

Refers to a field child of the current field, with no compile-time safety.