Documents

Overview

In this guide, you can learn how to use documents in the MongoDB Kotlin driver.

A MongoDB document is a data structure that contains key/value fields in binary JSON (BSON) format. You can use documents and the data they contain in their fields to store data as well as issue commands or queries in MongoDB.

For more information on the terminology, structure, and limitations of documents, read our page on Documents in the MongoDB manual.

The MongoDB Kotlin driver and BSON library include the following classes that help you access and manipulate the BSON data in documents:

While you can use any of these classes in your application, we recommend that you use the Document class since it can concisely represent dynamically structured documents of any complexity. It implements the Map<String, Object> interface which enables it to use loosely-typed values.

Document

The Document class offers a flexible representation of a BSON document. You can access and manipulate fields using Kotlin types from the standard library with this class. See the following table for mappings between frequently-used BSON and Kotlin types:

In the following code snippet, we show how to instantiate and build a sample Document instance representing a document containing several different field types:

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)
        )
    )

To insert this document into a collection, instantiate a collection using the getCollection() method and call the insertOne operation as follows:

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

Once you perform a successful insert, you can retrieve the sample document data from the collection using the following code:

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

For more information on retrieving and manipulating MongoDB data, see our CRUD guide.

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• Document

• getCollection()

• get()

BsonDocument

The BsonDocument class provides a type-safe API to access and manipulate a BSON document. You need to specify the BSON type from the BSON library for each field. See the following table for mappings between frequently-used BSON and BSON library types:

In the following code snippet, we show how to instantiate and build a sample BsonDocument instance representing a document containing several different field types:

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))
            )
        )
    )

To insert this document into a collection, instantiate a collection using the getCollection() method specifying the BsonDocument class as the documentClass parameter. Then, call the insertOne operation as follows:

// 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)

Once you perform a successful insert, you can retrieve the sample document data from the collection using the following code:

// <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

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• BsonDocument

• getCollection()

• BsonInvalidOperationException

• get()

• BsonValue

JsonObject

The JsonObject class acts as a wrapper for JSON strings. If you only want to work with JSON data, you can use JsonObject to avoid unnecessary data conversion to a Map object.

By default, JsonObject stores Extended JSON. You can customize the format of JSON in JsonObject by specifying a JsonObjectCodec and passing it a JsonWriterSettings object. For more information on JSON formats, see our Extended JSON guide.

In the following code snippet, we show how to instantiate a sample JsonObject instance wrapping an Extended JSON string containing different types of key value pairs:

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)

To insert this document into a collection, instantiate a collection using the getCollection() method specifying the JsonObject class as the documentClass parameter. Then, call the insertOne operation as follows:

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

Once you perform a successful insert, you can retrieve the sample JSON data from the collection. While you can use any class that extends Bson to specify your query, here is how to query your data using a 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}]}

For more information about the methods and classes mentioned in this section, see the following API Documentation:

• JsonObject

• JsonObjectCodec

• JsonWriterSettings

• getCollection()

Summary

In this guide, we covered the following topics on classes you can use to work with BSON data:

• Described Kotlin classes you can use to work with MongoDB documents and why you might prefer one over the other.

• Provided usage examples for each class on building documents containing multiple types, inserting them into a collection, and retrieving/accessing their typed fields.