替换文档

本页

概述

示例数据
替换操作
必需参数
替换一个
自定义替换操作
返回值
附加信息
API文档

概述

在本指南中，您可以学习如何使用PyMongo在MongoDB集合中对文档执行替换操作。替换操作与更新操作不同。更新操作仅修改目标文档中指定的字段。替换操作会删除目标文档中的所有字段，并用新的字段替换它们。

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

示例数据

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

替换操作

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

必需参数

replace_one()方法需要以下参数

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

替换一个

以下示例使用replace_one()方法来替换具有"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`	指定替换操作是否在查询过滤器没有匹配的文档时执行更新操作。有关更多信息，请参阅MongoDB服务器手册中的更新命令 upsert。默认值为`False`
`bypass_document_validation`	指定替换操作是否绕过文档验证。这允许您替换不满足模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅MongoDB服务器手册中的模式验证。默认值为`False`。
`collation`	指定排序结果时要使用的语言排序类型。有关更多信息，请参阅MongoDB服务器手册中的排序。
`hint`	获取或设置要扫描文档的索引。有关更多信息，请参阅MongoDB服务器手册中的提示语句。
`session`	是`ClientSession`的一个实例。
`let`	参数名称和值的映射图。值必须是常数或封闭表达式，不能引用文档字段。有关更多信息，请参阅MongoDB服务器手册中的let语句。
`注释`	附加到操作的注释。有关更多信息，请参阅MongoDB服务器手册中的插入命令字段指南。

以下代码使用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`	如果驱动程序执行了upsert，则在数据库中upsert的文档的ID。否则为`None`。

概述

示例数据

替换操作

必需参数

替换一个

重要

自定义替换操作

返回值

更多信息

API 文档