批量写入操作

样本数据

本指南中的示例使用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 同步驱动程序都会引发 BulkWriteError，并且不会执行任何进一步的操作。BulkWriteError 提供了一个 details字段，其中包括失败的操作以及有关异常的详细信息。

自定义批量写入操作

bulkWrite() 方法可以选择接受一个参数，该参数指定可用于配置批量写入操作的选项。如果不指定任何选项，驱动程序将使用默认设置执行批量操作。

下表描述了可用于配置BulkWriteOptions实例的 setter 方法：

以下代码创建选项并使用ordered(false)选项指定无序批量写入。 然后，该示例使用bulkWrite()方法执行批量操作：

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

如果无序批量写入中的任何写入操作失败， Kotlin 同步驱动程序仅在尝试所有操作后才会报告错误。

返回值

bulkWrite()方法返回一个BulkWriteResult对象。 您可以从BulkWriteResult实例访问权限以下信息：

插入操作

此示例演示如何创建包含插入两个文档的指令的模型。 将一个文档插入到 sample_restaurants.restaurants集合中，将另一文档插入到 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 的文档将替换为新文档。movies集合中 _id 值为 1 的文档也会被替换为新文档。

如果多个文档与 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 文档：

• 集合批量写入

  • bulkWrite()

  • InsertOneModel

  • UpdateOneModel

  • UpdateManyModel

  • ReplaceOneModel

  • DeleteOneModel

  • DeleteManyModel

  • BulkWriteResult

  • BulkWriteError

  • MongoBulkWriteException

• 客户端批量写入

  • bulkWrite()

  • ClientNamespacedWriteModel

  • MongoNamespace

  • ClientBulkWriteOptions

  • ClientBulkWriteResult