MongoDB\Collection::deleteOne()

本页内容

定义

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

定义

MongoDB\Collection::deleteOne()

删除最多匹配过滤条件的单个文档。如果多个文档匹配过滤条件，则只删除第一个匹配的文档。

function deleteOne(
    array|object $filter,
    array $options = []
): MongoDB\DeleteResult

参数

$filter : array|object

指定要删除的文档的筛选条件。

$options : array

指定所需选项的数组。

名称	类型	描述
collation	array\|object	排序允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。在指定排序时，`locale`字段是必需的；所有其他排序字段都是可选的。有关字段的描述，请参阅排序文档。如果未指定排序，但集合具有默认排序，则操作将使用为集合指定的排序。如果集合或操作未指定排序，MongoDB将使用先前版本中用于字符串比较的简单二进制比较。
comment	mixed	启用用户指定任意注释，以帮助通过数据库分析器、当前操作输出和日志跟踪操作。此选项自MongoDB 4.4起可用，如果为旧服务器版本指定，则在执行时将引发异常。新在版本中1.13.
hint	string\|array\|object	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。此选项自MongoDB 4.4起可用，如果为旧服务器版本指定，则在执行时将引发异常。新在版本中1.7.
let	array\|object	参数名称和值的映射。值必须是常量或封闭表达式，不引用文档字段。参数然后可以作为聚合表达式上下文中的变量访问（例如 `$$var`）。此功能不支持5.0之前的版本，如果使用，将在执行时引发异常。新在版本中1.13.
session	MongoDB\Driver\Session	与操作关联的客户端会话。新在版本中1.3.
writeConcern	MongoDB\Driver\WriteConcern	写入关注用于操作的写入关注。默认为集合的写入关注。在事务中无法为单个操作指定写入关注度。相反，请在开始事务时设置 `writeConcern` 选项。

返回值

AMongoDB\DeleteResult 对象，该对象封装了一个 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 对象，以确定错误的性质。

例如，写入操作可能已成功应用到主服务器，但未能满足写入关注（例如，复制耗时过长）。或者，写入操作可能直接失败（例如，违反了唯一键约束）。

示例

以下示例删除了具有"ny"作为state字段值的users集合中的一个文档

<?php
$collection = (new MongoDB\Client)->test->users;
$collection->drop();
$collection->insertOne(['name' => 'Bob', 'state' => 'ny']);
$collection->insertOne(['name' => 'Alice', 'state' => 'ny']);
$deleteResult = $collection->deleteOne(['state' => 'ny']);
printf("Deleted %d document(s)\n", $deleteResult->getDeletedCount());

输出将类似于

Deleted 1 document(s)

另请参阅

deleteMany()

distinct()