Docs 菜单
Docs 主页
/
语言
/
PHP
/
PHP 库手册
/
API 文档
/
MongoDB\集合

MongoDB\Collection::deleteOne()

在此页面上

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

定义

MongoDB\Collection::deleteOne()

最多删除一个与筛选条件匹配的文档。 如果有多个文档符合筛选条件，则仅删除个第一个匹配的文档。

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

参数

$filter : array|object
指定要删除的文档的筛选条件。
$options : array

指定所需选项的数组。

名称
类型
说明
排序规则
数组|对象

排序规则允许用户为string比较指定特定于语言的规则，例如字母大小写和重音符号规则。 指定排序规则时， locale字段为必填字段；所有其他排序规则字段都是可选的。 有关字段的说明，请参阅排序规则文档。

如果未指定排序规则但集合具有默认排序规则，则操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。

comment
混合

使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。

自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。

1.13 版本中的新增功能。

提示
字符串|数组|对象

要使用的索引。将索引名称指定为字符串或将索引键模式指定为文档。如果指定，查询系统将只考虑使用提示索引的计划。

自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。

版本 1.7 中的新增内容。

let
数组|对象

参数名称和值的映射。值必须是常量或不引用文档字段的封闭表达式。然后可以在聚合表达式上下文中将参数作为变量进行访问（例如 $$var）。

5.0 之前的服务器版本不支持此功能，如果使用，将导致执行时出现异常。

1.13 版本中的新增功能。

会话

与操作相关联的客户端会话。

1.3 版本中的新增功能。

writeConcern

写关注用于操作。默认为集合的写关注。

无法将单个操作的写关注指定为事务的一部分。 相反，请在writeConcern 启动事务 时设置 选项。

Return Values

一个MongoDB\DeleteResult 对象，其中封装了 MongoDB\ 驱动程序\WriteResult 对象。

错误/异常

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

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

MongoDB\Driver\Exception\BulkWriteException 与写入操作相关的错误。用户应检查 getWriteResult() 返回的值 以确定错误的性质。

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

行为

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

如果 MongoDB\Driver\Exception\BulkWriteException 抛出，用户应调用 getWriteResult() 并检查返回的 MongoDB\Driver\WriteResult 对象以确定错误的性质。

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

例子

users以下示例删除collection中字段的值为"ny" state的一个文档：

<?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()