Docs Menu
Docs Home
/ / /
PHP ライブラリ マニュアル
/ /

MongoDB\Collection::findOneAndReplace()

項目一覧

  • 定義
  • パラメーター
  • Return Values
  • エラーと例外
  • 動作
  • その他の参照
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

セッション

操作に関連付けるクライアント セッション。

バージョン 1.3 で追加

sort
array|object
結果の順序の並び替え指定。
typeMap
配列

型マップ カーソルに適用される 。これは、BSON ドキュメントが PHP 値に変換される方法を決定します。コレクションのタイプ マップがデフォルトになります。

これは返された結果ドキュメントに使用されます。

upsert
ブール値
trueに設定すると、クエリ条件に一致するドキュメントがない場合に新しいドキュメントが作成されます。 デフォルト値はfalseで、一致するものが見つからない場合は新しいドキュメントを挿入しません。
writeConcern

操作に使用する書込み保証 ( write concern )。 コレクションの書込み保証 (write concern) のデフォルトです。

トランザクションの一部である個々の操作に対して書込み保証 (write concern) を指定することはできません。 代わりに 、トランザクションを開始する ときにwriteConcern オプションを設定します。

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

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

MongoDB\Exception\UnsupportedExceptionオプションが使用され、選択したサーバーでサポートされていない場合(例: collationreadConcernwriteConcern )。

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を持つドキュメントを新しいドキュメントに置き換えます。

<?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"
}
}

戻る

FindOneAndDelete()