替换文档
概述
在本指南中，您可以了解如何使用 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?, )
替换操作
您可以使用replaceOne()方法在 MongoDB 中执行替换操作。此方法会从与查询筛选器匹配的第一个文档中删除除_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实例的 setter 方法：
属性 | 说明 |
|---|---|
upsert() | Specifies whether the replace operation performs an upsert operation if no
documents match the query filter. For more information, see upsert
behavior
in the MongoDB Server manual. Defaults to false |
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. |
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. |
comment() | Sets a comment to attach to the operation. |
以下代码将upsert选项设置为true ，这会指示驱动程序在查询筛选器与任何现有文档都不匹配时插入具有替换文档中指定的字段和值的新文档：
val opts = ReplaceOptions().upsert(true) val result = collection.replaceOne(filter, replacement, opts)
返回值
replaceOne()方法返回一个UpdateResult对象。您可以使用以下方法访问UpdateResult实例中的信息：
属性 | 说明 |
|---|---|
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. |
更多信息
要查看演示如何替换文档的可运行代码示例，请参阅将数据写入 MongoDB。
API 文档
要进一步了解本指南所讨论的任何方法或类型，请参阅以下 API 文档：