MongoDB\GridFS\Bucket::findOne()

定义

MongoDB\GridFS\Bucket::findOne()

从 GridFS 存储桶的文件collection中查找与查询匹配的单个文档。

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

参数

$filter : array|object

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

$options : array

指定所需选项的数组。

名称	类型	说明
allowDiskUse	布尔	允许写入临时文件。设置为 true 时，查询可以将数据写入到 dbPath 目录的 _tmp 子目录中。
allowPartialResults	布尔	对于针对分片集合的查询，如果某些分片不可用，则从 mongos返回部分结果，而不是引发错误。
编解码器	MongoDB\Codec\DocumentCodec	Encode Data with Type Codecs 用于对文档进行编码或解码。此选项与 typeMap 选项互斥。 默认为存储桶的编解码器。 默认codec选项的继承优先于typeMap选项的继承。 1.17 版本中的新增功能。
排序规则	数组|对象	排序规则允许用户为string比较指定特定于语言的规则，例如字母大小写和重音符号规则。 指定排序规则时， locale字段为必填字段；所有其他排序规则字段都是可选的。 有关字段的说明，请参阅排序规则文档。
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	读取关注以用于操作。 默认为存储桶的读关注（read concern）。 无法将单个操作的读关注（read concern）指定为ACID 事务的一部分。相反，请在启动ACID 事务时设立readConcern 选项。
readPreference	MongoDB\Driver\ReadPreference	读取要用于操作的偏好。 默认为存储桶的读取偏好（read preference）。
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 类型比较规则来比较类型和值，这与 PHP 的比较和类型规则不同。匹配特殊BSON类型时，查询条件应使用扩展中相应的BSON类（例如使用MongoDB\BSON\ObjectId来匹配ObjectId）。

示例

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = fopen('php://temp', 'w+b');
fwrite($stream, "foobar");
rewind($stream);
$bucket->uploadFromStream('b', $stream);
$fileDocument = $bucket->findOne(
    ['length' => ['$lte' => 6]],
    [
        'projection' => [
            'filename' => 1,
            'length' => 1,
            '_id' => 0,
        ],
        'sort' => ['length' => -1],
    ]
);
var_dump($fileDocument);

而输出将类似如下所示：

object(MongoDB\Model\BSONDocument)#3004 (1) {
  ["storage":"ArrayObject":private]=>
  array(2) {
    ["filename"]=>
    string(1) "b"
    ["length"]=>
    int(6)
  }
}

另请参阅

• MongoDB\Collection::findOne()

• MongoDB\GridFS\Bucket::find()