/ /

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	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の新機能。
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	配列	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).

例

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