MongoDB\Collection::findOneAndReplace()

定義

MongoDB\Collection::findOneAndReplace()

クエリに一致する単一のドキュメントを検索して置き換えます。

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

パラメーター

$filter : array|object

置き換えるドキュメントを指定するフィルター条件。

$replacement : array|object

置換ドキュメントです。

$options : 配列

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

名前	タイプ	説明
bypassDocumentValidation	ブール値	`true`の場合、書込み操作によってドキュメントレベルの検証を回避できます。デフォルトは`false`です。
コーデック	MongoDB\Codec\DocumentCodec	ドキュメントのエンコードまたはデコードに使用するは、タイプコーデックでデータをエンコードします。このオプションは `typeMap` オプションと相互に排他的です。デフォルトはコレクションのコーデック。デフォルトの`codec`オプションの継承は、 `typeMap`オプションの継承よりも優先されます。バージョン 1.17 の新機能。
collation	array\|object	照合順序を指定すると、大文字や小文字、アクセント記号など、string を比較するための言語独自のルールを指定できます。照合を指定する場合、 `locale`フィールドは必須です。その他の照合フィールドはすべてオプションです。フィールドの説明については、「照合ドキュメント」を参照してください。照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。
comment	混合	データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバーバージョンで指定すると実行時に例外が発生します。バージョン 1.13 の新機能。
hint	string\|array\|object	使用するインデックス。インデックス名を string またはインデックスキーパターンをドキュメントとして指定します。指定すると、クエリシステムはヒント指定したインデックスを使用するプランのみを考慮します。このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバーバージョンで指定すると実行時に例外が発生します。バージョン 1.7 の新機能。
let	array\|object	パラメーター名と値のマップ。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。その後、パラメーターには集計式コンテキストで変数としてアクセスできます（例: `$$var` ）。これは 5.0 より前のサーバーバージョンではサポートされていないため、使用された場合は実行時に例外が発生します。バージョン 1.13 の新機能。
maxTimeMS	integer	カーソルに対する情報処理操作の累積時間制限（ミリ秒単位）。 MongoDB は、次の割り込みポイントが最も近い時点で操作を中止します。
プロジェクション	array\|object	返される文書に含めるフィールドを決定するためのプロジェクション仕様。 MongoDB マニュアルの「クエリ演算子およびプロジェクション演算子から返されるプロジェクトフィールド」を参照してください。
returnDocument	integer	置換が適用される前にドキュメントを返すか、置換を適用した後にドキュメントを返すかを指定します。 `returnDocument`は次の値をサポートしています。 `MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE` （デフォルト） `MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER`
セッション	MongoDB\Driver\Session	操作に関連付けるクライアントセッション。バージョン 1.3 で追加。
sort	array\|object	結果の順序の並び替え指定。
typeMap	配列	カーソルに適用するタイプマップ。BSON ドキュメントをPHP値に変換する方法を決定します。コレクションのタイプマップがデフォルトになります。これは返された結果ドキュメントに使用されます。
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 。

動作

クエリ条件を評価する際、 MongoDB はBSON types の独自の比較ルールに従ってタイプと値を比較します。これは PHP の比較および型調整ルールとは異なります。特別なBSON type を照合する場合、クエリ条件は拡張機能内でそれぞれのBSONクラスを使用する必要があります（たとえば、 ObjectId と一致させるためにMongoDB\ BSON\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を持つドキュメントを新しいドキュメントに置き換えます。

<?php
$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\Collection::findOneAndDelete()
MongoDB\Collection::findOneAndUpdate()
MongoDB マニュアルのfindAndModifyコマンドに関する参考資料

戻る

FindOneAndDelete()

findOneAndUpdate()