替换文档

在本页

概述

示例数据
替换操作
必需参数
替换单个文档
自定义替换操作
返回值
其他信息
API 文档

概述

在本指南中，您可以学习如何使用Kotlin Sync驱动程序在MongoDB集合中对文档执行 替换操作。替换操作会删除指定文档中除了_id 字段之外的所有字段和值，并添加您指定的新的字段和值。此操作与更新操作不同，更新操作只更改一个或多个文档中指定的字段。

要了解更多关于更新操作的信息，请参阅更新文档指南。

示例数据

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

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

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val owner: String?,
)

替换操作

您可以使用MongoDB中的replaceOne()方法执行替换操作。此方法会删除与查询过滤器匹配的第一个文档的所有字段（除了_id字段），然后向空文档添加您指定的字段和值。

必需参数

您必须向replaceOne()方法传递以下参数

查询过滤器，用于匹配要更新的文档。有关查询过滤器的更多信息，请参阅指定查询指南。
替换文档，用于指定您想要用现有字段和值替换的字段和值。

替换一个文档

以下示例使用replaceOne()方法替换具有name字段值为"Primola Restaurant"的文档的字段和值。

val filter = Filters.eq(Restaurant::name.name, "Primola Restaurant")
val replacement = Restaurant(
    "Frutti Di Mare",
    "Queens",
    "Seafood",
    owner = "Sal Thomas"
)
val result = collection.replaceOne(filter, replacement)

重要

_id字段的值是不可变的。如果您的替换文档指定了_id字段的值，则它必须与现有文档的_id值相同，否则驱动程序会引发WriteError。

自定义替换操作

方法 replaceOne() 可选地接受一个参数，用于设置配置替换操作的选项。如果您未指定任何选项，驱动程序将使用默认设置执行替换操作。

以下表格描述了您可以用于配置 ReplaceOptions 实例的设置方法

属性	描述
`upsert()`	指定在查询过滤器没有匹配到任何文档时，替换操作是否执行 upsert 操作。有关更多信息，请参阅 MongoDB 服务器手册中的upsert 行为。默认值为 `false`
`bypassDocumentValidation()`	指定更新操作是否绕过文档验证。这允许您更新不满足模式验证要求（如果存在）的文档。有关模式验证的更多信息，请参阅 MongoDB 服务器手册中的模式验证。默认值为 `false`。
`collation()`	指定在排序结果时使用的语言排序方式。有关更多信息，请参阅 MongoDB 服务器手册中的排序。
`hint()`	设置用于匹配文档的索引。有关更多信息，请参阅 MongoDB 服务器手册中的提示语句。
`let()`	提供参数名称和值的映射，用于设置操作的上层变量。值必须是常量或封闭表达式，不引用文档字段。
`comment()`	设置要附加到操作的注释。

以下代码将 upsert 选项设置为 true，指示驱动程序在查询过滤器不匹配任何现有文档时插入一个新文档，该文档包含替换文档中指定的字段和值

val opts = ReplaceOptions().upsert(true)
val result = collection.replaceOne(filter, replacement, opts)

返回值

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

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

概述

示例数据

替换操作

必需参数

替换一个文档

重要

自定义替换操作

返回值

更多信息

API 文档