UpdateQuery¶
interface UpdateQuery<T> : CompoundBsonNode, FieldDsl
DSL for MongoDB operators that are used to update existing values (does not include aggregation operators).
Example¶
This expression type is available on multiple operations, most commonly update:
class User(
val name: String,
val age: Int,
)
collection.update(
filter = {
User::name eq "Bob"
},
update = {
User::age set 18
}
)
Operators¶
On regular fields:
On arrays:
Time management:
If you can't find the operator you're searching for, visit the tracking issue.
External resources¶
See also¶
FilterQuery: Filters
Inheritors¶
Constructors¶
UpdateQuery¶
@LowLevelApi
fun <T> UpdateQuery(context: BsonContext): UpdateQuery<T>
Creates an empty UpdateQuery.
Types¶
PushBuilder¶
interface PushBuilder<V> : BsonNode
DSL builder for advanced $push operations.
PushSortDsl¶
interface PushSortDsl<V : Any> : SortOptionDsl<V>
DSL for sorting elements during a $push operation.
Properties¶
all¶
open val <E> KProperty1<T, Collection<E>>.all: Field<T, E>
The all positional operator: selects all elements of an array.
This operator is used to declare an update that applies to all items of an array.
Example
class User(
val name: String,
val pets: List<Pet>,
)
class Pet(
val name: String,
val age: Int,
)
users.updateMany {
User::pets.all / Pet::age inc 1
}
External resources
context¶
@LowLevelApi
abstract val context: BsonContext
The context used to generate this expression.
field¶
Converts a Kotlin property into a Field.
selected¶
open val <E> KProperty1<T, Collection<E>>.selected: Field<T, E>
The positional operator: update an array item selected in the filter.
When we use any or anyValue in a filter to select an item, we can use this operator to update whichever item was selected.
Do not use this operator in an upsert.
Example
class User(
val name: String,
val pets: List<Pet>,
)
class Pet(
val name: String,
val age: Int,
)
users.updateMany(
filter = {
User::pets.any / Pet::name eq "Bobby"
},
update = {
User::pets.selected / Pet::age inc 1
}
)
This example finds all users who have a pet named "Bobby", and increases its age by 1. Note that if the users have other pets, they are not impacted.
External resources
Functions¶
accept¶
@LowLevelApi
@DangerousMongoApi
abstract override fun accept(node: BsonNode)
Adds a new node as a child of this one.
acceptAll¶
@LowLevelApi
@DangerousMongoApi
fun <N : Node> CompoundNode<N>.acceptAll(nodes: Iterable<N>)
Adds any number of nodes into this one.
addEachToSet¶
open fun <V> Field<T, Collection<V>>.addEachToSet(values: Iterable<V>, type: KType)
infix inline fun <V> Field<T, Collection<V>>.addEachToSet(values: Iterable<V>)
infix inline fun <V> KProperty1<T, Collection<V>>.addEachToSet(values: Iterable<V>)
Adds multiple values at the end of the array, unless they are already present.
Each value in values is treated independently. It if it is already present in the array, nothing happens. If it is absent from the array, it is added at the end.
MongoDB detects equality if the two documents are exactly identical. All the fields must be the same in the same order.
This is a convenience function for calling addToSet multiple times.
Example
class User(
val name: String,
val age: Int,
val tokens: List<String>,
)
collection.updateOne(
filter = {
User::name eq "Bob"
},
update = {
User::tokens addEachToSet listOf("123456789", "789456123")
}
)
This will add "123456789" and "789465123" to the user's tokens only if they aren't already present. If only one of them is present, the other is added.
External resources
addToSet¶
infix inline fun <V> KProperty1<T, Collection<V>>.addToSet(value: V)
Adds value at the end of the array, unless it is already present, in which case it does nothing.
MongoDB detects equality if the two documents are exactly identical. All the fields must be the same in the same order.
Example
class User(
val name: String,
val age: Int,
val tokens: List<String>,
)
collection.updateOne(
filter = {
User::name eq "Bob"
},
update = {
User::tokens addToSet "123456789"
}
)
This will add "123456789" to the user's tokens only if it isn't already present.
External resources
div¶
Refers to child as a nested field of the current field.
Refers to child as a nested field of the current field.
Refers to child as a nested field of the current field.
freeze¶
@LowLevelApi
abstract override fun freeze()
Makes this expression immutable.
get¶
Refers to a specific item in an array, by its index.
Refers to a specific item in a map, by its name.
Refers to a specific item in an array, by its index.
Refers to a specific item in a map, by its name.
inc¶
Increments a field by the specified amount.
amount may be negative, in which case the field is decremented.
If the field doesn't exist (either the document doesn't have it, or the operation is an upsert and a new document is created), the field is created with an initial value of amount.
Use of this operator with a field with a null value will generate an error.
Example
class User(
val name: String,
val age: Int,
)
// It's the new year!
collection.updateMany {
User::age inc 1
}
External resources
max¶
infix inline fun <V : Comparable<V>> KProperty1<T, V?>.max(value: V)
min¶
infix inline fun <V : Comparable<V>> KProperty1<T, V?>.min(value: V)
mul¶
Multiplies a field by the specified amount.
If the field doesn't exist (either the document doesn't have it, or the operation is an upsert and a new document is created), the field is created with an initial value of 0.
Use of this operator with a field with a null value will generate an error.
Example
External resources
plusAssign¶
inline operator fun <V : Number> KProperty1<T, V>.plusAssign(amount: V)
Increments a field by the specified amount.
amount may be negative, in which case the field is decremented.
If the field doesn't exist (either the document doesn't have it, or the operation is an upsert and a new document is created), the field is created with an initial value of amount.
Use of this operator with a field with a null value will generate an error.
Example
class User(
val name: String,
val age: Int,
)
// It's the new year!
collection.updateMany {
User::age += 1
}
External resources
push¶
infix inline fun <V> KProperty1<T, Collection<V>>.push(value: V)
Adds value at the end of the array.
Unlike addToSet, this operator always adds the value, even if it's already present in the array.
Example
class User(
val name: String,
val age: Int,
val scores: List<Int>,
)
collection.updateOne(
filter = {
User::name eq "Bob"
},
update = {
User::scores push 100
}
)
This will add 100 to the user's scores, even if it's already present.
External resources
abstract fun <V> Field<T, Collection<V>>.push(builder: UpdateQuery.PushBuilder<V>.() -> Unit, type: KType)
infix inline fun <V> Field<T, Collection<V>>.push(noinline builder: UpdateQuery.PushBuilder<V>.() -> Unit)
infix inline fun <V> KProperty1<T, Collection<V>>.push(noinline builder: UpdateQuery.PushBuilder<V>.() -> Unit)
Adds values to the end of the array with advanced options.
This method allows using MongoDB's advanced $push operators like $each and $slice.
Example
class User(
val name: String,
val age: Int,
val tokens: List<String>,
)
collection.updateOne(
filter = {
User::name eq "Bob"
},
update = {
User::tokens push {
each("123", "456")
slice(3)
}
}
)
This will add "123" and "456" to the user's tokens and keep only the last 3 elements.
External resources
pushEach¶
infix inline fun <V> KProperty1<T, Collection<V>>.pushEach(values: Iterable<V>)
Adds multiple values at the end of the array.
Unlike addToSet, this operator always adds all values, even if they're already present in the array.
This is a convenience function for calling push multiple times.
Example
class User(
val name: String,
val age: Int,
val scores: List<Int>,
)
collection.updateOne(
filter = {
User::name eq "Bob"
},
update = {
User::scores pushEach listOf(100, 200)
}
)
This will add 100 and 200 to the user's scores, even if they're already present.
External resources
renameTo¶
open infix fun <V> KProperty1<T, V>.renameTo(newName: KProperty1<T, V>)
set¶
Replaces the value of a field with the specified value.
Example
class User(
val name: String?,
val age: Int,
)
collection.filter {
User::name eq "foo"
}.updateMany {
User::age set 18
}
External resources
See also
UpsertQuery.setOnInsert: Only set if a new document is created.
setIf¶
Replaces the value of a field with the specified value, if condition is true.
If condition is false, this operator does nothing.
Example
class User(
val name: String?,
val age: Int,
)
collection.filter {
User::name eq "foo"
}.updateMany {
User::age.setIf(someComplexOperation, 18)
}
External resources
See also
UpsertQuery.setOnInsert: Only set if a new document is created.
setToCurrentDate¶
abstract fun Field<T, Instant?>.setToCurrentDate()
open fun KProperty1<T, Instant?>.setToCurrentDate()
Sets this field to the current date.
If the field does not exist, this operator adds the field to the document.
Example
class User(
val name: String?,
val age: Int,
val modificationDate: Instant,
)
collection.filter {
User::name eq "Bob"
}.updateMany {
User::age set 18
User::modificationDate.setToCurrentDate()
}
External resources
@JvmName(name = "setToCurrentTimestamp")
abstract fun Field<T, Timestamp?>.setToCurrentDate()
@JvmName(name = "setToCurrentTimestamp")
open fun KProperty1<T, Timestamp?>.setToCurrentDate()
Sets this field to the current timestamp.
If the field does not exist, this operator adds the field to the document.
The time Timestamp is internal. Instant should be preferred. For more information, see Timestamp.
Example
class User(
val name: String?,
val age: Int,
val modificationDate: Timestamp,
)
collection.filter {
User::name eq "Bob"
}.updateMany {
User::age set 18
User::modificationDate.setToCurrentDate()
}
External resources
setUnless¶
Replaces the value of a field with the specified value, if condition is false.
If condition is true, this operator does nothing.
Example
class User(
val name: String?,
val age: Int,
)
collection.filter {
User::name eq "foo"
}.updateMany {
User::age.setUnless(someComplexOperation, 18)
}
External resources
See also
UpsertQuery.setOnInsert: Only set if a new document is created.
simplify¶
@LowLevelApi
abstract fun simplify(): BsonNode?
Returns a simplified (but equivalent) expression to the current expression.
timesAssign¶
inline operator fun <V : Number> KProperty1<T, V>.timesAssign(amount: V)
Multiplies a field by the specified amount.
If the field doesn't exist (either the document doesn't have it, or the operation is an upsert and a new document is created), the field is created with an initial value of 0.
Use of this operator with a field with a null value will generate an error.
Example
External resources
toBson¶
@LowLevelApi
open fun toBson(): BsonDocument
Writes the result of simplifying to a new BsonDocument.
toString¶
unsafe¶
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.
Refers to a field child of the current field, without checking that it is a field available on the current object.
Refers to a field child of the current field, without checking that it is a field available on the current object.
Refers to a field child of the current field, without checking that it is a field available on the current object.
Refers to a field child of the current field, with no compile-time safety.
unset¶
writeTo¶
@LowLevelApi
abstract override fun writeTo(writer: BsonFieldWriter)
Writes the result of simplifying this expression into writer.