/ /

Update Documents

Overview

在本指南中，您可以学习；了解如何使用PyMongo通过update_one()或update_many()方法更新MongoDB集合中的文档。

样本数据

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

更新操作

您可以使用以下方法在 MongoDB 中执行更新操作：

update_one()，更新匹配搜索条件的第一个文档
update_many()，更新与搜索条件匹配的所有文档

每种更新方法都需要以下参数：

查询筛选器文档，用于确定要更新的文档。有关查询筛选器的更多信息，请参阅 MongoDB Server 手册中的查询筛选器文档部分。
更新文档，其中指定更新操作符（要执行的更新类型）以及应更改的字段和值。有关更新操作符及其用法的列表，请参阅 MongoDB Server 手册中的字段更新操作符指南页面。

更新一个文档

以下示例使用 update_one() 方法更新restaurants集合中名为 "Bagels N Buns" 的文档的 name 值。选择Synchronous或Asynchronous标签页以查看相应的代码：

restaurants = database["restaurants"]
query_filter = {'name' : 'Bagels N Buns'}
update_operation = { '$set' : 
    { 'name' : '2 Bagels 2 Buns' }
}
result = restaurants.update_one(query_filter, update_operation)

restaurants = database["restaurants"]
query_filter = {'name' : 'Bagels N Buns'}
update_operation = { '$set' : 
    { 'name' : '2 Bagels 2 Buns' }
}
result = await restaurants.update_one(query_filter, update_operation)

更新多个文档

以下示例使用 update_many() 方法更新cuisine 值为 "Pizza" 的所有文档。更新后，文档的 cuisine 值为 "Pasta"。选择Synchronous或Asynchronous标签页以查看相应的代码：

restaurants = database["restaurants"]
query_filter = {'cuisine' : 'Pizza'}
update_operation = { '$set' : 
    { 'cuisine' : 'Pasta' }
}
result = restaurants.update_many(query_filter, update_operation)

restaurants = database["restaurants"]
query_filter = {'cuisine' : 'Pizza'}
update_operation = { '$set' : 
    { 'cuisine' : 'Pasta' }
}
result = await restaurants.update_many(query_filter, update_operation)

自定义更新操作

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

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

以下代码使用 update_many() 方法查找 borough字段值为 "Manhattan" 的所有文档。然后，它将这些文档中的 borough 值更新为 "Manhattan (north)"。由于 upsert 选项设立为 True，因此如果查询过滤与任何现有文档都不匹配， PyMongo就会插入一个新文档。选择Synchronous或Asynchronous标签页以查看相应的代码：

restaurants = database["restaurants"]
query_filter = {'borough' : 'Manhattan'}
update_operation = { '$set' : 
    { 'borough' : 'Manhattan (north)' }
}
result = restaurants.update_many(query_filter, update_operation, upsert = True)

restaurants = database["restaurants"]
query_filter = {'borough' : 'Manhattan'}
update_operation = { '$set' : 
    { 'borough' : 'Manhattan (north)' }
}
result = await restaurants.update_many(query_filter, update_operation, upsert = True)

排序规则

执行更新操作时，可以指定驱动程序使用的排序规则。

排序规则是一设立特定于语言的字符串比较规则，例如字母大小写和重音符号规则。

要指定排序规则，请创建 Collation 类或Python字典的实例。有关要传递给 Collation 构造函数或作为键包含在字典中的选项列表，请参阅MongoDB Server手册中的排序规则。

提示

导入排序规则

要创建 Collation 类的实例，必须从 pymongo.collation 导入。

以下示例执行与上一示例相同的更新操作，但默认默认规则为 fr_CA。选择Synchronous或Asynchronous标签页以查看相应的代码：

from pymongo.collation import Collation
restaurants = database["restaurants"]
query_filter = {'cuisine' : 'Pizza'}
update_operation = { '$set' : 
    { 'cuisine' : 'Pasta' }
}
result = restaurants.update_many(query_filter, update_operation,
                                 collation=Collation(locale='fr_CA'))

from pymongo.collation import Collation
restaurants = database["restaurants"]
query_filter = {'cuisine' : 'Pizza'}
update_operation = { '$set' : 
    { 'cuisine' : 'Pasta' }
}
result = await restaurants.update_many(query_filter, update_operation,
                                       collation=Collation(locale='fr_CA'))

注意

操作排序规则覆盖默认值

当您在操作中指定排序规则时，它将覆盖集合的默认规则。

返回值

update_one() 和 update_many() 方法会各自返回一个 UpdateResult 对象。UpdateResult 类型包含以下属性：

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