Docs 菜单

MongoDB\Collection::find()

MongoDB\Collection::find()

查找与此查询匹配的文档。

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 不会关闭游标。

编解码器

MongoDB\Codec\DocumentCodec

用于对文档进行编码或解码的编解码器。 此选项与typeMap选项互斥。

默认为集合的编解码器。默认 codec 选项的继承优先于 typeMap 选项的继承。

1.17 版本中的新增功能

排序规则

数组|对象

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

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

comment

混合

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

评论可以是自 MongoDB 4.4 以来任何有效的 BSON 类型。早期服务器版本仅支持字符串值。

cursorType

整型

表示要使用的游标类型。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 最早会在中断点之后中止操作。

min

数组|对象

特定索引的包含下限。

版本 1.2 中的新增内容

modifiers

数组|对象

修改查询的输出或行为的元操作符。 这些操作符已弃用,建议使用命名选项。

noCursorTimeout

布尔

防止服务器在闲置期(10 分钟)后使空闲游标超时。

oplogReplay

布尔

针对副本集的内部用法。要使用 oplogReplay,您必须在筛选器中包含以下条件:

{ ts: { $gte: <timestamp> } }

MongoDB\BSON\Timestamp 类引用描述了如何使用 PHP 表示 MongoDB 的 BSON 时间戳类型。

自版本 1.7 起已弃用

投影

数组|对象

投影规范,用于确定要在返回的文档中包含哪些字段。 请参阅 MongoDB 手册中的从查询和 投影操作符 返回的项目字段 。

事务外的

读取关注以用于操作。 默认为集合的读关注。

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

readPreference

读取要用于操作的偏好。 默认为集合的读取偏好。

returnKey

布尔

如果为 true,则只返回结果文档中的索引键。

版本 1.2 中的新增内容

会话

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

1.3 版本中的新增功能

showRecordId

布尔

确定定是否返回每个文档的记录标识符。如果为 true,则在返回的文档中添加字段 $recordId

版本 1.2 中的新增内容

跳过

整型

要跳过的文档数量。默认值为 0

sort

数组|对象

对结果排序的排序规范。

snapshot

布尔

防止游标由于介入的写入操作而多次返回文档。

自版本 1.4 起已弃用

版本 1.2 中的新增内容

typeMap

阵列

类型映射 应用于游标,决定如何将 BSON 文档转换为 PHP 值。默认为集合的类型映射。

A MongoDB\ 驱动程序\Cursor 对象。

MongoDB\Exception\UnsupportedException,如果所选服务器使用了选项但不支持选项(例如collationreadConcernwriteConcern)。

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

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

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

以下示例根据cuisineborough字段查找餐馆,并使用投影来限制返回的字段。 它还将结果限制为5文档。

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$cursor = $collection->find(
[
'cuisine' => 'Italian',
'borough' => 'Manhattan',
],
[
'limit' => 5,
'projection' => [
'name' => 1,
'borough' => 1,
'cuisine' => 1,
],
]
);
foreach ($cursor as $restaurant) {
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"
}
}
object(MongoDB\Model\BSONDocument)#13 (1) {
["storage":"ArrayObject":private]=>
array(4) {
["_id"]=>
object(MongoDB\BSON\ObjectId)#12 (1) {
["oid"]=>
string(24) "576023c6b02fa9281da3f98d"
}
["borough"]=>
string(9) "Manhattan"
["cuisine"]=>
string(7) "Italian"
["name"]=>
string(18) "Marchis Restaurant"
}
}
object(MongoDB\Model\BSONDocument)#8 (1) {
["storage":"ArrayObject":private]=>
array(4) {
["_id"]=>
object(MongoDB\BSON\ObjectId)#10 (1) {
["oid"]=>
string(24) "576023c6b02fa9281da3f99b"
}
["borough"]=>
string(9) "Manhattan"
["cuisine"]=>
string(7) "Italian"
["name"]=>
string(19) "Forlinis Restaurant"
}
}
object(MongoDB\Model\BSONDocument)#12 (1) {
["storage":"ArrayObject":private]=>
array(4) {
["_id"]=>
object(MongoDB\BSON\ObjectId)#13 (1) {
["oid"]=>
string(24) "576023c6b02fa9281da3f9a8"
}
["borough"]=>
string(9) "Manhattan"
["cuisine"]=>
string(7) "Italian"
["name"]=>
string(22) "Angelo Of Mulberry St."
}
}
object(MongoDB\Model\BSONDocument)#10 (1) {
["storage":"ArrayObject":private]=>
array(4) {
["_id"]=>
object(MongoDB\BSON\ObjectId)#8 (1) {
["oid"]=>
string(24) "576023c6b02fa9281da3f9b4"
}
["borough"]=>
string(9) "Manhattan"
["cuisine"]=>
string(7) "Italian"
["name"]=>
string(16) "V & T Restaurant"
}
}