一括書き込み操作

サンプル データ

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

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

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val stars: Int? = null,
)
data class Movie(
    val title: String,
    val year: Int,
    val seen: Boolean? = null,
)

挿入操作

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

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

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

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

アップデート操作

ドキュメントを更新するには、 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)

複数のドキュメントが UpdateOneModelインスタンスで指定されたクエリフィルターに一致する場合、この操作最初の結果が更新されます。次のコードに示すように、サーバーが更新操作を実行する前に、一致したドキュメントに順序を適用するために、UpdateOptionsインスタンスで並べ替えを指定できます。

val opts = UpdateOptions().sort(Sorts.ascending(Restaurant::name.name))

複数のドキュメントを更新するには、 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インスタンスで指定されたクエリフィルターに一致する場合、その操作は最初の結果を置き換えます。次のコードに示すように、サーバーが置換操作を実行する前に、一致したドキュメントに順序を適用するために、ReplaceOptionsインスタンスで並べ替えを指定できます。

val opts = ReplaceOptions().sort(Sorts.ascending(Restaurant::name.name))

削除操作

ドキュメントを削除するには、 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フィールドを提供し、例外に関する詳細を示します。

一括書き込み操作をカスタマイズする

オプションで、 bulkWrite()メソッドは、一括書き込み操作を構成するために使用できるオプションを指定する パラメーターを受け入れます。 オプションを指定しない場合、ドライバーはデフォルト設定で一括操作を実行します。

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

次のコードでは、オプションを作成し、 ordered(false)オプションを使用して順序なしの一括書き込みを指定します。 次に、この例ではbulkWrite()メソッドを使用して一括操作を実行します。

val opts = BulkWriteOptions().ordered(false)
collection.bulkWrite(bulkOperations, opts)

順序付けなし一括書き込み 内のいずれかの書き込み操作が失敗した場合、 Kotlin Sync ドライバーはすべての操作を試行した後にのみエラーを報告します。

戻り値

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

挿入操作

この例では、 2 つのドキュメントを挿入する指示を含むモデルを作成する方法を示しています。 1 つのドキュメントはsample_restaurants.restaurantsコレクションに挿入され、もう 1 つのドキュメントはsample_mflix.moviesコレクションに挿入されます。 MongoNamespaceインスタンスは、各書込み操作が適用されるターゲットデータベースとコレクションを定義します。

val restaurantToInsert = ClientNamespacedWriteModel
    .insertOne(
        MongoNamespace("sample_restaurants", "restaurants"),
        Restaurant("Blue Moon Grill", "Brooklyn", "American")
    )
val movieToInsert = ClientNamespacedWriteModel
    .insertOne(
        MongoNamespace("sample_mflix", "movies"),
        Movie("Silly Days", 2022)
    )

アップデート操作

次の例は、bulkWrite() メソッドを使用して、sample_restaurants.restaurants コレクションと sample_mflix.movies コレクション内の既存のドキュメントを更新する方法を示しています。

val restaurantUpdate = ClientNamespacedWriteModel
    .updateOne(
        MongoNamespace("sample_restaurants", "restaurants"),
        Filters.eq(Restaurant::name.name, "Villa Berulia"),
        Updates.inc(Restaurant::stars.name, 1)
    )
val movieUpdate = ClientNamespacedWriteModel
    .updateMany(
        MongoNamespace("sample_mflix", "movies"),
        Filters.eq(Movie::title.name, "Carrie"),
        Updates.set(Movie::seen.name, true)
    )

この例では、restaurantsコレクションで name 値が "Villa Berulia" であるドキュメントで、starsフィールドの値を 1 ずつ増加させます。また、moviesコレクション内で title 値が "Carrie" であるすべてのドキュメントの seenフィールドの値を true に設定します。

複数のドキュメントが ClientNamespacedUpdateOneModelインスタンスで指定されたクエリフィルターに一致する場合、この操作最初の結果が更新されます。次のコードに示すように、 ClientUpdateOneOptions インスタンスでソート順序を指定して、サーバーが更新操作を実行する前に一致したドキュメントに順序を適用できます。

val options =  ClientUpdateOneOptions
    .clientUpdateOneOptions()
    .sort(Sorts.ascending("_id"))

置換操作

次の例は、 sample_restaurants.restaurants コレクションと sample_mflix.movies コレクション内の既存のドキュメントを置き換えるためのモデルを作成する方法を示しています。

val restaurantReplacement = ClientNamespacedWriteModel
    .replaceOne(
        MongoNamespace("sample_restaurants", "restaurants"),
        Filters.eq("_id", 1),
        Restaurant("Smith Town Diner", "Brooklyn", "American")
    )
val movieReplacement = ClientNamespacedWriteModel
    .replaceOne(
        MongoNamespace("sample_mflix", "movies"),
        Filters.eq("_id", 1),
        Movie("Loving Sylvie", 1999)
    )

この例が正常に実行されると、restaurantsコレクション内の _id 値が 1 であるドキュメントは、新しいドキュメントに置き換えられます。_id 値が 1 である moviesコレクション内のドキュメントも、新しいドキュメントに置き換えられます。

複数のドキュメントが ClientNamespacedReplaceOneModelインスタンスで指定されたクエリフィルターに一致する場合、その操作は最初の結果を置き換えます。次のコードに示すように、ClientReplaceOneOptionsインスタンスでソート順序を指定して、ドライバーが置換操作を実行する前に一致したドキュメントに順序を適用できます。

val options =  ClientReplaceOneOptions
    .clientReplaceOneOptions()
    .sort(Sorts.ascending("_id"))

一括操作の実行

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

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

val restaurantNamespace = MongoNamespace("sample_restaurants", "restaurants")
val movieNamespace = MongoNamespace("sample_mflix", "movies")
val bulkOperations = listOf(
    ClientNamespacedWriteModel
        .insertOne(
            restaurantNamespace,
            Restaurant("Drea's", "Brooklyn", "Mexican")
        ),
    ClientNamespacedWriteModel
        .replaceOne(
            movieNamespace,
            Filters.eq("_id", 1),
            Movie("Underneath It All", 2002)
        )
)
val clientBulkResult = mongoClient
    .bulkWrite(bulkOperations)
println(clientBulkResult.toString())

AcknowledgedSummaryClientBulkWriteResult{insertedCount=1, matchedCount=1, ...}

書き込み操作のいずれかが失敗した場合、ドライバーは ClientBulkWriteException を発生させ、それ以上の個々の操作を実行しません。 ClientBulkWriteException には ClientBulkWriteException.getWriteErrors() メソッドを使用してアクセスできる BulkWriteError が含まれており、個々の障害の詳細が提供されます。

一括書き込みをカスタマイズする

ClientBulkWriteOptions のインスタンスをbulkWrite() メソッドに渡して、ドライバーが 一括書込み操作を実行する方法をカスタマイズできます。

val namespace = MongoNamespace("sample_restaurants", "restaurants")
val options = ClientBulkWriteOptions
    .clientBulkWriteOptions()
    .ordered(false)
val bulkOps = listOf(
    ClientNamespacedWriteModel.insertOne(
        namespace,
        Document("_id", 1).append("name", "Freezyland")
    ),
    // Causes a duplicate key error
    ClientNamespacedWriteModel.insertOne(
        namespace,
        Document("_id", 1).append("name", "Coffee Stand No. 1")
    ),
    ClientNamespacedWriteModel.insertOne<Any>(
        namespace,
        Document("name", "Kelly's Krepes")
    )
)
val result = mongoClient
    .bulkWrite(bulkOps, options)

API ドキュメント

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

• コレクションの一括書込み (write)

  • bulkWrite()

  • InsertOneModel

  • UpdateOneModel

  • UpdateManyModel

  • ReplaceOneModel

  • DeleteOneModel

  • DeleteManyModel

  • BulkWriteResult

  • BulkWriteError

  • MongoBulkWriteException

• クライアント一括書込み (write)

  • bulkWrite()

  • ClientNamespacedWriteModel

  • MongoNamespace

  • ClientBulkWriteOptions

  • ClientBulkWriteResult