批量写入操作

样本数据

本指南中的示例使用Atlas示例数据集中的 和sample_restaurants.restaurants sample_mflix.movies集合。要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅Atlas入门指南。

这些集合中的文档由以下Kotlin数据类建模：

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String
)
data class Movie(
    val title: String,
    val year: Int
)

插入操作

要执行插入操作，请创建一个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实例访问权限以下信息：

插入操作

此示例演示如何创建包含插入两个文档的指令的模型。将一个文档插入到 db.people集合中，将另一文档插入到 db.things集合中。 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)
    )

替换操作

以下示例展示了如何创建模型来替换 db.people 和 db.things 集合中的现有文档：

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)
    )

此示例成功运行后，people集合中 _id 值为 1 的文档将替换为新文档。 things集合中 _id 值为 1 的文档将替换为新文档。

执行批量操作

为要执行的每个操作定义 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