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 タイプであればコメントに、任意の有効な BSON タイプ を使用できます。 以前のサーバー バージョンでは string 値のみがサポートされていました。
hint	string|array|object	使用するインデックス。 インデックス名を string またはインデックス キー パターンをドキュメントとして指定します。 指定すると、クエリ システムはヒント指定したインデックスを使用するプランのみを考慮します。 バージョン 1.2 の新機能.
let	array|object	パラメーター名と値のマップ。 値は、ドキュメント フィールドを参照しない定数または閉じた式である必要があります。 その後、パラメーターには 集計式コンテキスト で変数としてアクセスできます（例: $$var ）。 これは 5.0 より前のサーバー バージョンではサポートされていないため、使用された場合は実行時に例外が発生します。 バージョン 1.13 の新機能。
最大	array|object	特定のインデックスの排他的上限。 バージョン 1.2 の新機能.
maxScan	integer	クエリを実行するときにスキャンするドキュメントまたはインデックス キーの最大数。 バージョン 1.4 以降非推奨。 バージョン 1.2 の新機能.
maxTimeMS	integer	カーソルに対する情報処理操作の累積時間制限（ミリ秒単位）。 MongoDB は、次の割り込みポイントが最も近い時点で操作を中止します。
min	array|object	特定のインデックスの包括的下限。 バージョン 1.2 の新機能.
modifiers	array|object	クエリの出力または動作を変更するメタ演算子。 これらの演算子の使用は非推奨となり、代わりに名前付きオプションが使用されます。
oplogRePlay	ブール値	レプリカセットの内部使用。 oplogReplayを使用するには、フィルターに次の条件を含める必要があります。 { ts: { $gte: <timestamp> } } MongoDB\BSON\Timestamp クラス参照は、MongoDB の BSON タイムスタンプ型を PHP で表現する方法を説明します。 バージョン 1.7 以降非推奨。
プロジェクション	array|object	返される文書に含めるフィールドを決定するためのプロジェクション仕様。 MongoDB マニュアルの「 クエリ 演算子および プロジェクション 演算子 から返されるプロジェクト フィールド 」を 参照してください。
ReadConcern	MongoDB\Driver\ReadConcern	操作に使用する読み取り保証。 デフォルトはコレクションの読み取り保証 (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 型と一致する場合、クエリ条件はそれぞれの BSON クラス を使用する必要があります 拡張機能（例:MongoDB\BSON \ObjectId 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 マニュアルのコマンド リファレンスの検索