更新文档

可以在 MongoCollection 对象上使用 updateOne() 方法来更新单个文档。该方法接受与要更新的文档匹配的筛选器，以及指示驱动程序如何更改匹配文档的更新语句。updateOne() 方法只更新与筛选器匹配的第一个文档。

要使用 updateOne() 方法执行更新，必须传递查询筛选器和更新文档。查询筛选器指定了对哪个文档执行更新的标准，而更新文档则提供了对其进行更改的说明。

您可以选择向 updateOne() 方法传递 UpdateOptions 的实例，以指定该方法的行为。例如，如果将 UpdateOptions 对象的 upsert 字段设置为 true，那么如果没有与查询过滤器匹配的文档，操作就会从查询和更新文档中的字段插入新文档。有关更多信息，请参阅本页底部的 UpdateOptions API 文档链接。

执行成功后，updateOne() 方法会返回一个 UpdateResult 实例。您可以调用 getModifiedCount() 方法来检索经过修改的文档数等信息，或者调用 getUpsertedId() 方法（如果您在 UpdateOptions 实例中指定了 upsert(true)）来检索 _id 字段的值。

如果更新操作失败，驱动程序会引发异常。例如，如果您尝试在更新文档中为不可变字段 _id 设置值，该方法就会抛出 MongoWriteException，其中包含消息：

Performing an update on the path '_id' would modify the immutable field '_id'

如果您的更新文档包含违反唯一索引规则的更改，该方法会抛出一个 MongoWriteException 以及一条错误消息，该消息应如下所示：

E11000 duplicate key error collection: ...

有关特定条件下引发的异常类型的更多信息，请参阅本页底部链接的updateOne() API 文档。

例子

在此示例中，我们使用Filters构建器来query collection中是否有标题为“Cool Runnings 2”的电影。

接下来，我们对sample_mflix数据库的moviescollection中查询的第一个匹配项执行以下更新：

将 runtime 的值设置为 99
仅当 genres 数组中不存在 Sports 时，才可将其添加到该数组中
将lastUpdated的值设置为当前时间

我们使用Updates构建器（一个包含静态辅助方法的工厂类）来构造更新文档。虽然可以不使用构建器而直接传递更新文档，但构建器提供了类型检查和简化的语法。有关更多信息，请参阅有关更新构建指南的指南。

注意

此示例使用连接 URI 连接到MongoDB实例。要学习；了解有关连接到MongoDB实例的更多信息，请参阅连接指南。

import com.mongodb.MongoException
import com.mongodb.client.model.Filters
import com.mongodb.client.model.UpdateOptions
import com.mongodb.client.model.Updates
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
import java.time.LocalDateTime
data class Movie(
    val title: String,
    val runtime: Int,
    val genres: List<String>,
    val lastUpdated: LocalDateTime
)
fun main() = runBlocking {
    // Replace the uri string with your MongoDB deployment's connection string
    val uri = "<connection string uri>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Movie>("movies")
    val query = Filters.eq(Movie::title.name, "Cool Runnings 2")
    val updates = Updates.combine(
        Updates.set(Movie::runtime.name, 99),
        Updates.addToSet(Movie::genres.name, "Sports"),
        Updates.currentDate(Movie::lastUpdated.name)
    )
    val options = UpdateOptions().upsert(true)
    try {
        val result = collection.updateOne(query, updates, options)
        println("Modified document count: " + result.modifiedCount)
        println("Upserted id: " + result.upsertedId) // only contains a non-null value when an upsert is performed
    } catch (e: MongoException) {
        System.err.println("Unable to update due to an error: $e")
    }
    mongoClient.close()
}

运行该示例后，您应该会看到如下所示的输出：

Modified document count: 1
Upserted id: null

或者，如果示例导致更新或插入：

Modified document count: 0
Upserted id: BsonObjectId{value=...}

如果查询更新后的文档，它应如下所示：

Movie(title=Cool Runnings 2, runtime=99, genres=[ ... Sports], lastUpdated= ... )

有关此页面上提及的类和方法的更多信息，请参阅以下 API 文档：