/ /

Update Documents

Overview

在本指南中，您可以学习如何使用Ruby驱动程序通过 update_one 和 update_many 方法更新MongoDB集合中的文档。

样本数据

本指南中的示例使用Atlas示例数据集的 sample_restaurants数据库中的 restaurants集合。要从Ruby应用程序访问权限此集合，请创建一个连接到Atlas 集群的Mongo::Client对象，并将以下值分配给 database 和 collection 变量：

database = client.use('sample_restaurants')
collection = database[:restaurants]

要学习如何创建免费的MongoDB Atlas 集群并加载示例数据集，请参阅MongoDB 入门指南。

更新操作

您可以使用以下方法更新MongoDB中的文档：

update_one：更新符合搜索条件的第一个文档
update_many：更新所有符合搜索条件的文档

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

查询过滤，用于匹配要更新的文档。如需学习；了解有关查询筛选器的更多信息，请参阅“指定查询”指南。
更新文档，指定更新操作符以及要更新的字段和值。更新操作符指定要执行的更新类型。要查看更新操作符列表并学习；了解其用法，请参阅MongoDB Server手册中的字段更新操作符指南页面。

更新一个文档示例

以下示例使用 update_one 方法查找 name字段的值为 "Happy Garden" 的第一个文档。然后使用 $set操作符将 name字段值更新为 "Mountain House"。

filter = { name: 'Happy Garden' }
update = { '$set' => { name: 'Mountain House' } }
single_result = collection.update_one(filter, update)
puts "#{single_result.modified_count} document(s) updated."

1 document(s) updated

更新多个文档示例

以下示例使用 update_many 方法更新name字段值为 "Starbucks" 的所有文档。更新文档使用 $rename操作符将 address字段的名称更改为 location。

filter = { name: 'Starbucks' }
update = { '$rename' => { address: 'location' } }
many_result = collection.update_many(filter, update)
puts "#{many_result.modified_count} document(s) updated."

11 document(s) updated

更新或插入（upsert）选项

upsert 参数允许您使用 update_one() 和 update_many() 操作来执行条件操作：

如果指定的文档存在，该命令将对其进行更新。
如果指定的文档不存在，该命令将使用指定参数创建新文档。

有关更多信息，请参阅修改更新示例部分或本页上的选项表。

自定义更新操作

update_one 和 update_many 方法接受用于配置更新操作的选项。您可以单独将这些选项作为参数传递，也可以创建一个包含这些选项的 Hash对象并将该对象作为参数传递。如果不指定任何选项，驱动程序将使用默认设置执行更新操作。

下表描述了可用于配置更新操作的选项：

选项	说明
`upsert`	如果没有文档与查询过滤匹配，更新操作是否执行更新或插入（upsert）操作。有关更多信息，请参阅MongoDB Server手册中的更新或插入（upsert）声明。默认值： `false`
`bypass_document_validation`	更新操作是否绕过文档验证。这样，您就可以更新不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅MongoDB Server手册中的模式验证。默认值： `false`
`collation`	对结果进行排序时使用的语言排序规则。有关更多信息，请参阅MongoDB Server手册中的排序规则。
`array_filters`	指定用于选择更新应用于哪些大量元素的筛选器列表。
`hint`	匹配文档时使用的索引。有关更多信息，请参阅MongoDB Server手册中的提示声明。
`let`	用于设立操作的顶级变量的参数名称和值的映射。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。

修改更新示例

该示例使用 $equal操作符匹配 name字段值为 "Sunrise Pizzeria" 的文档。然后，它使用 $set操作符将第一个匹配文档中的 borough字段值设立为 "Queens"，并将 cuisine字段值设置为 "Italian"。

由于 upsert 选项设立为 true，因此如果查询筛选条件与任何现有文档都不匹配，驱动程序将插入一个包含过滤器和更新文档中的字段和值的新文档。

filter = { 'name' => 'Sunrise Pizzeria' }
update = { '$set' => { borough: 'Queens', cuisine: 'Italian' } }
upsert_result = collection.update_one(filter, update, upsert: true)
puts "#{upsert_result.modified_count} document(s) updated."

1 document(s) updated

返回值

update_one 和 update_many 方法各返回一个 Result对象。您可以从 Result实例访问权限以下方法：

方法	说明
`matched_count`	与查询过滤匹配的文档数量，无论执行了多少次更新。
`modified_count`	更新操作修改的文档数量。如果更新后的文档与原始文档相同，则不计入此计数。
`acknowledged?`	如果服务器确认结果，则返回 `true`。
`upserted_count`	如果驾驶员执行了更新或插入（upsert），则返回数据库中已更新或插入的文档数。
`upserted_ids`	如果驱动程序执行了更新或插入，则返回在数据库中更新或插入的文档的 `_id` 值。

提示

在尝试调用任何其他 Result 方法之前，请检查 acknowledged? 方法的值。如果 acknowledged? 方法返回 false，则当您尝试对 Result对象调用任何其他方法时，驱动程序会引发 InvalidOperation 异常。如果服务器未确认写入操作，则驱动程序无法确定这些值。