MongoDB\Collection::findOneAndReplace()
定義
パラメーター
$filter
: array|object- 置き換えるドキュメントを指定するフィルター条件。
$replacement
: array|object- 置換ドキュメントです。
$options
: 配列必要なオプションを指定する配列。
名前タイプ説明bypassDocumentValidationブール値true
の場合、書込み操作によってドキュメント レベルの検証を回避できます。 デフォルトはfalse
です。コーデックMongoDB\Codec\DocumentCodecドキュメントのエンコードまたはデコードに使用するコーデック。 このオプションは
typeMap
オプションと相互に排他的です。デフォルトはコレクションのコーデック。 デフォルトの
codec
オプションの継承は、typeMap
オプションの継承よりも優先されます。バージョン 1.17 の新機能。
collationarray|object照合順序を指定すると、大文字や小文字、アクセント記号など、string を比較するための言語独自のルールを指定できます。 照合を指定する場合、
locale
フィールドは必須です。その他の照合フィールドはすべてオプションです。 フィールドの説明については、 「照合ドキュメント」 を参照してください。照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。 コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。
comment混合データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。
このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバー バージョンで指定すると実行時に例外が発生します。
バージョン 1.13 の新機能。
hintstring|array|object使用するインデックス。 インデックス名を string またはインデックス キー パターンをドキュメントとして指定します。 指定すると、クエリ システムはヒント指定したインデックスを使用するプランのみを考慮します。
このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバー バージョンで指定すると実行時に例外が発生します。
バージョン 1.7 の新機能。
letarray|objectパラメーター名と値のマップ。 値は、ドキュメント フィールドを参照しない定数または閉じた式である必要があります。 その後、パラメーターには 集計式コンテキスト で変数としてアクセスできます(例:
$$var
)。これは 5.0 より前のサーバー バージョンではサポートされていないため、使用された場合は実行時に例外が発生します。
バージョン 1.13 の新機能。
maxTimeMSintegerカーソルに対する情報処理操作の累積時間制限(ミリ秒単位)。 MongoDB は、次の割り込みポイントが最も近い時点で操作を中止します。
プロジェクションarray|object返される文書に含めるフィールドを決定するためのプロジェクション仕様。 MongoDB マニュアルの「 クエリ 演算子および プロジェクション 演算子 から返されるプロジェクト フィールド 」を 参照してください。returnDocumentinteger置換が適用される前にドキュメントを返すか、置換を適用した後にドキュメントを返すかを指定します。
returnDocument
は次の値をサポートしています。MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE
(デフォルト)MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER
セッション操作に関連付けるクライアント セッション。
バージョン 1.3 で追加。
sortarray|object結果の順序の並び替え指定。typeMap配列型マップ カーソルに適用される 。これは、BSON ドキュメントが PHP 値に変換される方法を決定します。コレクションのタイプ マップがデフォルトになります。
これは返された結果ドキュメントに使用されます。
upsertブール値true
に設定すると、クエリ条件に一致するドキュメントがない場合に新しいドキュメントが作成されます。 デフォルト値はfalse
で、一致するものが見つからない場合は新しいドキュメントを挿入しません。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 拡張レベルのその他のエラー(例:)。
動作
クエリ条件を評価する際、MongoDB は BSON types の独自の比較ルール に従って型と値を比較します。これは PHP の 比較と は異なります と 型の調整 ルール。特殊な BSON 型と一致する場合、クエリ条件はそれぞれの BSON クラス を使用する必要があります 拡張機能(例:MongoDB\BSON \ObjectId ObjectIdを使用 )
例
test
データベース内の restaurants
コレクションにある次のドキュメントを検討してみましょう。
{ "_id" : ObjectId("576023c7b02fa9281da4139e"), "address" : { "building" : "977", "coord" : [ -74.06940569999999, 40.6188443 ], "street" : "Bay Street", "zipcode" : "10305" }, "borough" : "Staten Island", "cuisine" : "French", "grades" : [ { "date" : ISODate("2014-08-15T00:00:00Z"), "grade" : "A", "score" : 7 }, { "date" : ISODate("2014-02-13T00:00:00Z"), "grade" : "A", "score" : 5 }, { "date" : ISODate("2013-06-07T00:00:00Z"), "grade" : "A", "score" : 11 } ], "name" : "Zest", "restaurant_id" : "41220906" }
次の操作では、 "41220906"
のrestaurant_id
を持つドキュメントを新しいドキュメントに置き換えます。
$collection = (new MongoDB\Client)->teset->restaurants; $replacedRestaurant = $collection->findOneAndReplace( [ 'restaurant_id' => '41220906' ], [ 'Borough' => 'Staten Island', 'cuisine' => 'Italian', 'grades' => [], 'name' => 'Staten Island Pastaria', 'restaurant_id' => '999999999', ], [ 'returnDocument' => MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER ] ); var_dump($replacedRestaurant);
出力は次のようになります。
object(MongoDB\Model\BSONDocument)#18 (1) { ["storage":"ArrayObject":private]=> array(6) { ["_id"]=> object(MongoDB\BSON\ObjectId)#11 (1) { ["oid"]=> string(24) "594d5ef380a846852a4b5837" } ["Borough"]=> string(13) "Staten Island" ["cuisine"]=> string(7) "Italian" ["grades"]=> object(MongoDB\Model\BSONArray)#17 (1) { ["storage":"ArrayObject":private]=> array(0) { } } ["name"]=> string(22) "Staten Island Pastaria" ["restaurant_id"]=> string(9) "999999999" } }
その他の参照
MongoDB マニュアルのfindAndModifyコマンドに関する参考資料