文档菜单

文档首页 → 开发应用程序 → Python 驱动 → PyMongo

替换文档

本页内容

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

概述

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

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

示例数据

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

替换操作

您可以通过使用 replace_one() 方法在 MongoDB 中执行替换操作。此方法从符合搜索条件的第一个文档中删除除 _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 服务器手册中的排序。
提示
获取或设置要扫描文档的索引。有关更多信息，请参阅 MongoDB 服务器手册中的提示语句。
会话
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
如果驱动程序执行了插入操作，则在数据库中插入的文档的ID；否则为None。

更多信息

要了解有关创建查询过滤器的更多信息，请参阅指定查询指南。

API 文档

要了解有关本指南中讨论的任何方法或类型的更多信息，请参阅以下 API 文档

← 更新文档
删除文档 →

本页内容