/ /

ドキュメントの置換

Overview

このガイドでは、 MongoDB PHPライブラリを使用してMongoDBコレクションに対して置換操作を実行する方法を学習できます。置換操作は更新操作とは異なります。アップデート操作により、ターゲットドキュメント内の指定されたフィールドのみが変更されます。置換操作により、ターゲットドキュメント内のすべてのフィールドが削除され、新しいフィールドに置き換えられます。

ドキュメントを置き換えるには、 MongoDB\Collection::replaceOne()メソッドを使用します。

サンプルデータ

このガイドの例では、 Atlasサンプルデータセットのsample_restaurantsデータベースのrestaurantsコレクションを使用します。 PHPアプリケーションからこのコレクションにアクセスするには、Atlas クラスターに接続するMongoDB\Clientをインスタンス化し、次の値を$collection変数に割り当てます。

$collection = $client->sample_restaurants->restaurants;

MongoDB配置を作成し、サンプルデータセットをロードする方法については、MongoDBの使用開始ガイドを参照してください。

置換操作

MongoDB\Collection::replaceOne()を使用して置換操作を実行できます。このメソッドは、検索条件に一致する最初のドキュメントから_idフィールドを除くすべてのフィールドを削除します。次に、指定したフィールドと値がドキュメントに挿入されます。

必要なパラメーター

replaceOne() メソッドには次のパラメーターが必要です。

クエリフィルタードキュメント。置き換えるドキュメントを決定します。クエリフィルターの詳細については、 MongoDB Serverマニュアルの「クエリフィルタードキュメント」セクションを参照してください。
新しいドキュメントに挿入するフィールドと値を指定するドキュメントを置き換えます。

戻り値

replaceOne()メソッドはMongoDB\UpdateResultオブジェクトを返します。 MongoDB\UpdateResult型には次のメソッドが含まれています。

方式	説明
`getMatchedCount()`	アップデートされた数に関係なく、クエリフィルターに一致したドキュメントの数を返します。
`getModifiedCount()`	更新操作によって変更されたドキュメントの数を返します。更新されたドキュメントが元と同一の場合、このカウントには含まれません。
`getUpsertedCount()`	データベースにアップサートされたドキュメントの数を返します（存在する場合）。
`getUpsertedId()`	ドライバーがアップサートを実行した場合、データベースでアップサートされたドキュメントのIDを返します。
`isAcknowledged()`	サーバーが書き込み (write) 操作を認識したかどうかを示すブール値を返します。

例

次の例では、 replaceOne()メソッドを使用して、 nameフィールド値が'Pizza Town'であるドキュメントのフィールドと値を置き換えます。次に、変更されたドキュメントの数を出力します。

$replaceDocument = [
    'name' => 'Mongo\'s Pizza',
    'cuisine' => 'Pizza',
    'address' => [
        'street' => '123 Pizza St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan',
];
$result = $collection->replaceOne(['name' => 'Pizza Town'], $replaceDocument);
echo 'Modified documents: ', $result->getModifiedCount();

Modified documents: 1

重要

_idフィールドの値は不変です。置き換えドキュメントで_idフィールドに値が指定される場合は、既存のドキュメントの_id値と一致する必要があります。

置換操作の変更

オプション値を指定する配列をパラメーターとして渡すことで、 MongoDB\Collection::replaceOne()メソッドの動作を変更できます。次の表では、配列に設定できるオプションの一部を説明しています。

オプション	説明
`upsert`	クエリフィルターに一致するドキュメントがない場合に、置換操作でアップサート操作を実行するかどうかを指定します。詳細については、MongoDB Server マニュアルのアップサートステートメントを参照してください。デフォルトは `false` です。
`bypassDocumentValidation`	置換操作がドキュメント検証をバイパスするかどうかを指定します。これにより、スキーマ検証要件を満たしていないドキュメントが存在する場合は、それを置き換えることができます。スキーマ検証の詳細については、MongoDB Server マニュアルの「スキーマ検証」を参照してください。デフォルト値は `false` です。
`sort`	置換操作を実行する前にドキュメントに適用するソート順序を指定します。
`collation`	結果をソートするときに使用する言語照合の種類を指定します。詳細を学ぶには、このページの照合セクションを参照してください。
`hint`	ドキュメントをスキャンするインデックスを取得または設定します。詳細については、MongoDB Server マニュアルのヒントステートメントを参照してください。
`session`	操作に関連付けるクライアントセッションを指定します。
`let`	操作の読みやすさを向上させるために、の値のリストを含むドキュメントを指定します。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。詳細については、 MongoDB Serverマニュアルの let ステートメントを参照してください。
`comment`	操作にコメントを付けます。詳細については、 MongoDB Serverマニュアルの「挿入コマンドフィールドのガイド」を参照してください。

照合

操作の照合を指定するには、collation オプションを設定する $options 配列パラメータを操作メソッドに渡します。照合ルールを構成する配列に collation オプションを割り当てます。

次の表では、照合を構成するために設定できるフィールドについて説明しています。

フィールド	説明
`locale`	(必須) International Components for Unicode (ICU) ロケールを指定します。サポートされているロケールの一覧については、MongoDB Server マニュアルの「照合ロケールとデフォルトパラメータ」を参照してください。データ型: `string`
`caseLevel`	(任意) 大文字と小文字の比較を含めるかどうかを指定します。 `truestrength`に設定すると、比較の動作は `strength1` フィールドの値に応じて変わります。 - がの場合、PHP ライブラリは基本文字と大文字と小文字を比較します。 -`strength` が`2` の場合、PHP ライブラリは基本文字、分音符号、その他のセカンダリの違い、および大文字と小文字を比較します。 -`strength` がその他の値の場合、このフィールドは無視されます。 `false` に設定すると、PHP ライブラリは強度レベル `1` または `2` での大文字と小文字の比較を含めません。データ型: `bool` デフォルト: `false`
`caseFirst`	(任意) 三次レベルの比較中の大文字と小文字の相違のソート順序を指定します。データ型: `string` デフォルト: `"off"`
`strength`	(任意) ICU ドキュメントで定義されている、実行する比較のレベルを指定します。データ型: `int` デフォルト: `3`
`numericOrdering`	(任意) ドライバーが数字の文字列を数値として比較するかどうかを指定します。 `true` に設定すると、PHP ライブラリは数字の文字列を数値として比較します。例えば、文字列「10」と「2」を比較する場合、ライブラリは文字列の数値を使用し、「10」を「2」より大きいとして処理します。 `false`に設定すると、PHP ライブラリは数値型の文字列を文字列として比較します。例えば、文字列 "10" と "2" を比較する場合、ライブラリは 1 文字ずつ比較し、"10" を "2" より小さいとして取り扱います。詳細については、MongoDB Server マニュアルの「照合制限」を参照してください。データ型: `bool` デフォルト: `false`
`alternate`	(任意) ライブラリが空白と句読点を比較目的の基本文字として考慮するかどうかを指定します。データ型: `string` デフォルト: `"non-ignorable"`
`maxVariable`	(任意) `alternate` フィールドが `"shifted"` に設定されている場合、ライブラリが無視できる文字を指定します。データ型: `string` デフォルト: `"punct"`
`backwards`	(任意) 発音区別符号を含む string を、string の後ろから前にソートするかどうかを指定します。データ型: `bool` デフォルト: `false`

照合と各フィールドに可能な値の詳細については、 MongoDB Serverマニュアルの「照合」エントリを参照してください。

例

次のコードでは、 replaceOne()メソッドを使用して、 nameフィールドの値が'Food Town'である最初のドキュメントを検索し、このドキュメントをnameの値が'Food World'である新しいドキュメントに置き換えます。 upsertオプションがtrueに設定されているため、クエリフィルターが既存のドキュメントと一致しない場合、ライブラリは新しいドキュメントを挿入します。

$replaceDocument = [
    'name' => 'Food World',
    'cuisine' => 'Mixed',
    'address' => [
        'street' => '123 Food St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan',
];
$result = $collection->replaceOne(
    ['name' => 'Food Town'],
    $replaceDocument,
    ['upsert' => true],
);

詳細情報

アップデート操作の詳細については、ドキュメントのアップデートガイドを参照してください。

クエリフィルターの作成の詳細については、「クエリの指定」ガイドを参照してください。

API ドキュメント

このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。

戻る

Update Documents

Delete Documents