/ /

Update Documents

Overview

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

样本数据

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

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

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

更新操作

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

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

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

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

更新一个文档

以下示例使用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 Server手册中的更新或插入（upsert）声明。默认为 `false`。
`bypassDocumentValidation`	指定更新操作是否绕过文档验证。这样，您就可以更新不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅MongoDB Server手册中的模式验证。默认为 `false`。
`sort`	仅适用于 `updateOne()`。指定在执行更新操作之前应用文档的排序顺序。
`collation`	指定对结果进行排序时要使用的语言排序规则类型。要学习；了解更多信息，请参阅本页的排序规则部分。
`arrayFilters`	指定如果操作修改大量字段，则更新应用于哪些大量元素。
`hint`	设置扫描文档的索引。有关更多信息，请参阅MongoDB Server手册中的提示声明。
`writeConcern`	设置操作的写关注（write concern）。有关更多信息，请参阅MongoDB Server手册中的写关注。
`let`	指定包含值列表的文档，以提高操作的可读性。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。
`comment`	要附加到操作的注释。有关更多信息，请参阅 MongoDB Server 手册中的插入命令字段指南。

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

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

排序规则

要为操作指定排序规则，请传递 $options大量参数，该参数将 collation 选项设置为操作方法。将 collation 选项分配给配置排序规则规则的大量。

下表描述了可以设立以配置排序规则的字段：

字段	说明
`locale`	（必需）指定 Unicode(ICU)区域设置设置的国际组件。有关支持的区域设置列表，请参阅MongoDB Server手册中的排序规则区域设置和默认参数。数据类型： `string`
`caseLevel`	（可选）指定是否包括大小写比较。当设立为 `true`时，比较行为取决于`strength` 字段的值： `strength1` - 如果`strength` 为，`2` PHP库将比较基本字符和大小写。 — 如果为，则PHP库会比较基本字符、变音符号、其他从节点(secondary node`strength` `false`from replica set)差异和大小写。 — 如果为任何其他值，则忽略此字段。当设立为时， PHP库不包括强度级别`1` 或`2` 的大小写比较。数据类型：`bool` 默认值：`false`
`caseFirst`	（可选）指定三级比较期间大小写差异的排序顺序。数据类型： `string` 默认值：`"off"`
`strength`	（可选）指定要执行的比较级别，如 ICU 文档中所定义。数据类型： `int` 默认值：`3`
`numericOrdering`	（可选）指定驾驶员是否将数字字符串作为数字进行比较。如果设立为 `true`，则PHP库将数字字符串作为数字进行比较。示例，在比较字符串“”和“”时，该库使用字符串的数值并将“”视为大于“”。如果设立为10 2102 `false`102102 ，则PHP库将数字字符串作为字符串进行比较。示例，在比较字符串“”和“”时，该库一次比较一个字符，并将“”视为小于“”。有关更多信息，请参阅MongoDB Server手册中的排序规则限制。数据类型： `bool` 默认值：`false`
`alternate`	（可选）指定库是否将空格和标点符号视为基本字符以进行比较。数据类型： `string` 默认值：`"non-ignorable"`
`maxVariable`	（可选）指定当 `alternate`字段设立为`"shifted"` 时库认为可忽略的字符。数据类型： `string` 默认值：`"punct"`
`backwards`	（可选）指定包含变音符号的字符串是否从后往前排序。数据类型： `bool` 默认值：`false`

要学习；了解有关排序规则和每个字段可能值的更多信息，请参阅MongoDB Server手册中的排序规则条目。

返回值

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

function	说明
`getMatchedCount()`	返回与查询过滤匹配的文档数，无论有多少文档已更新。
`getModifiedCount()`	返回更新操作修改的文档数。如果更新后的文档与原始文档相同，则不计入此计数。
`isAcknowledged()`	返回一个布尔值，表示服务器是否确认了写入操作。
`getUpsertedCount()`	返回已更新或插入到数据库中的文档数。
`getUpsertedId()`	如果驱动程序执行了更新或插入（upsert），则返回在数据库中更新或插入的文档的ID。

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

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

Modified documents: 206

更新构建器

您可以使用 MongoDB\Builder\Update 类在 IDE 代码完成和 PHP 类型检查的支持下构造更新文档。Update 类提供与MongoDB更新操作符（如 $set、$inc 和 $unset）相对应的工厂方法。

要使用更新构建器，请将以下类导入您的应用程序：

use MongoDB\Builder\Query;
use MongoDB\Builder\Update;

以下示例使用 Update::set() 工厂方法将 restaurants集合中 name 值为 'Bagels N Buns' 的第一个匹配文档中的 name字段更新为 '2 Bagels 2 Buns'：

$result = $collection->updateOne(
    Query::query(name: Query::eq('Bagels N Buns')),
    Update::set(name: '2 Bagels 2 Buns'),
);

要在单个操作中应用多个更新操作符，请将操作符传递给 MongoDB\Builder\Update 构造函数。以下示例结合使用 Update::set() 和 Update::unset()，将 cuisine字段设立为 Pasta，并从 cuisine 值为 'Pizza' 的所有文档中删除grades字段：

$result = $collection->updateMany(
    Query::query(cuisine: Query::eq('Pizza')),
    new Update(
        Update::set(cuisine: 'Pasta'),
        Update::unset('grades'),
    ),
);

要学习有关构建者类的更多信息并查看更多示例，请参阅构建者操作指南。