插入文档

本页内容

概述

示例数据
的_id 字段
插入单个文档
插入多个文档
修改插入行为
修改插入示例
返回值
附加信息
API 文档

概述

在本指南中，您将学习如何使用 Kotlin Sync 驱动程序通过执行 插入操作 将文档添加到 MongoDB 集合。

插入操作会将一个或多个文档插入到 MongoDB 集合中。您可以使用insertOne() 和 insertMany() 方法执行插入操作。

示例数据

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

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

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

`_id` 字段

在 MongoDB 集合中，每个文档都必须包含一个具有唯一值的 _id 字段。

MongoDB 允许您以两种方式管理此字段

您可以为每个文档设置此字段，确保每个 _id 字段值都是唯一的。
您可以允许驱动程序自动为每个文档的 _id 生成一个唯一的 ObjectId 值。如果您没有为文档手动设置 _id 值，驱动程序将使用 ObjectId 来填充该字段。

除非您能保证唯一性，否则我们建议让驱动程序自动生成 _id 值。

注意

重复 _id 错误

在集合中设置重复的 _id 值违反了唯一索引约束，这会导致驱动程序从 insertOne() 方法返回 WriteError 或从 insertMany() 方法返回 BulkWriteError。

有关 _id 字段的更多信息，请参阅 MongoDB 服务器手册中的唯一索引指南。

有关文档结构和规则的信息，请参阅 MongoDB 服务器手册中的文档指南。

插入一个文档

要将单个文档添加到 MongoDB 集合中，请调用 insertOne() 方法并传递您要添加的文档。

以下示例将文档插入到 restaurants 集合

val doc = Restaurant("Sea Shell Bar", "Queens")
val result = collection.insertOne(doc)

插入多个文档

要将多个文档添加到 MongoDB 集合中，请使用 insertMany() 方法并传递您要添加的文档列表。

以下示例将文档列表插入到 restaurants 集合

val docs = listOf(
    Restaurant("Full Moon Grill", "Queens"),
    Restaurant("King's Cup", "Manhattan"),
)
val result = collection.insertMany(docs)

修改插入行为

insertOne() 方法可以接受一个可选的 InsertOneOptions 参数，用于设置配置插入操作的选项。如果您没有指定任何选项，驱动程序将使用默认设置执行插入操作。将选项作为 insertOne() 方法的最后一个参数传递。

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

方法	描述
`bypassDocumentValidation()`	如果设置为 `true`，允许驱动程序忽略文档级验证。默认为 `false`。
`comment()`	设置要附加到操作的注释。有关更多信息，请参阅 MongoDB 服务器手册中的插入命令字段指南。

您可以在 insertMany() 方法上设置前面的设置，通过配置一个 InsertManyOptions 实例。您还可以使用 ordered() 方法设置器方法来指定驱动程序将文档插入 MongoDB 的顺序

方法	描述
`ordered()`	如果设置为 `true`，驱动程序将按照提供的顺序将文档发送到服务器。如果发生错误，驱动程序将取消所有剩余的插入操作。默认为 `true`。

将选项作为 insertMany() 方法的最后一个参数传递。

修改插入示例

以下代码使用 bypassDocumentValidation() 方法设置选项以忽略文档验证规则。然后，示例使用 insertMany() 方法向 restaurants 集合添加新文档。

val opts = InsertManyOptions().bypassDocumentValidation(true)
val docs = listOf(
    Restaurant("Full Moon Grill", "Queens"),
    Restaurant("King's Cup", "Manhattan"),
)
val result = collection.insertMany(docs, opts)

返回值

insertOne() 方法返回一个 InsertOneResult 实例，而 insertMany() 方法返回一个 InsertManyResult 实例。

您可以使用以下方法从 InsertOneResult 实例中检索信息

方法	描述
`getInsertedId()`	指示插入文档的 `_id` 值。
`wasAcknowledged()`	如果服务器确认结果，则返回 `true`。

您可以使用以下方法从 InsertOneResult 实例中检索信息

方法	描述
`getInsertedIds()`	指示插入文档的 `_id` 值。
`wasAcknowledged()`	如果服务器确认结果，则返回 `true`。

注意

如果 wasAcknowledged() 方法返回 false，尝试访问 _id 值将导致 InvalidOperation 异常。如果服务器没有确认写入操作，驱动程序无法确定这些值。

概述