MongoDB\Collection::findOne()

定义

MongoDB\Collection::findOne()

查找与查询匹配的单个文档。

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

参数

$filter : array|object

指定要查询的文档的筛选条件。

$options : array

指定所需选项的数组。

名称	类型	说明
allowDiskUse	布尔	允许写入临时文件。设置为 true 时，查询可以将数据写入到 dbPath 目录的 _tmp 子目录中。
allowPartialResults	布尔	对于针对分片集合的查询，如果某些分片不可用，则从 mongos返回部分结果，而不是引发错误。
编解码器	MongoDB\Codec\DocumentCodec	用于对文档进行编码或解码的编解码器。 此选项与typeMap选项互斥。 默认为集合的编解码器。默认 codec 选项的继承优先于 typeMap 选项的继承。 1.17 版本中的新增功能。
排序规则	数组|对象	排序规则允许用户为string比较指定特定于语言的规则，例如字母大小写和重音符号规则。 指定排序规则时， locale字段为必填字段；所有其他排序规则字段都是可选的。 有关字段的说明，请参阅排序规则文档。 如果未指定排序规则但集合具有默认排序规则，则操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。 评论可以是自 MongoDB 4.4 以来任何有效的 BSON 类型。早期服务器版本仅支持字符串值。
提示	字符串|数组|对象	要使用的索引。将索引名称指定为字符串或将索引键模式指定为文档。如果指定，查询系统将只考虑使用提示索引的计划。 版本 1.2 中的新增内容。
let	数组|对象	参数名称和值的映射。值必须是常量或不引用文档字段的封闭表达式。然后可以在聚合表达式上下文中将参数作为变量进行访问（例如 $$var）。 5.0 之前的服务器版本不支持此功能，如果使用，将导致执行时出现异常。 1.13 版本中的新增功能。
Max	数组|对象	特定索引的独占上限。 版本 1.2 中的新增内容。
maxScan	整型	执行查询时要扫描的最大文档数或索引键数。 自版本 1.4 起已弃用。 版本 1.2 中的新增内容。
maxTimeMS	整型	处理游标操作的累计时间限制（以毫秒为单位）。MongoDB 最早会在中断点之后中止操作。
min	数组|对象	特定索引的包含下限。 版本 1.2 中的新增内容。
modifiers	数组|对象	修改查询的输出或行为的元操作符。 这些操作符已弃用，建议使用命名选项。
oplogReplay	布尔	针对副本集的内部用法。要使用 oplogReplay，您必须在筛选器中包含以下条件： { ts: { $gte: <timestamp> } } MongoDB\BSON\Timestamp 类引用描述了如何使用 PHP 表示 MongoDB 的 BSON 时间戳类型。 自版本 1.7 起已弃用。
投影	数组|对象	投影规范，用于确定要在返回的文档中包含哪些字段。 请参阅 MongoDB 手册中的从查询和 投影操作符 返回的项目字段 。
事务外的	MongoDB\Driver\ReadConcern	读取关注以用于操作。 默认为集合的读关注。 无法将单个操作的读关注指定为事务的一部分。 相反，请在readConcern 启动事务 时设置 选项。
readPreference	MongoDB\Driver\ReadPreference	读取要用于操作的偏好。 默认为集合的读取偏好。
returnKey	布尔	如果为 true，则只返回结果文档中的索引键。 版本 1.2 中的新增内容。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3 版本中的新增功能。
showRecordId	布尔	确定定是否返回每个文档的记录标识符。如果为 true，则在返回的文档中添加字段 $recordId。 版本 1.2 中的新增内容。
跳过	整型	要跳过的文档数量。默认值为 0。
sort	数组|对象	对结果排序的排序规范。
typeMap	阵列	类型映射 应用于游标，决定如何将 BSON 文档转换为 PHP 值。默认为集合的类型映射。 这将用于返回的结果文档。

Return Values

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

错误/异常

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

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

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

行为

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

示例

<?php
$database = (new MongoDB\Client)->test;
$zip = $database->zips->findOne(['_id' => '10036']);
$restaurant = $database->restaurants->findOne([
    '_id' => new MongoDB\BSON\ObjectId('594d5ef280a846852a4b3f70'),
]);

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$restaurant = $collection->findOne(
    [
        'cuisine' => 'Italian',
        'borough' => 'Manhattan',
    ],
    [
        'projection' => [
            'name' => 1,
            'borough' => 1,
            'cuisine' => 1,
        ],
    ]
);
var_dump($restaurant);

object(MongoDB\Model\BSONDocument)#10 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#8 (1) {
      ["oid"]=>
      string(24) "576023c6b02fa9281da3f983"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["cuisine"]=>
    string(7) "Italian"
    ["name"]=>
    string(23) "Isle Of Capri Resturant"
  }
}

另请参阅

• MongoDB\Collection::find()

• MongoDB 手册中的查找命令参考