/ /

替换文档

Overview

在本指南中，您可以学习如何使用Java Reactive Streams驱动程序通过执行替换操作来替换MongoDB集合中的文档。

替换操作使用您指定的新字段和值替换MongoDB集合中的一个文档。您可以使用replaceOne()方法执行替换操作。

样本数据

本指南中的示例使用来自 Atlas 示例数据集的 sample_restaurants.restaurants 集合。

要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅入门教程。

重要

项目 Reactor 库

本指南使用 Project Reactor 库来使用Java Reactive Streams驱动程序方法返回的 Publisher 实例。要学习；了解有关 Project Reactor 库及其使用方法的更多信息，请参阅 Reactor 文档中的入门。要进一步学习；了解如何使用本指南中的 Project Reactor 库方法，请参阅“将数据写入MongoDB”指南。

替换操作

您可以在MongoCollection实例上使用replaceOne()方法执行替换操作。此方法会从符合搜索条件的第一个文档中删除除_id字段之外的所有字段，然后将您指定的字段和值添加到空文档中。

所需参数

replaceOne() 方法需要使用以下参数：

查询过滤文档，用于确定要替换的文档。有关查询筛选器的更多信息，请参阅“指定查询”指南。
替换文档，指定要插入新文档中的字段和值。

替换示例

要替换MongoDB集合中的单个文档，请调用 replaceOne() 方法并将查询筛选条件文档和替换文档作为参数传递。然后，将 replaceOne() 结果传递给 Mono 中的静态 Mono.from() 方法。 Mono 是 Project Reactor 库中的一个类。在Java Reactive Streams 中，驱动程序方法会返回 Publisher 冷实例，这意味着除非您订阅返回的 Publisher，否则不会发生相应的操作。本指南使用项目 Reactor 库来使用它们。要学习；了解有关Mono 的更多信息，请参阅项目 Reactor 文档中的 Mono。

以下示例使用replaceOne()方法将name字段值为"Pizza Town"的文档的字段和值替换。 replaceOne()方法将原始文档替换为name字段值为"Mongo's Pizza"且cuisine字段值为"Pizza"的文档。

 Publisher<UpdateResult> replacePublisher = restaurants.replaceOne(
         eq("name", "Pizza Town"),
         new Document().append("name", "Mongo's Pizza")
                 .append("cuisine", "Pizza"));
 Mono.from(replacePublisher).block();

修改替换行为

您可以选择通过调用选项方法来修改replaceOne()方法的行为。 ReplaceOptions类提供了修改replaceOne()方法行为的方法。要使用ReplaceOptions类，请构造该类的新实例，然后调用其一个或多个方法来修改替换操作。您可以将这些方法调用链接在一起。要修改替换操作的行为，请将类实例和链式方法调用作为最后一个参数传递给replaceOne()方法。

您可以使用ReplaceOptions类中的以下方法来修改replaceOne()方法。

方法	说明
`bypassDocumentValidation(Boolean bypass)`	指定替换操作是否绕过文档验证。这样，您就可以更新不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅MongoDB Server手册中的模式验证。
`collation(Collation collation)`	指定对结果进行排序时要使用的语言排序规则类型。有关更多信息，请参阅 MongoDB Server 手册中的排序规则。
`comment(BsonValue comment)`	为操作附加 `BsonValue` 注释。有关更多信息，请参阅MongoDB Server手册中的插入命令字段指南。
`comment(String comment)`	为操作附加 `String` 注释。有关更多信息，请参阅MongoDB Server手册中的插入命令字段指南。
`hint(Bson hint)`	将操作的索引设置为 `Bson` 值。有关更多信息，请参阅MongoDB Server手册中的提示声明。
`hintString(String hint)`	将操作的索引设置为 `String` 值。有关更多信息，请参阅MongoDB Server手册中的提示声明。
`let(Bson variables)`	指定参数名称和值的映射。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。
`sort(Bson sort)`	设置要应用操作的排序条件。如果多个文档与您传递给 `replaceOne()` 方法的查询过滤匹配，则该操作将替换第一个结果。您可以设立此选项以对匹配的文档应用顺序，以便更好地控制替换哪个文档。
`upsert(Boolean upsert)`	指定在没有文档与查询过滤匹配的情况下，替换操作是否执行更新更新或插入（upsert）操作。有关更多信息，请参阅MongoDB Server手册中的更新或插入（upsert）声明。

修改替换示例

以下代码使用 replaceOne() 方法替换 restaurants集合中的文档。它还设置 upsert(true) 选项，以便驱动程序在查询筛选条件与任何现有文档都不匹配时插入新文档。

Publisher<UpdateResult> replacePublisher = restaurants.replaceOne(
        eq("name", "Food Town"),
        new Document().append("name", "Food World")
                .append("cuisine", "Mixed"),
        new ReplaceOptions().upsert(true));
Mono.from(replacePublisher).block();

返回值

replaceOne()方法返回一个UpdateResult对象。使用UpdateResult类型中的以下方法访问权限相应信息：

属性	说明
`getMatchedCount()`	与查询过滤匹配的文档数量，无论有多少被替换。
`getModifiedCount()`	替换操作修改的文档数。如果替换的文档与原始文档相同，则不计入此计数。
`getUpsertedId()`	如果驱动程序执行了更新或插入（upsert），则为插入到数据库中的文档的ID。如果未插入文档，则此值为 `null`。
`wasAcknowledged()`	确认替换。