MongoDB\Collection::find()

定義

MongoDB\Collection::find()

クエリに一致するドキュメントを検索します。

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

パラメーター

$filter : array|object

クエリするドキュメントを指定するフィルター条件。

$options : 配列

必要なオプションを指定する配列。

名前	タイプ	説明
allowDiskUse	ブール値	一時ファイルへの書込みを有効にします。 `true`に設定すると、クエリは`dbPath`ディレクトリの`_tmp`サブディレクトリにデータを書込むことができます。
allowPartialResults	ブール値	シャーディングされたコレクションに対するクエリでは、エラーがスローされる代わりにシャードが利用できない場合に、 `mongos`から部分的な結果を返します。
batchSize	integer	クエリ結果で返される各バッチする内のドキュメントの最大数。デフォルトでは、`find` コマンドの初期バッチするサイズは `101` ドキュメントで、後続の各バッチするの最大サイズは 16 メビバイト（MiB）です。このオプションを使用すると、16 MiB より小さい制限が適用できますが、超えることはありません。`batchSize` を、バッチが 16 MiB を超える制限に設定している場合、このオプションは効果がありません。 BatchSize が `0` の場合、カーソルは作成されますが、最初のバッチするではドキュメントは返されません。以前のワイヤプロトコルバージョンとは異なり、`find` コマンドの BatchSize が `1` の場合、カーソルは閉じられません。
コーデック	MongoDB\Codec\DocumentCodec	ドキュメントのエンコードまたはデコードに使用するは、タイプコーデックでデータをエンコードします。このオプションは `typeMap` オプションと相互に排他的です。デフォルトはコレクションのコーデック。デフォルトの`codec`オプションの継承は、 `typeMap`オプションの継承よりも優先されます。バージョン 1.17 の新機能。
collation	array\|object	照合順序を指定すると、大文字や小文字、アクセント記号など、string を比較するための言語独自のルールを指定できます。照合を指定する場合、 `locale`フィールドは必須です。その他の照合フィールドはすべてオプションです。フィールドの説明については、「照合ドキュメント」を参照してください。照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。
comment	混合	データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。コメントには、 MongoDB 4.4 以降の有効なBSONタイプであればどれでもかまいません。以前のサーバーバージョンでは string 値のみがサポートされていました。
cursorType	integer	使用するカーソルのタイプを示します。 `cursorType`は次の値をサポートしています。 `MongoDB\Operation\Find::NON_TAILABLE` （デフォルト） `MongoDB\Operation\Find::TAILABLE`
hint	string\|array\|object	使用するインデックス。インデックス名を string またはインデックスキーパターンをドキュメントとして指定します。指定すると、クエリシステムはヒント指定したインデックスを使用するプランのみを考慮します。バージョン 1.2 の新機能.
let	array\|object	パラメーター名と値のマップ。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。その後、パラメーターには集計式コンテキストで変数としてアクセスできます（例: `$$var` ）。これは 5.0 より前のサーバーバージョンではサポートされていないため、使用された場合は実行時に例外が発生します。バージョン 1.13 の新機能。
limit	integer	返されるドキュメントの最大数。指定しない場合、デフォルトは制限なしになります。 `0`の制限は、制限を設定しない場合と同じです。負の制限は正の制限と似ていますが、1バッチするの結果が返された後にカーソルを閉じます。そのため、負の制限では、制限された結果セットが単一のバッチするに収まらない場合、受信されるドキュメントの数は指定された制限よりも少なくなります。負の制限を渡すことにより、クライアントサーバーに getMore を使用して後続のバッチする要求が実行されないことが伝えられます。
最大	array\|object	特定のインデックスの排他的上限。バージョン 1.2 の新機能.
maxAwaitTimeMS	integer	データが利用できない場合にサーバーがgetMore操作をブロックする時間の制限をミリ秒単位で示す正の整数。このオプションは、 cursorType が `TAILABLE_AWAIT` の場合にのみ使用する必要があります。バージョン 1.2 の新機能.
maxTimeMS	integer	カーソルに対する情報処理操作の累積時間制限（ミリ秒単位）。 MongoDB は、次の割り込みポイントが最も近い時点で操作を中止します。
min	array\|object	特定のインデックスの包括的下限。バージョン 1.2 の新機能.
noCursorTimeout	ブール値	非アクティブ期間（10 分）後にサーバーがアイドルカーソルをタイムアウトしないようにします。
プロジェクション	array\|object	返される文書に含めるフィールドを決定するためのプロジェクション仕様。 MongoDB マニュアルの「クエリ演算子およびプロジェクション演算子から返されるプロジェクトフィールド」を参照してください。
ReadConcern	MongoDB\Driver\ReadConcern	操作に使用する読み取り保証。デフォルトはコレクションの読み取り保証 (read concern) です。トランザクションの一部である個々の操作に対して読み取り保証 (read concern)を指定することはできません。代わりに、トランザクションを開始するときに`readConcern` オプションを設定します。
readPreference	MongoDB\Driver\ReadPreference	操作に使用する読み取り設定。コレクションの読み込み設定（read preference）がデフォルトで設定されます。
returnKey	ブール値	trueの場合、結果のドキュメントに含まれるインデックスキーのみを返します。バージョン 1.2 の新機能.
セッション	MongoDB\Driver\Session	操作に関連付けるクライアントセッション。バージョン 1.3 で追加。
showRecordId	ブール値	各ドキュメントのレコード識別子を返すかどうかを決定します。 true の場合、返されるドキュメントにフィールド`$recordId`が追加されます。バージョン 1.2 の新機能.
スキップ	integer	スキップするドキュメントの数。デフォルトは `0` です。
sort	array\|object	結果の順序の並び替え指定。
typeMap	配列	カーソルに適用するタイプマップ。BSON ドキュメントをPHP値に変換する方法を決定します。コレクションのタイプマップがデフォルトになります。

Return Values

MongoDBDriver\Cursorオブジェクト。

エラーと例外

MongoDB\Exception\UnsupportedExceptionオプションが使用され、選択したサーバーでサポートされていない場合（例: collation 、 readConcern 、 writeConcern ）。

MongoDB\Exception\InvalidArgumentException は、パラメータまたはオプションの解析に関連するエラーの場合はです。

MongoDB$Driver\Exception\RuntimeException は、拡張レベルの他のエラーの場合（例:）。

動作

クエリ条件を評価する際、 MongoDB はBSON types の独自の比較ルールに従ってタイプと値を比較します。これは PHP の比較および型調整ルールとは異なります。特別な BSON type を照合する場合、BSONクラスは拡張機能（例:）。（ ObjectId を一致させるためにMongoDB$ BSON$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\Collection::findOne()
MongoDB マニュアルのコマンドリファレンスの検索

戻る

explain()

findOne()