插入文档

在此页面上

Overview

样本数据
_id 字段
插入一个文档
插入多个文档
修改插入行为
修改插入示例
返回值
更多信息
API 文档

Overview

在本指南中，您可以学习；了解如何使用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 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()`	If set to `true`, allows the driver to ignore document-level validation. Defaults to `false`.
`comment()`	Sets a comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual for more information.

您可以通过配置InsertManyOptions实例，在insertMany()方法上进行上述设立。您还可以使用ordered()方法 setter 方法来指定驾驶员将文档插入MongoDB的顺序：

方法	说明
`ordered()`	If set to `true`, the driver sends documents to the server in the order provided. If an error occurs, the driver cancels all remaining insert operations. Defaults to `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异常。如果服务器未确认写入操作，则驾驶员无法确定这些值。