MongoDB\Collection::findOne()

定義

MongoDB\Collection::findOne()

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

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

パラメーター

$filter : array|object

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

$options : 配列

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

名前	タイプ	説明
allowDiskUse	ブール値	一時ファイルへの書込みを有効にします。 trueに設定すると、クエリはdbPathディレクトリの_tmpサブディレクトリにデータを書込むことができます。
allowPartialResults	ブール値	シャーディングされたコレクションに対するクエリでは、エラーがスローされる代わりにシャードが使用できない場合に、mongos から部分的な結果を返します。
コーデック	MongoDB\Codec\DocumentCodec	ドキュメントのエンコードまたはデコードに使用する タイプ コーデック でデータをエンコードする。このオプションは typeMap オプションと相互に排他的です。 デフォルトはコレクションのコーデック。 デフォルトのcodecオプションの継承は、 typeMapオプションの継承よりも優先されます。 バージョン1.17の新機能。
collation	array|object	照合順序を指定すると、大文字や小文字、アクセント記号など、string を比較するための言語独自のルールを指定できます。照合を指定する場合、locale フィールドは必須です。その他の照合フィールドはすべてオプションです。フィールドの説明については、 「照合ドキュメント」 を参照してください。 照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。 コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。
comment	混合	データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。 コメントには、 MongoDB 4.4 以降の有効なBSONタイプであればどれでもかまいません。以前のサーバーバージョンでは string 値のみがサポートされていました。
hint	string|array|object	使用するインデックス。 インデックス名を string またはインデックス キー パターンをドキュメントとして指定します。 指定すると、クエリ システムはヒント指定したインデックスを使用するプランのみを考慮します。 バージョン1.2の新機能。
let	array|object	パラメーター名と値のマップ。 値は、ドキュメント フィールドを参照しない定数または閉じた式である必要があります。 その後、パラメーターには 集計式コンテキスト で変数としてアクセスできます（例: $$var ）。 これは 5.0 より前のサーバー バージョンではサポートされていないため、使用された場合は実行時に例外が発生します。 バージョン1.13の新機能。
最大	array|object	特定のインデックスの排他的上限。 バージョン1.2の新機能。
maxTimeMS	integer	カーソルに対する情報処理操作の累積時間制限（ミリ秒単位）。 MongoDB は、 割り込みポイントの後の最も早く操作を中止します。
min	array|object	特定のインデックスの包括的下限。 バージョン1.2の新機能。
プロジェクション	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

nullクエリに一致した最初のドキュメントの配列またはオブジェクト。クエリに一致するドキュメントがない場合は 。戻り値の型は、typeMap オプションによって異なります。

エラーと例外

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

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

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

動作

クエリ条件を評価する際、 MongoDB はBSON types の独自の比較ルールに従ってタイプと値を比較します。これは PHP の比較およびタイプの調整ルールとは異なります。特別なBSON type を照合する場合、クエリ条件は拡張機能内でそれぞれのBSONクラスを使用する必要があります（たとえば、 ObjectId と一致させるためにMongoDB\ BSON\ObjectId を使用するなど）。

例

<?php
$database = (new MongoDB\Client)->test;
$zip = $database->zips->findOne(['_id' => '10036']);
$restaurant = $database->restaurants->findOne([
    '_id' => new MongoDB\BSON\ObjectId('594d5ef280a846852a4b3f70'),
]);

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$restaurant = $collection->findOne(
    [
        'cuisine' => 'Italian',
        'borough' => 'Manhattan',
    ],
    [
        'projection' => [
            'name' => 1,
            'borough' => 1,
            'cuisine' => 1,
        ],
    ]
);
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"
  }
}

その他の参照

• MongoDB\Collection::find()

• MongoDB マニュアルのコマンド リファレンスの検索