MongoDB\Collection::findOneAndUpdate()

本页内容

定义

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

定义

MongoDB\Collection::findOneAndUpdate()

查找匹配查询的单个文档并更新它。

function findOneAndUpdate(
    array|object $filter,
    array|object $update,
    array $options = []
): object|null

参数

$filter : array|object

指定要更新的文档的过滤条件。

$update : array|object

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

$options : array

指定所需选项的数组。

名称	类型	描述
bypassDocumentValidation	boolean	如果为 `true`，则允许写操作绕过文档级验证。默认为 `false`。
arrayFilters	array	一个过滤器文档数组，用于确定在数组字段上的更新操作中要修改哪些数组元素。新版本1.3.
collation	array\|object	排序规则允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。在指定排序规则时，`locale`字段是必需的；所有其他排序规则字段都是可选的。有关字段的描述，请参阅排序规则文档。如果未指定排序规则，但集合具有默认排序规则，则操作使用集合中指定的排序规则。如果集合或操作未指定排序规则，MongoDB将使用之前版本中用于字符串比较的简单二进制比较。
注释	混合	此选项允许用户指定任意注释以帮助通过数据库分析器、当前操作输出和日志跟踪操作。此选项自MongoDB 4.4起可用，如果用于较旧的服务器版本，则会在执行时引发异常。新版本1.13.
提示	字符串\|数组\|对象	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。此选项自MongoDB 4.4起可用，如果用于较旧的服务器版本，则会在执行时引发异常。新版本1.7.
maxTimeMS	整数	在游标上处理操作的累积时间限制（以毫秒为单位）。MongoDB会在最早的中断点处终止操作。
let	array\|object	参数名称和值的映射。值必须是常量或封闭表达式，不能引用文档字段。然后可以在聚合表达式上下文中作为变量访问参数（例如 `$$var`）。此选项不支持5.0之前的版本，如果使用则会引发执行时异常。新版本1.13.
投影	array\|object	用于确定返回文档中应包含哪些字段的投影规范。请参阅MongoDB手册中的从查询结果中投影字段和投影运算符。
returnDocument	整数	指定是否在应用更新之前或之后返回文档。`returnDocument`支持以下值 `MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_BEFORE` （默认值） `MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER`
会话	MongoDB\Driver\Session	要与此操作关联的客户端会话。新版本1.3.
sort	array\|object	用于排序结果顺序的排序规范。
typeMap	array	将类型映射应用到游标上，这决定了 BSON 文档如何转换为 PHP 值。默认值为集合的类型映射。这将用于返回的结果文档。
upsert	boolean	如果设置为 `true`，则在没有文档匹配查询条件时创建新文档。默认值为 `false`，当找不到匹配项时不会插入新文档。
writeConcern	MongoDB\Driver\WriteConcern	写入关注用于操作的。默认值为集合的写入关注。在事务中无法为单个操作指定写入关注。相反，在开始事务时设置 `writeConcern` 选项。

返回值

一个数组或对象，用于原始文档或更新后的文档，具体取决于returnDocument选项指定的值。默认情况下，返回原始文档。如果没有文档匹配查询，则返回null。返回类型将取决于typeMap选项。

错误/异常

如果服务器命令响应格式不正确，则抛出MongoDB\Exception\UnexpectedValueException。

如果选项被使用但所选服务器不支持（例如collation，readConcern，writeConcern），则抛出MongoDB\Exception\UnsupportedException。

对于与参数或选项解析相关的错误，抛出MongoDB\Exception\InvalidArgumentException。

对于扩展级别上的其他错误（例如连接错误），抛出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).

示例

以下操作通过将建筑号设置为“761”来更新“test”数据库中“restaurants”集合中具有restaurant_id的"40361708"的餐厅：

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updatedRestaurant = $collection->findOneAndUpdate(
    [ 'restaurant_id' => '40361708' ],
    [ '$set' => [ 'address.building' => '761' ]],
    [
        'projection' => [ 'address' => 1 ],
        'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER,
    ]
);
var_dump($updatedRestaurant);

输出将类似于：

object(MongoDB\Model\BSONDocument)#20 (1) {
  ["storage":"ArrayObject":private]=>
  array(2) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#12 (1) {
      ["oid"]=>
      string(24) "594d5ef280a846852a4b3dee"
    }
    ["address"]=>
    object(MongoDB\Model\BSONDocument)#19 (1) {
      ["storage":"ArrayObject":private]=>
      array(4) {
        ["building"]=>
        string(3) "761"
        ["coord"]=>
        object(MongoDB\Model\BSONArray)#18 (1) {
          ["storage":"ArrayObject":private]=>
          array(2) {
            [0]=>
            float(-73.9925306)
            [1]=>
            float(40.7309346)
          }
        }
        ["street"]=>
        string(8) "Broadway"
        ["zipcode"]=>
        string(5) "10003"
      }
    }
  }
}

另请参阅

MongoDB Collection::findOneAndDelete()
MongoDB Collection::findOneAndReplace()
findAndModify 命令参考，见 MongoDB 手册

findOneAndReplace()

getCollectionName()