文档 (Document）

在此页面上

Overview

文档
BsonDocument
JsonObject
总结

Overview

在本指南中，您可以了解如何在 MongoDB Kotlin 驱动程序中使用文档。

MongoDB 文档是种数据结构，包含二进制 JSON (BSON) 形式的键/值字段。您可以使用文档及其字段中包含的数据来存储数据，也可以在 MongoDB 中发布命令或查询。

有关文档的术语、结构和限制的更多信息，请阅读 MongoDB 手册中的文档页面。

MongoDB Kotlin 驱动程序和 BSON 库包含以下类，可帮助您访问和操作文档中的 BSON 数据：

名称	安装包	实施地图	推荐用法
`Document`	`org.bson`	是，实现 `Map<String, Object>`	当您需要灵活简洁的数据表示时。
`BsonDocument`	`org.bson`	是，实现 `Map<String, BsonValue>`	当您需要类型安全的 API 时。
`JsonObject`	`org.bson.json`	No	当您只想处理 JSON 字符串时。

虽然您可以在应用程序中使用其中任何类，但我们建议您使用 Document 类，因为其可以简明地表示任何复杂程度的动态结构文档。其实现了 Map<String, Object> 接口，从而可以使用松散类型值。

文档

Document类提供了 BSON 文档的灵活表示形式。您可以通过此类，使用标准库中的 Kotlin 类型访问和操作字段。有关常用 BSON 和 Kotlin 类型之间的映射关系，请参阅下表：

BSON 类型	Kotlin 类型
阵列	`kotlin.collections.List`
二进制文件	`org.bson.types.Binary`
布尔	`kotlin.Boolean`
Date	`java.time.LocalDateTime`
文档	`org.bson.Document`
double	`kotlin.Double`
Int32	`kotlin.Int`
Int64	`kotlin.Long`
null	`null`
ObjectId	`org.bson.types.ObjectId`
字符串	`kotlin.String`

以下代码片段中，我们将展示如何实例化和构建示例 Document 实例，该实例代表包含多种不同字段类型的文档：

val author = Document("_id", ObjectId())
    .append("name", "Gabriel García Márquez")
    .append(
        "dateOfDeath",
        LocalDateTime.of(2014, 4, 17, 4, 0)
    )
    .append(
        "novels", listOf(
            Document("title", "One Hundred Years of Solitude").append("yearPublished", 1967),
            Document("title", "Chronicle of a Death Foretold").append("yearPublished", 1981),
            Document("title", "Love in the Time of Cholera").append("yearPublished", 1985)
        )
    )

要将此文档插入到集合中，请使用getCollection()方法实例化一个集合，并调用 insertOne操作，如下所示：

// val mongoClient = <code to instantiate your client>
val database = mongoClient.getDatabase("fundamentals_data")
val collection = database.getCollection<Document>("authors")
val result = collection.insertOne(author)

成功执行插入操作后，可以使用以下代码从集合中检索示例文档数据：

val doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).firstOrNull()
doc?.let {
    println("_id: ${it.getObjectId("_id")}, name: ${it.getString("name")}, dateOfDeath: ${it.getDate("dateOfDeath")}")
    it.getList("novels", Document::class.java).forEach { novel ->
        println("title: ${novel.getString("title")}, yearPublished: ${novel.getInteger("yearPublished")}")
    }
}

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: Thu Apr 17 00:00:00 EDT 2014
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

提示

前面的代码样本使用辅助方法检查返回类型，并在无法转换字段值时引发异常。您可以调用 get() 方法来检索类型为 Object 的值并跳过类型检查。

有关检索和操作 MongoDB 数据的更多信息，请参阅我们的增删改查指南。

有关本节中提到的方法和类的详情，请参阅以下 API 文档：

BsonDocument

BsonDocument类提供类型安全的 API 来访问和操作 BSON 文档。您需要为每个字段指定 BSON 库中的 BSON 类型。常用 BSON 和 BSON 库类型之间的映射关系如下表所示：

BSON 类型	BSON 库类型
阵列	`org.bson.BsonArray`
二进制文件	`org.bson.BsonBinary`
布尔	`org.bson.Boolean`
日期（长值）	`org.bson.BsonDateTime`
文档	`org.bson.BsonDocument`
double	`org.bson.BsonDouble`
Int32	`org.bson.BsonInt32`
Int64	`org.bson.BsonInt64`
null	`org.bson.BsonNull`
ObjectId	`org.bson.BsonObjectId`
字符串	`org.bson.BsonString`

以下代码片段中，我们将展示如何实例化和构建示例 BsonDocument 实例，该实例代表包含多种不同字段类型的文档：

val author = BsonDocument()
    .append("_id", BsonObjectId())
    .append("name", BsonString("Gabriel García Márquez"))
    .append(
        "dateOfDeath",
        BsonDateTime(
            LocalDateTime.of(2014, 4, 17, 0, 0).atZone(ZoneId.of("America/New_York")).toInstant().toEpochMilli()
        )
    )
    .append(
        "novels", BsonArray(
            listOf(
                BsonDocument().append("title", BsonString("One Hundred Years of Solitude"))
                    .append("yearPublished", BsonInt32(1967)),
                BsonDocument().append("title", BsonString("Chronicle of a Death Foretold"))
                    .append("yearPublished", BsonInt32(1981)),
                BsonDocument().append("title", BsonString("Love in the Time of Cholera"))
                    .append("yearPublished", BsonInt32(1985))
            )
        )
    )

要将此文档插入到某一集合中，请使用 getCollection() 方法实例化一个集合，而此方法会将 BsonDocument 类指定为 documentClass 参数。然后，按以下方法调用 insertOne 操作：

// val mongoClient = <code to instantiate your client>
val database = mongoClient.getDatabase("fundamentals_data")
val collection = database.getCollection<BsonDocument>("authors")
val result: InsertOneResult = collection.insertOne(author)

成功执行插入操作后，可以使用以下代码从集合中检索示例文档数据：

// <MongoCollection setup code here>
val doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).firstOrNull()
doc?.let {
    println("_id: ${it.getObjectId("_id").value}, name: ${it.getString("name").value}, dateOfDeath: ${Instant.ofEpochMilli(it.getDateTime("dateOfDeath").value).atZone(ZoneId.of("America/New_York")).toLocalDateTime()}")
    it.getArray("novels").forEach { novel ->
        val novelDocument = novel.asDocument()
        println("title: ${novelDocument.getString("title").value}, yearPublished: ${novelDocument.getInt32("yearPublished").value}")
    }
}

_id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: 2014-04-17T00:00
title: One Hundred Years of Solitude, yearPublished: 1967
title: Chronicle of a Death Foretold, yearPublished: 1981
title: Love in the Time of Cholera, yearPublished: 1985

提示

前面的代码示例使用辅助方法检查返回类型，并在无法转换字段值时抛出BsonInvalidOperationException 。您可以调用get()方法来检索类型为BsonValue的值并跳过类型检查。

有关本节中提到的方法和类的详情，请参阅以下 API 文档：

JsonObject

JsonObject 类作为 JSON 字符串的包装器。如果只想处理 JSON 数据，可以使用 JsonObject 来避免将数据不必要地转换为 Map 对象。

默认， JsonObject存储扩展JSON 。您可以在JsonObject中自定义JSON格式，方法是指定JsonObjectCodec并向其传递JsonWriterSettings对象。有关JSON格式的更多信息，请参阅我们的扩展JSON指南。

在以下代码片段中，我们展示了如何实例化示例 JsonObject 实例，该实例包装包含不同类型键值对的扩展 JSON 字符串：

val ejsonStr = """
    {"_id": {"${"$"}oid": "6035210f35bd203721c3eab8"},
    "name": "Gabriel García Márquez",
    "dateOfDeath": {"${"$"}date": "2014-04-17T04:00:00Z"},
    "novels": [
        {"title": "One Hundred Years of Solitude","yearPublished": 1967},
        {"title": "Chronicle of a Death Foretold","yearPublished": 1981},
        {"title": "Love in the Time of Cholera","yearPublished": 1985}]}
    """.trimIndent()
val author = JsonObject(ejsonStr)

要将此文档插入到某一集合中，请使用 getCollection() 方法实例化一个集合，而此方法会将 JsonObject 类指定为 documentClass 参数。然后，按以下方法调用 insertOne 操作：

// val mongoClient = <code to instantiate your client>;
val database = mongoClient.getDatabase("fundamentals_data")
val collection= database.getCollection<JsonObject>("authors")
val result = collection.insertOne(author)

成功执行插入操作后，可以从集合中检索 JSON 示例数据。您可以使用任何扩展了 Bson 的类来指定查询，下面介绍了如何使用 JsonObject 查询数据：

// val mongoClient = <code to instantiate your client>;
val query = JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}")
val jsonResult = collection.find(query).firstOrNull()
jsonResult?.let {
    println("query result in extended json format: " + jsonResult.json)
}

query result in extended json format: {"_id": {"$oid": "6035210f35bd203721c3eab8"}, "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, {"title": "Love in the Time of Cholera", "yearPublished": 1985}]}

有关本节中提到的方法和类的详情，请参阅以下 API 文档：

总结

在本指南中，我们介绍了可用于处理 BSON 数据的类，包括以下主题：

描述了可用于处理 MongoDB 文档的 Kotlin 类，以及为什么您可能更喜欢其中一个类。
为每个类提供了构建包含多种类型的文档、将它们插入集合以及检索/访问其类型化字段的用法示例。

后退

扩展 JSON

来年

Kotlin 序列化