MongoDB\GridFS\Bucket::find()

定义

MongoDB\GridFS\Bucket::find()

从GridFS存储桶的文件集合中查找与查询匹配的文档。

function find(
    array|object $filter = [],
    array $options = []
): MongoDB\Driver\Cursor

参数

$filter : array|object

指定要查询的文档的过滤器条件。

$options : array

指定所需选项的数组。

名称	类型	描述
allowDiskUse	布尔型	启用写入临时文件。当设置为true时，查询可以将数据写入dbPath目录下的_tmp子目录。
allowPartialResults	布尔型	对于针对分片集合的查询，当某些分片不可用而不是抛出错误时，从mongos返回部分结果。
batchSize	整数	第一批次返回的文档数。默认为101。batchSize为0表示已建立游标，但第一批次不会返回任何文档。 与之前的线协议版本不同，对于find命令，batchSize为1不会关闭游标。
codec	MongoDB\Codec\DocumentCodec	...编解码器用于编码或解码文档。此选项与typeMap选项互斥。 默认为存储桶的编解码器。默认codec选项的继承优先于typeMap选项。 新功能版本1.17.
排序	数组|对象	排序允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定排序时，locale字段是必需的；所有其他排序字段都是可选的。有关字段的描述，请参阅排序文档。
注释	混合	启用用户指定任意注释，以帮助通过数据库分析器、当前操作输出和日志跟踪操作。 从MongoDB 4.4开始，注释可以是任何有效的BSON类型。早期服务器版本仅支持字符串值。
游标类型	整数	指示要使用的游标类型。cursorType支持以下值 MongoDB\Operation\Find::NON_TAILABLE （默认值） MongoDB\Operation\Find::TAILABLE
提示	字符串|数组|对象	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。 新功能版本1.2.
let	数组|对象	参数名称和值的映射。值必须是常量或封闭表达式，不能引用文档字段。然后可以在聚合表达式上下文中作为变量访问参数（例如 $$var）。 此功能不支持5.0之前的版本，并且如果在执行时使用，将引发异常。 新功能版本1.13.
limit	整数	返回的最大文档数。如果未指定，则默认为无限制。限制为0与设置无限制等效。 负限制类似于正限制，但会在返回一个结果批次后关闭游标。因此，在负限制的情况下，如果限制的结果集不适合单个批次，则接收到的文档数将少于指定的限制。通过传递负限制，客户端指示服务器它不会通过getMore请求后续批次。
max	数组|对象	特定索引的排它性上限。 新功能版本1.2.
maxAwaitTimeMS	整数	表示服务器阻塞getMore操作的时间限制（以毫秒为单位），如果无数据可用。此选项仅应在cursorType为TAILABLE_AWAIT时使用。 新功能版本1.2.
maxScan	整数	执行查询时扫描的最大文档或索引键数。 已弃用自版本1.4. 新功能版本1.2.
maxTimeMS	整数	处理光标操作的总时间限制（以毫秒为单位）。MongoDB会在最早的下一次中断点终止操作。
最小值	数组|对象	特定索引的包含下限。 新功能版本1.2.
修饰符	数组|对象	元操作符，用于修改查询的输出或行为。现在推荐使用命名选项代替这些操作符的使用。
noCursorTimeout	布尔型	防止服务器在空闲光标在一段时间（10分钟）后超时。
oplogReplay	布尔型	内部使用，用于副本集。要使用oplogReplay，必须在过滤器中包含以下条件 { ts: { $gte: <timestamp> } } MongoDB\BSON\Timestamp类参考描述了如何用PHP表示MongoDB的BSON时间戳类型。 已弃用自版本1.7.
投影	数组|对象	用于确定返回文档中包含哪些字段的投影规范。请参阅MongoDB手册中的从查询结果中投影字段和投影操作符。
readConcern	MongoDB\Driver\ReadConcern	用于操作的读取关注点。默认为桶的读取关注点。 在事务中无法为单个操作指定读取关注点。相反，在开始事务时设置readConcern选项。
readPreference	MongoDB\Driver\ReadPreference	读取偏好，用于操作。默认为桶的读取偏好。
returnKey	布尔型	如果为真，则只返回结果文档中的索引键。 新功能版本1.2.
session	MongoDB\Driver\Session	与操作关联的客户端会话。 新功能版本1.3.
showRecordId	布尔型	确定是否返回每个文档的记录标识符。如果为真，则在返回的文档中添加字段 $recordId。 新功能版本1.2.
skip	整数	要跳过的文档数量。默认为 0。
sort	数组|对象	结果的排序规范。
snapshot	布尔型	防止游标因中间的写操作而返回重复的文档。 已弃用自版本1.4. 新功能版本1.2.
typeMap	array	应用于游标的 类型映射，用于将 BSON 文档转换为 PHP 值。默认为桶的类型映射。

返回值

一个 MongoDB\Driver\Cursor 对象。

错误/异常

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

示例

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

输出结果将类似于

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

另见

• MongoDB\Collection::find()

• MongoDB\GridFS\Bucket::findOne()