更新文档

本页内容

概述

示例数据
更新操作
更新单个文档
更新多个文档
自定义更新操作
返回值
附加信息
API 文档

概述

在本指南中，您可以学习如何使用 Kotlin Sync 驱动程序，通过使用updateOne() 和 updateMany() 方法来更新 MongoDB 集合中的文档。

示例数据

本指南中的示例使用来自Atlas 示例数据集的 sample_restaurants.restaurants 集合。要了解如何创建免费的 MongoDB Atlas 集群并加载示例数据集，请参阅 Atlas 入门指南。

本集合中的文档由以下 Kotlin 数据类建模

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

更新操作

您可以使用以下方法在 MongoDB 中更新文档

updateOne()，它更新 第一个匹配搜索条件的文档
updateMany()，用于更新所有符合搜索条件的文档

每个更新方法都需要以下参数

查询过滤器，用于匹配要更新的文档。要了解更多关于查询过滤器的信息，请参阅指定查询指南。
更新文档，用于指定更新操作符，或要执行更新的类型，以及要更新的字段和值。有关更新操作符及其用法的列表，请参阅MongoDB服务器手册中的字段更新操作符指南页面。

更新单个文档

以下示例使用updateOne()方法将文档"Happy Garden"中的name值从"Happy Garden"更新为"Mountain House"。

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

更新多个文档

以下示例使用updateMany()方法更新所有name值为"Starbucks"的文档。更新将address字段重命名为location。

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

自定义更新操作

updateOne() 和 updateMany() 方法可以接受一个参数来配置更新操作。如果您没有指定任何选项，驱动程序将使用默认设置执行更新操作。

以下表格描述了您可以使用来配置 UpdateOptions 实例的设置方法

属性	描述
`upsert()`	指定如果查询过滤器没有匹配的文档，更新操作是否执行更新操作。有关更多信息，请参阅 MongoDB 服务器手册中的 upsert 语句。默认为 `false`
`bypassDocumentValidation()`	指定更新操作是否绕过文档验证。如果您有任何模式验证要求，这允许您更新不符合模式验证要求的文档。有关模式验证的更多信息，请参阅 MongoDB 服务器手册中的模式验证。默认为 `false`。
`collation()`	指定在排序结果时使用哪种语言排序规则。有关更多信息，请参阅 MongoDB 服务器手册中的排序规则。
`arrayFilters()`	提供您指定的过滤器列表，以选择更新操作应用到哪些数组元素。
`hint()`	设置在匹配文档时使用的索引。有关更多信息，请参阅 MongoDB 服务器手册中的 hint 语句。
`let()`	提供参数名称和值的映射，以设置操作的操作变量。值必须是常数或闭包表达式，不引用文档字段。有关更多信息，请参阅 MongoDB 服务器手册中的 let 语句。
`comment()`	设置要附加到操作的注释。有关更多信息，请参阅 MongoDB 服务器手册中有关更新命令字段的指南。

修改更新示例

以下代码使用updateOne()方法匹配字段值为"Sunrise Pizzeria"的文档。然后，它将第一个匹配文档中的borough值设置为"Queens"，并将cuisine值设置为"意大利菜"。

因为设置了upsert选项为true，如果查询过滤器没有匹配到现有文档，驱动程序将插入一个新文档，该文档包含更新文档中指定的字段和值。

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)

返回值

updateOne()和updateMany()方法各自返回一个UpdateResult对象。您可以使用以下方法访问UpdateResult实例的信息

属性	描述
`getMatchedCount()`	返回匹配查询过滤器的文档数量，无论执行了多少更新操作。
`getModifiedCount()`	返回更新操作修改的文档数量。如果更新的文档与原始文档相同，则不包括在此计数中。
`wasAcknowledged()`	如果服务器确认了结果，则返回`true`。
`getUpsertedId()`	如果驱动程序执行了upsert操作，则返回在数据库中upsert的文档的`_id`值。

注意

如果wasAcknowledged()方法返回false，尝试从UpdateResult实例访问其他信息将导致InvalidOperation异常。如果服务器没有确认写入操作，驱动程序无法确定这些值。

附加信息

要查看使用 Kotlin Sync 驱动更新文档的运行代码示例，请参阅将数据写入 MongoDB。

API 文档

要了解更多关于本指南中讨论的任何方法或类型的信息，请参阅以下 API 文档

插入

替换