MongoDB\Collection::updateOne()

在本页面上

定义

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

定义

MongoDB\Collection::updateOne()

更新最多匹配过滤器条件的单个文档。如果多个文档匹配过滤器条件，则仅更新第一个匹配的文档。

function updateOne(
    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.
会话	MongoDB\Driver\Session	要关联操作的客户端会话。新版本1.3.
upsert	布尔型	如果设置为 `true`，则在没有文档匹配查询条件时创建新文档。默认值是 `false`，当未找到匹配项时不会插入新文档。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作。默认为集合的写关注。无法在事务中指定单个操作的写关注。相反，在开始事务时设置 `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 对象以确定错误的性质。

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

示例

以下示例通过将name字段设置为"Brunos on Astoria"来更新一个具有restaurant_id为"40356151"的文档

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updateResult = $collection->updateOne(
    [ 'restaurant_id' => '40356151' ],
    [ '$set' => [ 'name' => 'Brunos on Astoria' ]]
);
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());

输出结果将类似于

Matched 1 document(s)
Modified 1 document(s)

另请参阅

updateMany()

updateSearchIndex()