/ /

Update Documents

Overview

In this guide, you can learn how to use the Kotlin Sync driver to update documents in a MongoDB collection by using the updateOne() and updateMany() methods.

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB deployment and load the sample datasets, see the MongoDB Get Started guide.

The documents in this collection are modeled by the following Kotlin data class:

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val address: Document
)

Update Operations

You can update documents in MongoDB by using the following methods:

updateOne(), which updates the first document that matches the search criteria
updateMany(), which updates all documents that match the search criteria

Each update method requires the following parameters:

Query filter, which matches which documents to update. To learn more about query filters, see the Specify a Query guide.
Update document, which specifies the update operator, or the kind of update to perform, and the fields and values to be updated. For a list of update operators and their usages, see the Field Update Operators guide page in the MongoDB Server manual.

Update One Document

The following example uses the updateOne() method to update the name value of a document from "Happy Garden" to "Mountain House":

val filter = eq(Restaurant::name.name, "Happy Garden")
val update = set(Restaurant::name.name, "Mountain House")
val result = collection.updateOne(filter, update)

Update Many Documents

The following example uses the updateMany() method to update all documents in which the name value is "Starbucks". The update renames the address field to location.

val filter = eq(Restaurant::name.name, "Starbucks")
val update = rename(Restaurant::address.name, "location")
val result = collection.updateMany(filter, update)

Customize the Update Operation

The updateOne() and updateMany() methods optionally accept a parameter that sets options to configure the update operation. If you don't specify any options, the driver performs update operations with default settings.

The following table describes the setter methods that you can use to configure an UpdateOptions instance:

Property	Description
`upsert()`	Specifies whether the update operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Defaults to `false`
`sort(Bson sort)`	Sets the sort criteria to apply to the operation. If multiple documents match the query filter that you pass to the `updateOne()` method, the operation updates the first result. You can set this option to apply an order to matched documents to have more control over which document is updated.
`bypassDocumentValidation()`	Specifies whether the update operation bypasses document validation. This lets you update documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`collation()`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`arrayFilters()`	Provides a list of filters that you specify to select which array elements the update applies to.
`hint()`	Sets the index to use when matching documents. For more information, see the hint statement in the MongoDB Server manual.
`let()`	Provides a map of parameter names and values to set top-level variables for the operation. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`comment()`	Sets a comment to attach to the operation. For more information, see the update command fields guide in the MongoDB Server manual for more information.

Upsert Documents Example

The following code uses the updateOne() method to match documents in which the name field value is "Sunrise Pizzeria". It then sets the borough value in the first matching document to "Queens" and the cuisine value to "Italian".

Because the upsert option is set to true, the driver inserts a new document that has the fields and values specified in the update document if the query filter doesn't match any existing documents.

val opts = UpdateOptions().upsert(true)
val filter = eq(Restaurant::name.name, "Sunrise Pizzeria")
val update = combine(
    set(Restaurant::borough.name, "Queens"),
    set(Restaurant::cuisine.name, "Italian")
)
collection.updateOne(filter, update, opts)

Return Value

The updateOne() and updateMany() methods each return an UpdateResult object. You can use the following methods to access information from an UpdateResult instance:

Property	Description
`getMatchedCount()`	Returns the number of documents that matched the query filter, regardless of how many updates were performed.
`getModifiedCount()`	Returns the number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count.
`wasAcknowledged()`	Returns `true` if the server acknowledged the result.
`getUpsertedId()`	Returns the `_id` value of the document that was upserted in the database, if the driver performed an upsert.

Note

If the wasAcknowledged() method returns false, trying to access other information from the UpdateResult instance results in an InvalidOperation exception. The driver cannot determine these values if the server does not acknowledge the write operation.

Additional Information

To view runnable code examples that demonstrate how to update documents by using the Kotlin Sync driver, see Insert Documents.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Access Data from a Cursor

Replace Documents