/ /

/ /

替换文档

Overview

在本指南中，您可以了解如何使用 PyMongo 对 MongoDB 集合中的文档执行替换操作。替换操作的执行方式与更新操作不同。更新操作仅修改目标文档中的指定字段。替换操作会删除目标文档中的所有字段，然后替换为新字段。

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

样本数据

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

替换操作

您可以使用replace_one()方法在 MongoDB 中执行替换操作。此方法会从匹配Atlas Search条件的第一个文档中删除除 _id 字段之外的所有字段。然后，它将您指定的字段和值插入到文档中。

所需参数

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

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

replaceOne

以下示例使用replace_one()方法替换name字段值为"Pizza Town"的文档的字段和值：

restaurants = database["restaurants"]
query_filter = {"name" : "Pizza Town"}
replace_document = { "name" : "Mongo's Pizza",
                     "cuisine" : "Pizza",
                     "address" : {
                         "street" : "123 Pizza St",
                         "zipCode" : "10003"
                     },
                     "borough" : "Manhattan"
                   }
result = restaurants.replace_one(query_filter, replace_document)

重要

_id 字段的值不可变。如果您的替换文档指定 _id 字段的值，则它必须与现有文档的 _id 值匹配。

自定义替换操作

replace_one()方法可以选择接受其他参数，这些参数表示可用于配置替换操作的选项。如果不指定任何其他选项，驱动程序不会自定义替换操作。

属性	说明
`upsert`	指定在没有文档与查询过滤匹配的情况下，替换操作是否执行更新或插入（upsert）操作。有关更多信息，请参阅MongoDB Server手册中的更新或插入（upsert）声明。默认为 `False`
`bypass_document_validation`	指定替换操作是否绕过文档验证。这样，您就可以替换不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅MongoDB Server手册中的模式验证。默认为 `False`。
`collation`	指定对结果进行排序时要使用的语言排序规则类型。有关更多信息，请参阅MongoDB Server手册中的排序规则。
`hint`	获取或设置用于扫描文档的索引。有关更多信息，请参阅MongoDB Server手册中的提示声明。
`session`	`ClientSession`的实例。
`let`	参数名称和值的映射。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。
`comment`	要附加到操作的注释。有关更多信息，请参阅MongoDB Server手册中的插入命令字段指南。

以下代码使用replace_one()方法查找name字段值为"Food Town"的第一个文档，然后将此文档替换为名为"Food World"的新文档。由于upsert选项设置为True ，因此如果查询筛选器与任何现有文档都不匹配，驱动程序将插入新文档。

restaurants = database["restaurants"]
query_filter = {"name" : "Food Town"}
replace_document = { "name" : "Food World",
                     "cuisine" : "Mixed",
                     "address" : {
                         "street" : "123 Food St",
                         "zipCode" : "10003"
                     },
                     "borough" : "Manhattan"
                   }
result = restaurants.replace_one(query_filter, replace_document, upsert = True)

返回值

replace_one() 方法返回 UpdateResult 对象。UpdateResult 类型包含以下属性：

属性	说明
`matched_count`	与查询筛选器匹配的文档数量，无论已更新文档的数量如何。
`modified_count`	更新操作修改的文档数。如果更新后的文档与原始文档相同，则不计入此计数。
`raw_result`	服务器返回的原始结果文档。
`upserted_id`	如果驱动程序执行了更新或插入，则为数据库中已更新或插入的文档的 ID。否则`None` 。

替换文档

Overview

样本数据

替换操作

所需参数

replaceOne

自定义替换操作

返回值

更多信息

API 文档