UpsertQuery

interface UpsertQuery<T> : UpdateQuery<T> 

DSL for MongoDB operators that are used to update existing values, creating new documents if none exist (does not include aggregation operators).

This interface is a variant of UpdateQuery used in upsert operations. See UpdateQuery for more information.

If you can't find the operator you're searching for, visit the tracking issue.

Constructors

UpsertQuery

@LowLevelApi



fun <T> UpsertQuery(context: BsonContext): UpsertQuery<T>

Creates an empty UpsertQuery.

Properties

all

open val <E> Field<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

• Official documentation

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

• Official documentation

context

@LowLevelApi



abstract val context: BsonContext

The context used to generate this expression.

field

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

Converts a Kotlin property into a Field.

selected

open val <E> Field<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

• Official documentation

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

• Official documentation

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.

addToSet

abstract infix fun <V> Field<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

• Official documentation

open infix 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

• Official documentation

open infix fun <V> Field<T, Collection<V>>.addToSet(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 addToSet 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

• Official documentation

open infix fun <V> KProperty1<T, Collection<V>>.addToSet(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 addToSet 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

• Official documentation

div

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.

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

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

open operator fun <Root, Type, Child> Field<Root, Type>.div(child: Field<Type, Child>): Field<Root, Child>

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

freeze

@LowLevelApi



abstract override fun freeze()

Makes this expression immutable.

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.

inc

abstract infix fun <V : Number> Field<T, V>.inc(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 inc 1
}

External resources

• Official documentation

open infix fun <V : Number> KProperty1<T, V>.inc(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 inc 1
}

External resources

• Official documentation

max

abstract infix fun <V : Comparable<V>> Field<T, V?>.max(value: V)

Updates the value of a field to the specified value only if the specified value is greater than the current value of the field.

If the field doesn't exist, the field is set to the specified value.

Example

class User(
    val name: String,
    val score: Int,
)

collection.updateMany {
    User::score max 100
}

External resources

• Official documentation

open infix fun <V : Comparable<V>> KProperty1<T, V?>.max(value: V)

Updates the value of a field to the specified value only if the specified value is greater than the current value of the field.

If the field doesn't exist, the field is set to the specified value.

Example

class User(
    val name: String,
    val score: Int,
)

collection.updateMany {
    User::score max 100
}

External resources

• Official documentation

min

abstract infix fun <V : Comparable<V>> Field<T, V?>.min(value: V)

Updates the value of a field to the specified value only if the specified value is less than the current value of the field.

If the field doesn't exist, the field is set to the specified value.

Example

class User(
    val name: String,
    val score: Int,
)

collection.updateMany {
    User::score min 10
}

External resources

• Official documentation

open infix fun <V : Comparable<V>> KProperty1<T, V?>.min(value: V)

Updates the value of a field to the specified value only if the specified value is less than the current value of the field.

If the field doesn't exist, the field is set to the specified value.

Example

class User(
    val name: String,
    val score: Int,
)

collection.updateMany {
    User::score min 10
}

External resources

• Official documentation

mul

abstract infix fun <V : Number> Field<T, V>.mul(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

class User(
    val name: String,
    val price: Double,
)

collection.updateMany {
    User::price mul 2.0
}

External resources

• Official documentation

open infix fun <V : Number> KProperty1<T, V>.mul(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

class User(
    val name: String,
    val price: Double,
)

collection.updateMany {
    User::price mul 2.0
}

External resources

• Official documentation

plusAssign

open operator fun <V : Number> Field<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

• Official documentation

open 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

• Official documentation

renameTo

abstract infix fun <V> Field<T, V>.renameTo(newName: Field<T, V>)

Renames a field.

Example

class User(
    val name: String,
    val age: Int,
    val ageOld: Int,
)

collection.updateMany {
    User::ageOld renameTo User::age
}

External resources

• Official documentation

open infix fun <V> KProperty1<T, V>.renameTo(newName: Field<T, V>)

Renames a field.

Example

class User(
    val name: String,
    val age: Int,
    val ageOld: Int,
)

collection.updateMany {
    User::ageOld renameTo User::age
}

External resources

• Official documentation

open infix fun <V> Field<T, V>.renameTo(newName: KProperty1<T, V>)

Renames a field.

Example

class User(
    val name: String,
    val age: Int,
    val ageOld: Int,
)

collection.updateMany {
    User::ageOld renameTo User::age
}

External resources

• Official documentation

open infix fun <V> KProperty1<T, V>.renameTo(newName: KProperty1<T, V>)

Renames a field.

Example

class User(
    val name: String,
    val age: Int,
    val ageOld: Int,
)

collection.updateMany {
    User::ageOld renameTo User::age
}

External resources

• Official documentation

set

abstract infix fun <V> Field<T, V>.set(value: V)

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

• Official documentation

See also

• UpsertQuery.setOnInsert: Only set if a new document is created.

open infix fun <V> KProperty1<T, V>.set(value: V)

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

• Official documentation

See also

• UpsertQuery.setOnInsert: Only set if a new document is created.

setIf

open fun <V> Field<T, V>.setIf(condition: Boolean, value: V)

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

• Official documentation

See also

• UpsertQuery.setOnInsert: Only set if a new document is created.

open fun <V> KProperty1<T, V>.setIf(condition: Boolean, value: V)

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

• Official documentation

See also

• UpsertQuery.setOnInsert: Only set if a new document is created.

setOnInsert

abstract infix fun <V> Field<T, V>.setOnInsert(value: V)

If an upsert operation results in an insert of a document, then this operator assigns the specified value to the field. If the update operation does not result in an insert, this operator does nothing.

Example

class User(
    val name: String?,
    val age: Int,
)

collection.filter {
    User::name eq "foo"
}.upsertOne {
    User::age setOnInsert 18
}

External resources

• Official documentation

See also

• UpsertQuery.set: Always set the value.

open infix fun <V> KProperty1<T, V>.setOnInsert(value: V)

If an upsert operation results in an insert of a document, then this operator assigns the specified value to the field. If the update operation does not result in an insert, this operator does nothing.

Example

class User(
    val name: String?,
    val age: Int,
)

collection.filter {
    User::name eq "foo"
}.upsertOne {
    User::age setOnInsert 18
}

External resources

• Official documentation

See also

• UpsertQuery.set: Always set the value.

setToCurrentDate

abstract fun Field<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

• Official documentation

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

• Official documentation

@JvmName
(name = "setToCurrentTimestamp")abstract fun Field<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

• Official documentation

@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

• Official documentation

setUnless

open fun <V> Field<T, V>.setUnless(condition: Boolean, value: V)

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

• Official documentation

See also

• UpsertQuery.setOnInsert: Only set if a new document is created.

open fun <V> KProperty1<T, V>.setUnless(condition: Boolean, value: V)

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

• Official documentation

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.

toBson

@LowLevelApi



open fun toBson(): Bson

Writes the result of simplifying to a new BSON document.

toString

abstract override fun toString(): String

JSON representation of this expression.

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.

unset

abstract fun <V> Field<T, V>.unset()

Deletes a field.

Example

class User(
    val name: String,
    val age: Int,
    val alive: Boolean,
)

collection.filter {
    User::name eq "Luke Skywalker"
}.updateOne {
    User::age.unset()
    User::alive set false
}

External resources

• Official documentation

open fun <V> KProperty1<T, V>.unset()

Deletes a field.

Example

class User(
    val name: String,
    val age: Int,
    val alive: Boolean,
)

collection.filter {
    User::name eq "Luke Skywalker"
}.updateOne {
    User::age.unset()
    User::alive set false
}

External resources

• Official documentation

writeTo

@LowLevelApi



abstract override fun writeTo(writer: BsonFieldWriter)

Writes the result of simplifying this expression into writer.