一括書き込み操作

項目一覧

Overview

サンプルデータ
書込み (write) 操作を定義する
挿入操作
アップデート操作
置換操作
削除操作
一括操作の実行
一括書き込み操作をカスタマイズする
戻り値
詳細情報
API ドキュメント

Overview

このガイドでは、 Kotlin Sync ドライバーを使用して、1 回のデータベース呼び出しでデータに複数の変更を加える一括書き込み操作を実行する方法について説明します。

同じタスクでドキュメントの挿入、ドキュメントの更新、ドキュメントの削除が必要になる状況を考えてみましょう。個別の書込みメソッドを使用して各タイプの操作を実行すると、各書込みはデータベースに個別にアクセスします。一括書き込み操作を使用して、アプリケーションがサーバーに行う呼び出しの数を最適化できます。

サンプルデータ

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

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

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

書込み (write) 操作を定義する

実行する書込み操作ごとに、汎用のWriteModelクラスから継承する次の操作クラスのいずれかの対応するインスタンスを作成します。

InsertOneModel
UpdateOneModel
UpdateManyModel
ReplaceOneModel
DeleteOneModel
DeleteManyModel

次に、これらのインスタンスのリストをbulkWrite()メソッドに渡します。

次のセクションでは、前述のクラスのインスタンスを作成して使用する方法を示します。「一括操作の実行」セクションでは、モデルのリストをbulkWrite()メソッドに渡して一括操作を実行する方法が説明されています。

挿入操作

挿入操作を実行するには、 InsertOneModelインスタンスを作成し、挿入するドキュメントを指定します。

次の例では、 InsertOneModelのインスタンスを作成しています。

val blueMoon = InsertOneModel(Restaurant("Blue Moon Grill", "Brooklyn", "American"))

複数のドキュメントを挿入するには、ドキュメントごとにInsertOneModelのインスタンスを作成します。

重要

一括操作を実行する場合、 InsertOneModelはコレクション内にすでに存在する_idを含むドキュメントを挿入できません。この状況では、ドライバーはMongoBulkWriteExceptionをスローします。

アップデート操作

ドキュメントを更新するには、 UpdateOneModelのインスタンスを作成し、次の引数を渡します。

コレクション内のドキュメントを照合するために使用される基準を指定するクエリフィルター
実行する更新操作。更新操作の詳細については、MongoDB Server マニュアルの「フィールド更新演算子」ガイドを参照してください。

UpdateOneModelインスタンスは、クエリフィルターに一致する最初のドキュメントの更新を指定します。

次の例では、 UpdateOneModelのインスタンスを作成しています。

val updateOneFilter = Filters.eq(Restaurant::name.name, "White Horse Tavern")
val updateOneDoc = Updates.set(Restaurant::borough.name, "Queens")
val tavernUpdate = UpdateOneModel<Restaurant>(updateOneFilter, updateOneDoc)

複数のドキュメントを更新するには、 UpdateManyModelのインスタンスを作成し、 UpdateOneModelと同じ引数を渡します。 UpdateManyModelクラスは、クエリフィルターに一致するすべてのドキュメントのアップデートを指定します。

次の例では、 UpdateManyModelのインスタンスを作成しています。

val updateManyFilter = Filters.eq(Restaurant::name.name, "Wendy's")
val updateManyDoc = Updates.set(Restaurant::cuisine.name, "Fast food")
val wendysUpdate = UpdateManyModel<Restaurant>(updateManyFilter, updateManyDoc)

置換操作

置換操作により、指定されたドキュメントのすべてのフィールドと値が削除され、指定した新しいフィールドと値に置き換えられます。置換操作を実行するには、 ReplaceOneModelのインスタンスを作成し、クエリフィルターと、一致するドキュメントを置き換えるフィールドと値を渡します。

次の例では、 ReplaceOneModelのインスタンスを作成しています。

val replaceFilter = Filters.eq(Restaurant::name.name, "Cooper Town Diner")
val replaceDoc = Restaurant("Smith Town Diner", "Brooklyn", "American")
val replacement = ReplaceOneModel(replaceFilter, replaceDoc)

複数のドキュメントを置き換えるには、ドキュメントごとにReplaceOneModelのインスタンスを作成する必要があります。

削除操作

ドキュメントを削除するには、 DeleteOneModelのインスタンスを作成し、削除するドキュメントを指定するクエリフィルターを渡します。 DeleteOneModelインスタンスには、クエリフィルターに一致する最初のドキュメントのみを削除するための手順が記載されています。

次の例では、 DeleteOneModelのインスタンスを作成しています。

val deleteOne = DeleteOneModel<Restaurant>(Filters.eq(
    Restaurant::name.name,
    "Morris Park Bake Shop"
))

複数のドキュメントを削除するには、 DeleteManyModelのインスタンスを作成し、削除するドキュメントを指定してクエリフィルターを渡します。 DeleteManyModelのインスタンスには、クエリフィルターに一致するすべてのドキュメントを削除するための手順が表示されます。

次の例では、 DeleteManyModelのインスタンスを作成しています。

val deleteMany = DeleteManyModel<Restaurant>(Filters.eq(
    Restaurant::cuisine.name,
    "Experimental"
))

一括操作の実行

実行する操作ごとにモデルインスタンスを定義した後、これらのインスタンスのリストをbulkWrite()メソッドに渡します。デフォルトでは、メソッドはモデルのリストで指定された順序で操作を実行します。

次の例では、 bulkWrite()メソッドを使用して複数の書込み操作を実行します。

val insertOneMdl = InsertOneModel(Restaurant("Red's Pizza", "Brooklyn", "Pizzeria"))
val updateOneMdl = UpdateOneModel<Restaurant>(
    Filters.eq(Restaurant::name.name, "Moonlit Tavern"),
    Updates.set(Restaurant::borough.name, "Queens")
)
val deleteManyMdl = DeleteManyModel<Restaurant>(
    Filters.eq(Restaurant::name.name, "Crepe")
)
val bulkResult = collection.bulkWrite(
    listOf(insertOneMdl, updateOneMdl, deleteManyMdl)
)
println(bulkResult)

AcknowledgedBulkWriteResult{insertedCount=1, matchedCount=5, removedCount=3,
modifiedCount=2, upserts=[], inserts=[BulkWriteInsert{index=0,
id=BsonObjectId{value=...}}]}

書き込み操作のいずれかが失敗した場合、 Kotlin Sync ドライバーはBulkWriteErrorを発生させ、それ以上の操作を実行しません。 BulkWriteErrorは、失敗した操作を含むdetailsアイテムと例外に関する詳細を提供します。

注意

ドライバーが一括操作を実行する場合、ターゲットコレクションの書込み保証 (write concern) が使用されます。ドライバーは、実行順序に関係なく、すべての操作を試行した後にすべての書込み保証 (write concern) エラーを報告します。