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 不会关闭游标。
codec	MongoDB\Codec\DocumentCodec	用于编码或解码文档的codec。此选项与 typeMap 选项互斥。 默认为集合的 codec。默认 codec 选项的继承优先于 typeMap 选项。 新版本1.17.
collation	数组|对象	Collation 允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定 collation 时，locale 字段是必需的；所有其他 collation 字段都是可选的。有关字段的说明，请参阅 Collation Document. 如果未指定 collation 但集合有默认 collation，则操作使用为集合指定的 collation。如果集合或操作未指定 collation，MongoDB 使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	允许用户指定任意注释以帮助通过 数据库分析器、当前操作 输出和 日志 跟踪操作。 自 MongoDB 4.4 以来，注释可以是任何有效的 BSON 类型。早期服务器版本仅支持字符串值。
cursorType	整数	指示要使用的游标类型。cursorType 支持以下值 MongoDB\Operation\Find::NON_TAILABLE （默认值） MongoDB\Operation\Find::TAILABLE
hint	字符串|数组|对象	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。 新版本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.
projection	数组|对象	用于确定返回文档中应包含哪些字段的投影规范。请参阅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).

示例

以下示例根据 cuisine 和 borough 字段查找餐馆，并使用 投影 来限制返回的字段。它还限制了结果为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"
  }
}

另请参阅

• MongoDB\集合::findOne()

• find 命令参考 MongoDB 手册