Docs 主页

/ /

Kotlin Coroutine 驱动程序

Docs 主页

客户端库

Kotlin

Kotlin Coroutine 驱动程序

Docs 主页

客户端库

Kotlin

Kotlin Coroutine 驱动程序

替换文档

Overview

在本指南中，您可以学习；了解如何使用Kotlin驾驶员替换MongoDB集合中的文档。替换操作使用查询过滤匹配集合中的文档，然后用新文档替换该文档。

替换一个文档

replaceOne() 方法会删除匹配文档中的所有现有字段和值（_id字段除外），并插入替换文档中的字段和值。

您可以在MongoCollection实例上调用replaceOne()方法，如下所示：

collection.replaceOne(<query>, <replacementDocument>)

如果多个文档与 replaceOne() 方法中指定的查询筛选条件匹配，则该操作将替换第一个结果。您可以在 ReplaceOptions实例中指定排序，以便在驱动程序执行替换操作之前对匹配的文档应用顺序，如以下代码所示：

val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))

如果替换操作中与查询筛选条件匹配的文档有零个，则 replaceOne() 不会对集合中的文档进行任何更改。请参阅更新或插入（upsert）指南，学习；了解如何在没有匹配的文档时插入新文档，而不是替换文档。

重要

replaceOne() 方法无法对违反集合唯一索引约束的文档进行更改。有关唯一索引的更多信息，请参阅MongoDB Server手册。

替换操作参数

replaceOne() 方法接受以下参数：

Parameter	说明
`filter`	查询筛选条件，用于指定要替换的文档。有关查询筛选条件的更多信息，请参阅MongoDB Server手册。数据类型： BSON
`replacement`	替换文档，指定要插入新文档中的字段和值。如果集合中的文档映射到Kotlin类，则替换文档可以是该类的实例。数据类型： `document: T`
`options`	可选。`ReplaceOptions` 类的实例，用于指定替换操作的配置。默认值为 `null`。数据类型： ReplaceOptions

自定义替换操作

replaceOne() 方法可以选择接受 ReplaceOptions对象作为参数，该对象表示可用于配置替换操作的选项。

ReplaceOptions 类包含以下属性：

属性	说明
`bypassDocumentValidation`	指定替换操作是否绕过文档验证。这使您可以替换不满足模式验证要求的文档（如存在）。有关模式验证的更多信息，请参阅 MongoDB Server 手册。数据类型：布尔
`collation`	指定排序结果时使用的语言集合类型。数据类型：排序规则
`comment`	获取或设置用户提供的操作注释。有关更多信息，请参阅 MongoDB Server 手册。数据类型： String 或 BsonValue
`hint`	获取或设置用于扫描文档的索引。有关更多信息，请参阅 MongoDB Server 手册。数据类型： Bson
`hintString`	获取或设置用于扫描文档的索引。有关更多信息，请参阅 MongoDB Server 手册。数据类型：字符串
`upsert`	指定如果没有文档与查询筛选条件匹配，替换操作是否执行更新或插入操作。有关更多信息，请参阅 MongoDB Server 手册。数据类型：布尔
`sort`	如果查询选择了多个文档，则确定该操作替换哪个文档，因为替换操作会按指定的排序顺序替换第一个文档。数据类型： Bson
`let`	获取或设置 let文档以为操作添加顶级变量。有关更多信息，请参阅MongoDB Server手册。数据类型： Bson

返回值

成功执行后，replaceOne() 方法将返回一个 UpdateResult实例。UpdateResult 类包含以下属性：

属性	说明
`wasAcknowledged`	指示替换操作是否由 MongoDB 确认。数据类型： `boolean`
`getMatchedCount`	与查询筛选器匹配的文档数量，无论是否已有文档被替换。数据类型： `long`
`getModifiedCount`	通过替换操作替换的文档数量。数据类型： `long`
`getUpsertedId`	如果驱动程序执行了更新或插入，则在数据库中更新或插入的文档的 ID。数据类型： BsonValue

异常

如果替换操作失败，驱动程序会引发异常。

示例，如果替换文档中 _id字段的值与原始文档中的值不同，该方法将抛出以下 MongoWriteException：

After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)

如果替换文档包含违反唯一索引规则的更改，该方法会引发 MongoWriteException 错误，并显示类似于以下内容的错误消息：

E11000 duplicate key error collection: ...

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

替换一个示例

一家油漆存储出售五种不同颜色的油漆。以下集合中的文档表示商店库存中的油漆颜色：

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 8 }
{ "_id": 3, "color": "yellow", "qty": 0 }
{ "_id": 4, "color": "green", "qty": 6 }
{ "_id": 5, "color": "pink", "qty": 20 }

以下Kotlin数据类对此数据进行建模：

data class PaintOrder(
    @BsonId val id: Int,
    val color: String,
    val qty: Int
)

油漆存储必须更新库存，用 25 罐橙色油漆替换 20 罐粉色油漆。

要更新库存，请调用 replaceOne() 方法：

val filter = Filters.eq(PaintOrder::color.name, "pink")
val update = PaintOrder(5, "orange", 25)
val result = collection.replaceOne(filter, update)
println("Matched document count: $result.matchedCount")
println("Modified document count: $result.modifiedCount")

  Matched document count: 1
  Modified document count: 1

前面的替换操作创建了以下文档：

 { "_id": 5, "color": "orange", "qty": 25 }

高级替换一个示例

在以下示例中，replaceOne() 方法将 Atlas sample_mflix.movies 数据集的 movies 集合中查询筛选条件的第一个匹配项替换为替换文档。该操作会删除原始文档中除 _id 之外的所有字段，并插入替换文档中的字段。以下 Movie 数据类对此集合中的文档进行建模，以便与Kotlin驱动程序一起使用：

data class Movie(
    val title: String,
    val year: Int,
    val genres: List<String>,
    val rated: String,
    val plot: String,
    val runtime: Int,
    val imdb: IMDB,
    val fullplot: String? = "No full plot",
){
    data class IMDB(
        val rating: Double
    )
}

提示

构建器方法和数据类属性

通过将可选的Kotlin驱动程序扩展依赖项添加到应用程序，您可以直接将构建者类中的方法与数据类属性一起使用。要学习；了解更多信息和查看示例，请参阅《使用构建器与数据类》指南。

在replaceOne()操作运行之前，原始文档包含多个描述电影的字段。操作运行后，生成的文档仅包含替换文档指定的字段（ title和fullplot ）以及_id字段。

以下示例使用以下对象和方法：

传递给 replaceOne() 方法的查询筛选器。eq 筛选器仅会匹配标题与 "Music of the Heart" 文本完全匹配的电影。
替换文档，其中包含用于替换匹配文档（如果存在）的文档。
一个将 upsert 选项设为 true 的 ReplaceOptions 对象。此选项指定，如果查询筛选条件与任何文档都不匹配，则该方法将插入替换文档中包含的数据。

注意

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

import com.mongodb.MongoException
import com.mongodb.client.model.Filters
import com.mongodb.client.model.ReplaceOptions
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
data class Movie(val title: String, val fullplot: String)
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")
    try {
        val query = Filters.eq("title", "Music of the Heart")
        val replaceDocument = Movie( "50 Violins", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music")
        val options = ReplaceOptions().upsert(true)
        val result = collection.replaceOne(query, replaceDocument, 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 replace due to an error: $e")
    }
    mongoClient.close()
}

前面的示例返回以下输出：

Modified document count: 1
Upserted id: null

如果前面的示例执行了更新或插入（upsert），则代码将返回以下输出：

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

如果查询被替换的文档，查询将返回以下输出：

Movie(title=50 Violins, fullplot= A dramatization of the true story of Roberta Guaspari
who co-founded the Opus 118 Harlem School of Music)