/ /

替换文档

Overview

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

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

样本数据

restaurantssample_restaurants本指南中的示例使用Atlas示例数据集的数据库中的集合。要从Scala应用程序访问权限此集合，请创建一个连接到Atlas 集群的MongoClient对象，并将以下值分配给 database 和 collection 变量：

val database: MongoDatabase = mongoClient.getDatabase("sample_restaurants")
val collection: MongoCollection[Document] = database.getCollection("restaurants")

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

替换操作

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

所需参数

您必须将以下参数传递给replaceOne()方法：

查询过滤，用于匹配要更新的文档。如需学习；了解有关查询筛选器的更多信息，请参阅“指定查询”指南。
替换文档，指定要替换现有字段和值的字段和值。

替换一个文档

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

val filter = equal("name", "Primola Restaurant")
val replacement = Document(
  "name" -> "Frutti Di Mare",
  "borough" -> "Queens",
  "cuisine" -> "Seafood",
  "owner" -> "Sal Thomas"
)
val observable: Observable[UpdateResult] = collection.replaceOne(filter, replacement)
observable.subscribe(new Observer[UpdateResult] {
  override def onNext(result: UpdateResult): Unit = println(s"Replaced document count: ${result.getModifiedCount}")
  override def onError(e: Throwable): Unit = println(s"Failed: ${e.getMessage}")
  override def onComplete(): Unit = println("Completed")
})

Replaced document count: 1
Completed

重要

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

自定义替换操作

replaceOne() 方法可以选择接受 ReplaceOptions数据类型的参数。ReplaceOptions 类包含可用于配置替换选项的 setter 方法。如果不指定任何选项，驱动程序将使用默认设置执行替换操作。

下表描述了 ReplaceOptions 类中的 setter 方法：

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

以下代码将 upsert 选项设置为 true，这会指示驱动程序在查询筛选条件与任何现有文档都不匹配时插入具有替换文档中指定的字段和值的新文档：

val options = ReplaceOptions().upsert(true)
val observable: Observable[UpdateResult] = collection.replaceOne(filter, replacement, options)
observable.subscribe(new Observer[UpdateResult] {
  override def onNext(result: UpdateResult): Unit = println(s"Replaced document count: ${result.getModifiedCount}")
  override def onError(e: Throwable): Unit = println(s"Failed: ${e.getMessage}")
  override def onComplete(): Unit = println("Completed")
})

Replaced document count: 1
Completed

返回值

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

方法	说明
`getMatchedCount()`	返回与查询过滤匹配的文档数。
`getModifiedCount()`	返回更新操作修改的文档数。如果更新后的文档与原始文档相同，则不计入此计数。
`wasAcknowledged()`	如果服务器确认结果，则返回 `true`。
`getUpsertedId()`	返回驾驶员更新或插入到数据库中的文档的 `_id` 值（如果有）。