更新文档

在本页

概述

示例数据
更新操作
更新单个文档
更新多个文档
自定义更新操作
返回值
附加信息
API 文档

概述

在此指南中，您可以学习如何使用 MongoDB PHP 库来更新 MongoDB 集合中的文档。您可以调用MongoDB\Collection::updateOne() 方法来更新单个文档或调用 MongoDB\Collection::updateMany() 方法来更新多个文档。

示例数据

本指南中的示例使用来自Atlas 示例数据集的 sample_restaurants 数据库中的 restaurants 集合。要从您的 PHP 应用程序访问此集合，请实例化一个连接到 Atlas 集群的 MongoDB\Client，并将以下值分配给您的 $collection 变量

$collection = $client->sample_restaurants->restaurants;

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

更新操作

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

MongoDB\Collection::updateOne()，它更新与搜索条件匹配的第一个文档
MongoDB\Collection::updateMany()，它更新所有与搜索条件匹配的文档

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

查询过滤器文档：指定要更新的文档。有关查询过滤器的更多信息，请参阅MongoDB服务器手册中的查询过滤器文档部分。
更新文档：指定更新运算符或要执行的更新类型，以及要更改的字段和值。有关更新运算符及其使用的列表，请参阅MongoDB服务器手册中的字段更新运算符指南。

更新单个文档

以下示例使用updateOne()方法将restaurants集合中文档的name值从'Bagels N Buns'更新为'2 Bagels 2 Buns'

$result = $collection->updateOne(
    ['name' => 'Bagels N Buns'],
    ['$set' => ['name' => '2 Bagels 2 Buns']]
);

更新多个文档

以下示例使用 updateMany() 方法更新所有具有 cuisine 值为 'Pizza' 的文档。更新后，文档的 cuisine 值变为 'Pasta'。

$result = $collection->updateMany(
    ['cuisine' => 'Pizza'],
    ['$set' => ['cuisine' => 'Pasta']]
);

自定义更新操作

您可以通过传递一个指定选项值的数组作为参数来修改 updateOne() 和 updateMany() 方法的行为。以下表格描述了您可以在数组中设置的某些选项

选项	描述
`upsert`	指定更新操作是否在查询过滤器没有匹配文档时执行 upsert 操作。有关更多信息，请参阅 MongoDB 服务器手册中的 upsert 语句。默认为 `false`。
`bypassDocumentValidation`	指定更新操作是否跳过文档验证。这允许您更新不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅 MongoDB 服务器手册中的 Schema Validation。默认为 `false`。
`collation`	指定排序结果时使用的语言排序类型。有关更多信息，请参阅 MongoDB 服务器手册中的 Collation。
`arrayFilters`	指定在操作修改数组字段时更新哪些数组元素。
`hint`	设置扫描文档的索引。更多信息，请参阅MongoDB服务器手册中的提示语句。
`writeConcern`	设置操作的写关注。更多信息，请参阅MongoDB服务器手册中的写关注。
`let`	指定一个包含值列表的文档以提高操作可读性。值必须是常量或无引用文档字段的封闭表达式。更多信息，请参阅MongoDB服务器手册中的let语句。
`comment`	附加到操作的注释。更多信息，请参阅MongoDB服务器手册中的插入命令字段指南。

以下示例使用updateMany()方法查找所有具有borough值为'Manhattan'的文档。然后，将这些文档中的borough值更新为'Manhattan (north)'。因为upsert选项设置为true，如果查询过滤器不匹配任何现有文档，MongoDB PHP库将插入一个新文档。

$result = $collection->updateMany(
    ['borough' => 'Manhattan'],
    ['$set' => ['borough' => 'Manhattan (north)']],
    ['upsert' => true]
);

返回值

updateOne()和updateMany()方法返回一个MongoDB\UpdateResult类的实例。此类包含以下成员函数

函数	描述
`getMatchedCount()`	返回与查询过滤器匹配的文档数量，无论更新了多少。
`getModifiedCount()`	返回更新操作修改的文档数量。如果一个更新后的文档与原始文档相同，则不包含在此计数中。
`isAcknowledged()`	返回一个布尔值，表示写操作是否被确认。
`getUpsertedCount()`	返回被插入数据库的文档数量。
`getUpsertedId()`	返回在数据库中上插的文档的ID，如果驱动程序执行了上插操作。

以下示例使用updateMany()方法将匹配文档的name字段从'Dunkin' Donuts'更新为'Dunkin''。它调用getModifiedCount()成员函数来打印修改的文档数量

$result = $collection->updateMany(
    ['name' => 'Dunkin\' Donuts'],
    ['$set' => ['name' => 'Dunkin\'']]
);
echo 'Modified documents: ', $result->getModifiedCount();

Modified documents: 206

附加信息

要了解如何创建查询过滤器，请参阅指定查询指南。

API 文档

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

写入数据

插入