Documentos

Overview

En esta guía, puede aprender a utilizar documentos en el controlador MongoDB Kotlin.

Un documento de MongoDB es una estructura de datos que contiene campos clave/valor en formato binario JSON (BSON). Puedes usar documentos y los datos que contienen en sus campos para almacenar datos, y también utilizarlos para emitir comandos o consultas en MongoDB.

Para obtener más información sobre la terminología, la estructura y las limitaciones de los documentos, lea nuestra página sobre Documentos en el manual de MongoDB.

El driver de MongoDB Kotlin y la librería BSON incluyen las siguientes clases que le ayudan a acceder y manipular los datos BSON en los documentos:

Aunque puedes usar cualquiera de estas clases en tu aplicación, te recomendamos usar la clase Document, ya que puede representar de manera concisa documentos de estructuras dinámicas de cualquier complejidad. Implementa la interfaz Map<String, Object> que le permite usar valores de tipado libre.

Documento

La clase Document ofrece una representación flexible de un documento BSON. Puedes acceder y manipular campos usando tipos de Kotlin de la librería estándar con esta clase. Consulta la siguiente tabla para ver la correspondencia entre tipos BSON y Kotlin usados con frecuencia:

En el siguiente fragmento de código, mostramos cómo instanciar y compilar una muestra de instancia de Document que representa un documento que contiene varios tipos de campos diferentes:

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

Para insertar este documento en una colección, crea una colección utilizando el método getCollection() y llama al insertOne operación como se indica a continuación:

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

Una vez que realices una inserción exitosa, puedes recuperar los datos del documento de muestra de la colección usando el siguiente código:

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

Para obtener más información sobre cómo recuperar y manipular datos MongoDB, consulta nuestra guía CRUD.

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de la API:

• Documento

• getCollection()

• get()

Documento Bson

La clase BsonDocument proporciona una API con seguridad de tipos para acceder y manipular un documento BSON. Debe especificar el tipo BSON de la biblioteca BSON para cada campo. Consulte la siguiente tabla para ver las asignaciones entre los tipos BSON y los tipos de la biblioteca BSON más utilizados:

En el siguiente fragmento de código, mostramos cómo instanciar y compilar una muestra de instancia de BsonDocument que representa un documento que contiene varios tipos de campos diferentes:

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

Para insertar este documento en una colección, instancia una colección utilizando el método getCollection() especificando la clase BsonDocument como el parámetro documentClass. Luego, llama a la operación insertOne de la siguiente manera:

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

Una vez que realices una inserción exitosa, puedes recuperar los datos del documento de muestra de la colección usando el siguiente código:

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

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de la API:

• Documento Bson

• getCollection()

• BsonInvalidOperationException

• get()

• BsonValue

JsonObject

La clase JsonObject actúa como contenedor de cadenas JSON. Si solo desea trabajar con datos JSON, puede usar JsonObject para evitar la conversión innecesaria de datos a un objeto Map.

De forma predeterminada, JsonObject almacena JSON extendido. Puede personalizar el formato de JSON en JsonObject especificando un JsonObjectCodec y pasándole un JsonWriterSettings objeto. Para obtener más información sobre los formatos JSON, consulte nuestra guía de JSON extendido.

En el siguiente fragmento de código, mostramos cómo crear una instancia de muestra JsonObject que envuelva una cadena JSON extendida que contenga diferentes tipos de pares clave-valor:

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)

Para insertar este documento en una colección, instancia una colección utilizando el método getCollection() especificando la clase JsonObject como el parámetro documentClass. Luego, llama a la operación insertOne de la siguiente manera:

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

Una vez que realice una inserción exitosa, puede recuperar los datos de muestra JSON de la colección. Si bien puedes usar cualquier clase que extienda Bson para especificar tu query, aquí te mostramos cómo consultar tus datos usando un 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}]}

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de la API:

• JsonObject

• JsonObjectCodec

• Configuración de JsonWriter

• getCollection()

Resumen

En esta guía, cubrimos los siguientes temas sobre las clases que puedes usar para trabajar con datos BSON:

• Se describieron las clases de Kotlin que se pueden usar para trabajar con documentos de MongoDB y por qué podría ser preferible una frente a la otra.

• Se proporcionan ejemplos de uso para cada clase sobre cómo construir documentos que contienen varios tipos, insertarlos en una colección y recuperar/acceder a sus campos tipados.