/ /

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`	Whether the update operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Default: `false`
`bypass_document_validation`	Whether the update operation bypasses document validation. This lets you update 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. Default: `false`
`collation`	Language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`array_filters`	List of filters that you specify to select which array elements the update applies to.
`hint`	Index to use when matching documents. For more information, see the hint statement in the MongoDB Server manual.
`let`	Map of parameter names and values to set top-level variables for the operation. 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.

修改更新示例

该示例使用 $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`	Number of documents that matched the query filter, regardless of how many updates were performed.
`modified_count`	Number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count.
`acknowledged?`	Returns `true` if the server acknowledged the result.
`upserted_count`	Returns the number of documents that were upserted in the database, if the driver performed an upsert.
`upserted_ids`	Returns the `_id` value of the document that was upserted in the database, if the driver performed an upsert.

提示

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