UpdateOperations

interface UpdateOperations<Document : Any> : BaseOperations

Interface grouping MongoDB operations allowing to update existing information.

Inheritors

• MongoCollection

Types

UpdateResult

interface UpdateResult

The return value of updateMany and updateOne.

UpsertResult

interface UpsertResult : UpdateOperations.UpdateResult

The return value of upsertOne.

Properties

context

@LowLevelApi



abstract val context: BsonContext

Functions

bulkWrite

abstract fun bulkWrite(
    options: BulkWriteOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    operations: BulkWrite<Document>.() -> Unit
)

Performs multiple update operations in a single request.

Example

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

collection.bulkWrite {
    upsertOne(
        filter = {
            User::name eq "Patrick"
        },
        update = {
            User::age set 15
        }
    )

    updateMany {
        User::age inc 1
    }
}

To see which operations are available and their respective syntax, see BulkWrite.

Using filtered writes

We can group operations by the filter they apply on:

collection.bulkWrite {
    filtered(filter = { User::isAlive eq true }) {
        updateOne(…)
        updateOne(…)
        updateMany(…)
    }

    updateOne(…)
}

To learn more, see filtered.

Using filtered collections

If we want all operations to use the same filter, we can declare it before calling the operation:

collection.filter {
    User::isAlive eq true
}.bulkWrite {
    updateOne(…)
    updateOne(…)
    updateMany(…)
}

External resources

• Official documentation

findOneAndUpdate

abstract fun findOneAndUpdate(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateQuery<Document>.() -> Unit
): Document?

Updates one element that matches filter according to update and returns it, atomically.

Example

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

collection.findOneAndUpdate(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.findOneAndUpdate {
    User::age set 15
}

To learn more, see filter.

External resources

• Official documentation

Parameters

• filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

• UpdateOperations.updateMany: Update more than one document.

• UpdateOperations.updateOne: Do not return the value.

replaceOne

abstract fun replaceOne(
    options: ReplaceOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    document: Document
)

Replaces a document that matches filter by document.

If multiple documents match filter, only the first one found is updated.

Data races

This operator is often used by first reading a document, processing it, and replacing it. This can be dangerous in distributed systems because another replica of the server could have updated the document between the read and the write.

If this is a concern, it is recommended to use updateOne with explicit operators on the data that has changed, allowing to do the modification in a single operation. Doing the update that way, MongoDB is responsible for ensuring the read and the write are atomic.

Example

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

collection.replaceOne(
    filter = {
        User::name eq "Patrick"
    },
    document = User("Bob", 15)
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.replaceOne(User("Patrick", 15))

To learn more, see filter.

External resources

• Official documentation

Parameters

• filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

• UpdateOperations.updateOne: Updates an existing document.

• UpdateOperations.updateMany: Update more than one document.

• UpdateOperations.repsertOne: Replaces a document, or inserts it if it doesn't exist.

• UpdateOperations.findOneAndUpdate: Also returns the result of the update.

repsertOne

abstract fun repsertOne(
    options: ReplaceOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    document: Document
)

Replaces a document that matches filter by document.

If multiple documents match filter, only the first one found is updated.

If no documents match filter, document is inserted.

Data races

This operator is often used by first reading a document, processing it, and replacing it. This can be dangerous in distributed systems because another replica of the server could have updated the document between the read and the write.

If this is a concern, it is recommended to use updateOne with explicit operators on the data that has changed, allowing to do the modification in a single operation. Doing the update that way, MongoDB is responsible for ensuring the read and the write are atomic.

Example

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

collection.repsertOne(
    filter = {
        User::name eq "Patrick"
    },
    document = User("Bob", 15)
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.repsertOne(User("Patrick", 15))

To learn more, see filter.

External resources

• Official documentation

Parameters

• filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

• UpdateOperations.updateOne: Updates an existing document.

• UpdateOperations.replaceOne: Replaces an existing document.

• UpdateOperations.findOneAndUpdate: Also returns the result of the update.

updateMany

@IgnorableReturnValue
abstract fun updateMany(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateQuery<Document>.() -> Unit
): UpdateOperations.UpdateResult

Updates all documents that match filter according to update.

Example

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

collection.updateMany(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.updateMany {
    User::age set 15
}

To learn more, see filter.

External resources

• Official documentation

Parameters

• filter: Optional filter to select which documents are updated. If no filter is specified, all documents are updated.

See also

• UpdateOperations.updateOne

updateOne

@IgnorableReturnValue
abstract fun updateOne(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateQuery<Document>.() -> Unit
): UpdateOperations.UpdateResult

Updates a single document that matches filter according to update.

If multiple documents match filter, only the first one found is updated.

Example

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

collection.updateOne(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.updateOne {
    User::age set 15
}

To learn more, see filter.

External resources

• Official documentation

Parameters

• filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

• UpdateOperations.updateMany: Update more than one document.

• UpdateOperations.findOneAndUpdate: Also returns the result of the update.

upsertOne

@IgnorableReturnValue
abstract fun upsertOne(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpsertQuery<Document>.() -> Unit
): UpdateOperations.UpsertResult

Updates a single document that matches filter according to update.

If multiple documents match filter, only the first one is updated.

If no documents match filter, a new one is created.

Example

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

collection.upsertOne(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

If a document exists that has the name of "Patrick", its age is set to 15. If none exists, a document with name "Patrick" and age 15 is created.

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.upsertOne {
    User::age set 15
}

To learn more, see filter.

External resources

• The update operation

• The behavior of upsert functions

See also

• UpdateOperations.updateOne