MongoDB\Collection::findOneAndUpdate()

在此页面上

定义
参数
Return Values
错误/异常
行为
示例
另请参阅

定义

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

Return Values

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

错误/异常

MongoDB\Exception\UnexpectedValueException ，如果来自服务器的命令响应格式错误。

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

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

MongoDB\ 驱动程序\Exception\RuntimeException 对于扩展级别的其他错误（例如连接错误）。

行为

在评估查询条件时，MongoDB 会根据自己的比较规则来BSON types 比较类型和值，这不同于的PHP 比较和类型杂技规则。匹配特殊BSON类型时，查询条件应使用相应的 BSON类在扩展（例如使用 MongoDB\ BSON\ObjectId 以匹配 ObjectId ）。

示例

以下操作通过将其建筑物编号设置为"761"来更新test数据库中的restaurantscollection中"40361708"的restaurant_id的餐厅：

<?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()
MongoDB 手册中的findAndModify命令参考

后退

FindOneAndReplace()

来年

getCollectionName()