/ /

ドキュメントの置換

Overview

このガイドでは、 Kotlin Sync ドライバーを使用して MongoDB コレクション内のドキュメントに対して置換操作を実行する方法を学習します。置換操作を実行すると、指定されたドキュメントから_idフィールドを除くすべてのフィールドと値が削除され、指定した新しいフィールドと値が追加されます。この操作は、1 つ以上のドキュメントの指定されたフィールドのみを変更する更新操作とは異なります。

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

サンプルデータ

このガイドの例では、Atlas サンプルデータセットの sample_restaurants.restaurants コレクションを使用します。無料の MongoDB 配置を作成し、サンプルデータセットを読み込む方法については、MongoDB のスタートガイドを参照してください。

このコレクション内のドキュメントは、次の Kotlin データクラスによってモデル化されます。

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val owner: String?,
)

置換操作

MongoDB では、 replaceOne()メソッドを使用して置換操作を実行できます。このメソッドは、クエリフィルターに一致する最初のドキュメントから_idフィールドを除くすべてのフィールドを削除します。次に、指定したフィールドと値を空のドキュメントに追加します。

必要なパラメーター

次のパラメータをreplaceOne()メソッドに渡す必要があります。

クエリフィルター。アップデートするドキュメントに一致する。クエリフィルターの詳細については、「クエリの指定」ガイドを参照してください。
置換ドキュメント。既存のフィールドと値を置き換えるフィールドと値を指定します。

1 つのドキュメントの置換

次の例では、 replaceOne()メソッドを使用して、 nameフィールドの値が"Primola Restaurant"であるドキュメントのフィールドと値を置き換えます。

val filter = Filters.eq(Restaurant::name.name, "Primola Restaurant")
val replacement = Restaurant(
    "Frutti Di Mare",
    "Queens",
    "Seafood",
    owner = "Sal Thomas"
)
val result = collection.replaceOne(filter, replacement)

重要

_idフィールドの値は不変です。置き換えドキュメントで_idフィールドの値を指定する場合、既存のドキュメントの_id値と同じである必要があります。そうでない場合、ドライバーはWriteErrorを発生させます。

置換操作をカスタマイズする

replaceOne()メソッドはオプションで、置換操作を構成するためのオプションを設定するパラメーターを受け入れます。オプションを指定しない場合、ドライバーはデフォルト設定で置換操作を実行します。

次の表では、 ReplaceOptionsインスタンスを構成するために使用できる setter メソッドについて説明します。

プロパティ	説明
`upsert()`	クエリフィルターに一致するドキュメントがない場合に、置換操作でアップサート操作を実行するかどうかを指定します。詳細については、 MongoDB Serverマニュアルの「アップサートの動作」を参照してください。デフォルトは `false`
`sort(Bson sort)`	操作に適用するソート基準を設定します。 `replaceOne()` メソッドに渡すクエリフィルターに複数のドキュメントが一致する場合、その操作は最初の結果を置き換えます。このオプションをに設定すると、一致したドキュメントに順序を適用し、置き換えられるドキュメントをより詳細に制御できます。
`bypassDocumentValidation()`	アップデート操作がドキュメント検証をバイパスするかどうかを指定します。これにより、スキーマ検証要件を満たさないドキュメントを更新することができます（存在する場合）。スキーマ検証の詳細については、 MongoDB Serverマニュアルの「スキーマバリデーション」を参照してください。デフォルトは `false`です。
`collation()`	結果をソートするときに使用する言語照合の種類を指定します。詳細については、MongoDB Server マニュアルの「照合」を参照してください。
`hint()`	ドキュメントをマッチングするときに使用するインデックスを設定します。詳細については、 MongoDB Serverマニュアルのヒントステートメントを参照してください。
`let()`	操作の最上位変数を設定するためのパラメーター名と値のマップを提供します。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。
`comment()`	操作に添付するコメントを設定します。

次のコードでは、 upsertオプションをtrueに設定します。これは、クエリフィルターが既存のドキュメントと一致しない場合に、置換ドキュメントで指定されたフィールドと値を持つ新しいドキュメントを挿入するようにドライバーに指示します。

val opts = ReplaceOptions().upsert(true)
val result = collection.replaceOne(filter, replacement, opts)

戻り値

replaceOne()メソッドはUpdateResultオブジェクトを返します。 UpdateResultインスタンスからの情報にアクセスするには、次のメソッドを使用できます。

プロパティ	説明
`getMatchedCount()`	アップデートが実行された回数に関係なく、クエリフィルターに一致したドキュメントの数を返します。
`getModifiedCount()`	更新操作によって変更されたドキュメントの数を返します。更新されたドキュメントが元と同一の場合、このカウントには含まれません。
`wasAcknowledged()`	サーバーが結果を確認した場合は `true` を返します。
`getUpsertedId()`	ドライバーがアップサートを実行した場合、データベースでアップサートされたドキュメントの `_id` 値を返します。

詳細情報

ドキュメントを置き換える方法を示す実行可能なコード例については、ドキュメントの挿入を参照してください。

API ドキュメント

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

戻る

Update Documents

Delete Documents