/ /

MongoDB\Collection::findOneAndUpdate()

定義

MongoDB\Collection::findOneAndUpdate()

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

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

パラメーター

$filter : array|object

更新するドキュメントを指定するフィルター条件。

$update : array|object

更新するフィールドと値の組み合わせと、関連する更新演算子を指定します。$update は MongoDB の更新演算子を使用します。このパラメーターとして集計パイプラインを渡すこともできます。

$options : 配列

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

名前	タイプ	説明
bypassDocumentValidation	ブール値	`true`の場合、書込み操作によってドキュメントレベルの検証を回避できます。デフォルトは`false`です。
arrayFilters	配列	配列フィールドの更新操作でどの配列要素を変更するかを決定するフィルタードキュメントの配列。バージョン1.3の新機能。
collation	array\|object	Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document. 照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。
comment	混合	データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバーバージョンで指定すると実行時に例外が発生します。バージョン1.13の新機能。
hint	string\|array\|object	使用するインデックス。インデックス名を string またはインデックスキーパターンをドキュメントとして指定します。指定すると、クエリシステムはヒント指定したインデックスを使用するプランのみを考慮します。このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバーバージョンで指定すると実行時に例外が発生します。バージョン1.7の新機能。
maxTimeMS	integer	カーソルに対する情報処理操作の累積時間制限（ミリ秒単位）。MongoDB は、割り込みポイントの後の最も早く操作を中止します。
let	array\|object	パラメーター名と値のマップ。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。その後、パラメーターには集計式コンテキストで変数としてアクセスできます（例: `$$var` ）。これは 5.0 より前のサーバーバージョンではサポートされていないため、使用された場合は実行時に例外が発生します。バージョン1.13の新機能。
プロジェクション	array\|object	返される文書に含めるフィールドを決定するためのプロジェクション仕様。 MongoDB マニュアルの「クエリ演算子およびプロジェクション演算子から返されるプロジェクトフィールド」を参照してください。
returnDocument	integer	アップデートを適用する前にドキュメントを返すか、アップデートを適用した後にドキュメントを返すかを指定します。 `returnDocument`は次の値をサポートしています。 `MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_BEFORE` （デフォルト） `MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER`
セッション	MongoDB\Driver\Session	操作に関連付けるクライアントセッション。バージョン1.3の新機能。
sort	array\|object	結果の順序の並び替え指定。
typeMap	配列	The type map to apply to cursors, which determines how BSON documents are converted to PHP values. Defaults to the collection's type map. これは返された結果ドキュメントに使用されます。
upsert	ブール値	`true`に設定すると、クエリ条件に一致するドキュメントがない場合に新しいドキュメントが作成されます。デフォルト値は`false`で、一致するものが見つからない場合は新しいドキュメントを挿入しません。
writeConcern	MongoDB\Driver\WriteConcern	操作に使用する書込み保証 ( write concern )。コレクションの書込み保証 (write concern) のデフォルトです。トランザクションの一部である個々の操作に対して書込み保証 (write concern)を指定することはできません。代わりに、トランザクションを開始するときに`writeConcern` オプションを設定します。

Return Values

returnDocumentオプションの指定値に応じて、元のドキュメントまたは更新されたドキュメントの配列またはオブジェクト。デフォルトでは、元のドキュメントが返されます。クエリに一致するドキュメントがない場合、 nullが返されます。戻り値の型は、 typeMapオプションによって異なります。

エラーと例外

MongoDB\Exception\UnexpectedValueException サーバーからのコマンド応答が不正な形式であった場合、。

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).

例

次の操作では、ビルド番号を"761"に設定して、 testデータベース内のrestaurantsコレクション内の"40361708"のrestaurant_idを持つレストランを更新します。

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updatedRestaurant = $collection->findOneAndUpdate(
    [ 'restaurant_id' => '40361708' ],
    [ '$set' => [ 'address.building' => '761' ]],
    [
        'projection' => [ 'address' => 1 ],
        'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER,
    ]
);
var_dump($updatedRestaurant);

出力は次のようになります。

object(MongoDB\Model\BSONDocument)#20 (1) {
  ["storage":"ArrayObject":private]=>
  array(2) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#12 (1) {
      ["oid"]=>
      string(24) "594d5ef280a846852a4b3dee"
    }
    ["address"]=>
    object(MongoDB\Model\BSONDocument)#19 (1) {
      ["storage":"ArrayObject":private]=>
      array(4) {
        ["building"]=>
        string(3) "761"
        ["coord"]=>
        object(MongoDB\Model\BSONArray)#18 (1) {
          ["storage":"ArrayObject":private]=>
          array(2) {
            [0]=>
            float(-73.9925306)
            [1]=>
            float(40.7309346)
          }
        }
        ["street"]=>
        string(8) "Broadway"
        ["zipcode"]=>
        string(5) "10003"
      }
    }
  }
}

その他の参照

MongoDB\Collection::findOneAndDelete()
MongoDB\Collection::findOneAndReplace()
MongoDB マニュアルのfindAndModifyコマンドに関する参考資料

戻る

FindOneAndReplace()

getCollectionName()