MongoDB\Collection::updateMany()

本页内容

定义

参数
返回值
错误/异常
行为
示例
另请参阅

定义

MongoDB\Collection::updateMany()

更新所有匹配过滤器条件的文档。

function updateMany(
    array|object $filter,
    array|object $update,
    array $options = []
): MongoDB\UpdateResult

参数

$filter : 数组|对象

指定要更新的文档的筛选条件。

$update : 数组|对象

指定要更新字段和值组合以及任何相关的更新运算符。$update 使用 MongoDB 的更新运算符。从 MongoDB 4.2 开始，可以将聚合管道作为此参数传递。

$options : 数组

指定所需选项的数组。

名称	类型	描述
arrayFilters	数组	一个筛选文档数组，用于确定要修改数组字段的更新操作中的哪些数组元素。新在版本1.3.
bypassDocumentValidation	布尔值	如果设置为 `true`，则允许写入操作绕过文档级验证。默认为 `false`。
collation	数组\|对象	排序规则允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定排序规则时，`locale` 字段是必需的；所有其他排序规则字段都是可选的。有关字段的说明，请参阅排序规则文档。如果未指定排序规则，但集合有默认排序规则，则操作使用集合指定的排序规则。如果集合或操作未指定排序规则，MongoDB 使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	允许用户指定任意注释，以帮助通过数据库分析器、当前操作输出和日志跟踪操作。此选项自 MongoDB 4.4 起可用，如果为旧服务器版本指定，则在执行时将引发异常。新在版本1.13.
hint	字符串\|数组\|对象	要使用的索引。指定索引名称（字符串形式）或索引键模式（文档形式）。如果指定，则查询系统将只考虑使用提示索引的计划。此选项自MongoDB 4.2版本起可用，如果用于旧版本服务器，则在执行时将引发异常。新在版本1.6.
let	数组\|对象	参数名称和值的映射。值必须是常数或封闭表达式，不得引用文档字段。参数可以然后在聚合表达式上下文中作为变量访问（例如 `$$var`）。此功能不支持5.0版本之前的服务器，如果使用则会在执行时引发异常。新在版本1.13.
session	MongoDB\Driver\Session	与操作关联的客户端会话。新在版本1.3.
upsert	布尔值	如果设置为 `true`，则在没有文档匹配查询条件时创建新文档。默认值是 `false`，表示如果没有找到匹配项则不插入新文档。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作的写关注。默认为集合的写关注。无法指定作为事务一部分的个别操作的写关注。相反，在开始事务时

返回值

AMongoDB\UpdateResult 对象，它封装了一个 MongoDB\Driver\WriteResult 对象。

错误/异常

MongoDB\Exception\UnsupportedException 如果使用了不支持所选服务器（例如 collation、readConcern、writeConcern）的选项。

MongoDB\Exception\InvalidArgumentException 与参数或选项解析相关的错误。

MongoDB\Driver\Exception\BulkWriteException 用于处理写入操作相关的错误。用户应检查getWriteResult() 返回的值，以确定错误的性质。

MongoDB\Driver\Exception\RuntimeException 用于处理扩展层面的其他错误（例如连接错误）。

行为

When evaluating query criteria, MongoDB compares types and values according to its own comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class in the extension (e.g. use MongoDB\BSON\ObjectId to match an ObjectId).

如果抛出了 MongoDB\Driver\Exception\BulkWriteException 异常，用户应调用 getWriteResult() 并检查返回的 MongoDB\Driver\WriteResult 对象以确定错误的性质。

例如，写入操作可能已成功应用到主服务器，但未能满足写入关注点（例如，复制花费时间过长）。或者，写入操作可能完全失败（例如，违反了唯一键）。

示例

以下示例通过将 active 字段设置为 true 来更新所有具有 "Queens" 区的文档

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updateResult = $collection->updateMany(
    [ 'borough' => 'Queens' ],
    [ '$set' => [ 'active' => true ]]
);
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());

输出结果如下

Matched 5656 document(s)
Modified 5656 document(s)

另请参阅

replaceOne()

updateOne()