MongoDB\Collection::findOneAndDelete()

本页内容

定义

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

定义

MongoDB\Collection::findOneAndDelete()

查找匹配查询的单个文档并将其删除。

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

参数

$filter : array|object

指定要删除的文档的过滤器条件。

$options : array

指定所需选项的数组。

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

返回值

被删除的文档的数组或对象，或如果没有文档匹配查询，则为null。返回类型将取决于typeMap选项。

错误/异常

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

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

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).

示例

以下示例在 test 数据库中的 restaurants 集合中查找并删除具有 restaurant_id 为 "40375376" 的文档

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$deletedRestaurant = $collection->findOneAndDelete(
    [ 'restaurant_id' => '40375376' ],
    [
        'projection' => [
            'name' => 1,
            'borough' => 1,
            'restaurant_id' => 1,
        ],
    ]
);
var_dump($deletedRestaurant);

输出结果将类似于

object(MongoDB\Model\BSONDocument)#17 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#11 (1) {
      ["oid"]=>
      string(24) "594d5ef280a846852a4b3f70"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["name"]=>
    string(15) "Agra Restaurant"
    ["restaurant_id"]=>
    string(8) "40375376"
  }
}

另请参阅

MongoDB\Collection::findOneAndReplace()
MongoDB\Collection::findOneAndUpdate()
findAndModify 命令参考 MongoDB 手册

findOne()

findOneAndReplace()