/ /

插入文档

Overview

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

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

样本数据

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

此集合中的文档由以下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 Server 手册中的唯一索引指南。

要了解有关文档结构和规则的更多信息，请参阅 MongoDB Server 手册中的文档指南。

插入一个文档

要将单个文档添加到 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实例的 setter 方法：

方法	说明
`bypassDocumentValidation()`	如果设立为`true` ，则允许驾驶员忽略文档级验证。默认为 `false`。
`comment()`	设置要附加到操作的注释。有关更多信息，请参阅MongoDB Server手册中的插入命令字段指南。

您可以通过配置 InsertManyOptions实例，在 insertMany() 方法上设立上述设置。您还可以使用 ordered() 方法 setter 方法来指定驱动程序将文档插入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` 。