批量写入操作

本页内容

概述

示例数据
定义写入操作
插入操作
更新操作
替换操作
删除操作
执行批量操作
自定义批量写入操作
返回值
附加信息
API 文档

概述

本指南展示了如何使用 Kotlin 同步驱动程序执行批量写入操作，该操作可在单个数据库调用中对您的数据进行多个更改。

考虑一种需要为同一任务插入、更新和删除文档的情况。如果您使用单个写入方法来执行每种类型的操作，则每个写入都会单独访问数据库。您可以使用批量写入操作来优化您的应用程序对服务器的调用次数。

示例数据

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

该集合中的文档由以下 Kotlin 数据类建模

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

定义写入操作

对于您要执行的每个写入操作，创建一个从泛型 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 服务器手册中的字段更新运算符指南。

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 项，其中包括失败的操作和异常的详细信息。

注意

当驱动程序执行批量操作时，它使用目标集合的写关注。驱动程序在尝试所有操作后报告所有写关注错误，无论执行顺序如何。

自定义批量写操作

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

以下表格描述了您可以使用来配置 BulkWriteOptions 实例的设置方法

属性	描述
`ordered()`	如果为 `true`，驱动程序将按照提供的顺序执行写操作。如果发生错误，则不会尝试剩余的操作。如果为 `false`，驱动程序将按任意顺序执行操作并尝试执行所有操作。默认值为 `true`。
`bypassDocumentValidation()`	指定更新操作是否绕过文档验证。这允许您更新不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅 MongoDB 服务器手册中的模式验证。默认值为 `false`。
`comment()`	为操作设置注释。
`let()`	提供参数名称和值的映射，以设置操作的一级变量。值必须是常数或封闭表达式，不能引用文档字段。

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

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

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

注意

无序批量操作不保证执行顺序。顺序可能与您列出的方式不同，以优化运行时。

返回值

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

属性	描述
`wasAcknowledged()`	指示服务器是否已确认写操作。
`getDeletedCount()`	如果有，删除的文档数量。
`getInsertedCount()`	如果有，插入的文档数量。
`getInserts()`	如果有，插入的文档列表。
`getMatchedCount()`	如果有，适用于更新的匹配文档数量。
`getModifiedCount()`	如果有，修改的文档数量。
`getUpserts()`	如果有，更新插入的文档列表。

附加信息

要了解如何执行单个写操作，请参阅以下指南

API 文档

要了解本指南中讨论的任何方法或类型，请参阅以下 API 文档

删除

事务