Docs 菜单

Docs 主页 → 开发应用程序 → Python 驱动程序 → pymongo

替换文档

在此页面上

  • Overview
  • 样本数据
  • 替换操作
  • 所需参数
  • replaceOne
  • 自定义替换操作
  • 返回值
  • 更多信息
  • API 文档

Overview

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

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

样本数据

本指南中的示例使用 Atlas 样本数据集中的 sample_restaurants.restaurants集合。 要了解如何创建免费的MongoDB Atlas cluster并加载样本数据集，请参阅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
Specifies whether the replace operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual.
Defaults to False
bypass_document_validation
Specifies whether the replace operation bypasses document validation. This lets you replace documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual.
Defaults to False.
collation
Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
hint
Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
session
An instance of ClientSession.
let
A Map of parameter names and values. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
comment
A comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.

以下代码使用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
The number of documents that matched the query filter, regardless of how many were updated.
modified_count
The number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count.
raw_result
The raw result document returned by the server.
upserted_id
The ID of the document that was upserted in the database, if the driver performed an upsert. Otherwise None.

更多信息

要了解创建查询筛选器的更多信息，请参阅指定查询指南。

API 文档

要进一步了解本指南所讨论的任何方法或类型，请参阅以下 API 文档：

← Update Documents
Delete Documents →

在此页面上