Documentos

Visão geral

Neste guia, você pode aprender como usar documentos no driver MongoDB Kotlin.

Um documento do MongoDB é uma estrutura de dados que contém campos de chave/valor no formato JSON binário (BSON). Você pode usar documentos e os dados que eles contêm em seus campos para armazenar dados, bem como para emitir comandos ou queries no MongoDB.

Para mais informações sobre a terminologia, estrutura e limitações de documentos, leia nossa página em Documentos no manual do MongoDB.

O driver Kotlin do MongoDB e a biblioteca BSON incluem as seguintes classes que ajudam a acessar e manipular os dados BSON em documentos:

Embora possa usar qualquer uma dessas classes em seu aplicativo, recomendamos utilizar a classe Document, pois ela representa de forma concisa documentos estruturados dinamicamente de qualquer complexidade. Ela implementa a interface Map<String, Object>, o que lhe permite usar valores de tipos livres.

Documento

A classe Document oferece uma representação flexível de um documento BSON. Você pode acessar e manipular campos usando tipos de Kotlin da biblioteca padrão com esta classe. Consulte a tabela a seguir para mapeamentos entre os tipos de BSON e Kotlin usados com frequência:

No trecho de código abaixo, mostramos como instanciar e construir uma instância Document de amostra que representa um documento com vários tipos de campos:

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 inserir esse documento em uma coleção, instancie uma coleção usando o método getCollection() e chame a operaçãoinsertOne da seguinte forma:

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

Depois de realizar uma inserção bem-sucedida, você pode recuperar os dados do documento de amostra da coleção usando o código a seguir:

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 obter mais informações sobre como recuperar e manipular dados do MongoDB, consulte nosso guia CRUD.

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• Documento

• getCollection()

• get()

Documento BSON

A classe BsonDocument fornece uma API segura por tipo para acessar e manipular um documento BSON. Você precisa especificar o tipo BSON da biblioteca BSON para cada campo. Consulte a tabela a seguir para mapeamentos entre os tipos de biblioteca BSON e BSON usados com frequência:

No trecho de código abaixo, mostramos como instanciar e construir uma instância BsonDocument de amostra que representa um documento com vários tipos de campos:

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 inserir este documento em uma coleção, instancie uma coleção utilizando o método getCollection() especificando a classe BsonDocument como o parâmetro documentClass. Em seguida, ligue para a operação insertOne da seguinte maneira:

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

Depois de realizar uma inserção bem-sucedida, você pode recuperar os dados do documento de amostra da coleção usando o código a seguir:

// <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 obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• Documento BSON

• getCollection()

• Exceção de operação inválida do BSON

• get()

• BsonValor

JsonObject

A classe JsonObject age como um wrapper para strings JSON. Se você deseja trabalhar somente com dados JSON, use o JsonObject para evitar uma conversão de dados desnecessária para um objeto Map.

Por padrão, JsonObject armazena JSON estendido. Você pode personalizar o formato de JSON no JsonObject especificando um JsonObjectCodec e passando um objeto JsonWriterSettings . Para mais informações sobre formatos JSON, consulte nosso guia JSON estendido.

No trecho de código a seguir, mostramos como instanciar uma instância de JsonObject de exemplo encapsulando uma string JSON estendida contendo diferentes tipos de pares de valores de chave:

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 inserir este documento em uma coleção, instancie uma coleção utilizando o método getCollection() especificando a classe JsonObject como o parâmetro documentClass. Em seguida, ligue para a operação insertOne da seguinte maneira:

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

Após executar uma inserção bem-sucedida, você pode recuperar a amostra de dados JSON da coleção. Enquanto você pode utilizar qualquer classe que estenda o Bson para especificar sua query, aqui está como executar query de seus dados utilizando um 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 obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• JsonObject

• JsonObjectCodec

• JsonWriterSettings

• getCollection()

Resumo

Neste guia, descrevemos os seguintes tópicos de classes que você pode usar para trabalhar com dados BSON:

• Classes Kotlin descritas que você pode usar para trabalhar com documentos do MongoDB, e por que uma classe pode ser melhor que a outra.

• Fornecer exemplos de uso para cada classe em documentos de construção contendo vários tipos, inserindo-os em uma coleção e recuperando/acessando seus campos digitados.