Docs 菜单
Docs 主页
/ /
Kotlin Coroutine 驱动程序
Docs 主页
/
客户端库
/
Kotlin
/
Kotlin Coroutine 驱动程序
Docs 主页
/
客户端库
/
Kotlin
/
Kotlin Coroutine 驱动程序

插入文档

Overview

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

插入操作将一个或多个文档插入MongoDB集合。 您可以使用以下方法执行插入操作：

  • insertOne() 插入单个文档

  • insertMany() 插入一个或多个文档

样本数据

在以下示例中，一家油漆店库存有不同颜色的油漆。 此数据使用以下 Kotlin 数据类进行建模：

data class PaintOrder(
    @BsonId val id: ObjectId? = null,
    val qty: Int,
    val color: String
)

_id 字段

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

MongoDB 允许您通过两种方式管理该字段：

  • 您可以自行为每个文档设置此字段，确保每个 _id 字段的值都是唯一的。

  • 您可以让驱动程序自动为每个文档_id 生成唯一的 ObjectId 值。如果您没有为文档手动设立_id 值，驱动程序将使用 ObjectId 填充该字段。

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

注意

重复_id错误

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

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

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

插入一个文档

如果要插入单个文档，请使用 insertOne() 方法。

成功插入后，该方法将返回一个InsertOneResult 实例，该实例表示新文档的_id。

以下示例使用 insertOne() 方法创建并插入文档：

val paintOrder = PaintOrder(ObjectId(), 5, "red")
val result = collection.insertOne(paintOrder)
val insertedId = result.insertedId?.asObjectId()?.value
println("Inserted a document with the following id: $insertedId")
Inserted a document with the following id: 60930c39a982931c20ef6cd6

插入多个文档

要将多个文档添加到MongoDB集合，请使用 insertMany() 方法并传递要添加的文档列表。insertMany() 方法按指定顺序插入文档，直到发生异常（如有）。

如果成功，该方法将返回一个 InsertManyResult实例，表示每个新文档的 _id。

以下示例创建两个文档并将其添加到 List 中，并使用 insertMany() 方法插入 List：

val paintOrders = listOf(
    PaintOrder(ObjectId(), 5, "red"),
    PaintOrder(ObjectId(), 10, "purple")
)
val result = collection.insertMany(paintOrders)
println("Inserted documents with the following ids: ${result.insertedIds.toList()}")
Inserted documents with the following ids: [60930c3aa982931c20ef6cd7, 60930c3aa982931c20ef6cd8]

返回值

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

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

方法
说明

getInsertedId()

指示插入文档的_id值。

wasAcknowledged()

如果服务器确认结果，则返回true 。

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

方法
说明

getInsertedIds()

指示插入文档的_id值。

wasAcknowledged()

如果服务器确认结果，则返回true 。

注意

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

完全可运行的示例

以下部分提供完全可运行的示例，演示如何使用 insertOne() 和 insertMany() 方法插入文档。

样本数据

本部分中的示例使用Atlas示例数据集中的 sample_movies.movies集合。要学习如何创建免费的MongoDB Atlas 集群并加载示例数据集，请参阅 Mongodb 入门指南。

insertOne() 示例：完整文件

以下示例连接到MongoDB 集群，创建 MongoClient对象，并使用 insertOne() 方法将单个文档插入到 movies集合中：

import com.mongodb.MongoException
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId
data class Movie(@BsonId val id: ObjectId, val title: String, val genres: List<String>)
fun main() = runBlocking {
    // Replace the uri string with your MongoDB deployment's connection string
    val uri = "<connection string uri>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Movie>("movies")
    try {
        val result = collection.insertOne(
            Movie(ObjectId(), "Ski Bloopers", listOf("Documentary", "Comedy"))
        )
        println("Success! Inserted document id: " + result.insertedId)
    } catch (e: MongoException) {
        System.err.println("Unable to insert due to an error: $e")
    }
    mongoClient.close()
}
Success! Inserted document id: BsonObjectId{value=...}

insertMany() 示例：完整文件

以下示例连接到MongoDB 集群，创建 MongoClient对象，并使用 insertMany() 方法将多个文档插入到 movies集合中：

import com.mongodb.MongoException
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
data class Movie(val title: String)
fun main() = runBlocking {
    // Replace the uri string with your MongoDB deployment's connection string
    val uri = "<connection string uri>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Movie>("movies")
    val movieList = listOf(
        Movie("Short Circuit 3"),
        Movie("The Lego Frozen Movie")
    )
    try {
        val result = collection.insertMany(movieList)
        println("Success! Inserted document ids: " + result.insertedIds)
    } catch (e: MongoException) {
        System.err.println("Unable to insert due to an error: $e")
    }
    mongoClient.close()
}
Success! Inserted document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}

API 文档

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

后退

数据库和collection

来年

查找文档

在此页面上