Menu Docs
Página inicial do Docs
/ / /
Kotlin Coroutine
/ /

Documentos

Nesta página

  • Visão geral
  • Documento
  • Documento BSON
  • JsonObject
  • Resumo

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:

Nome
Pacote
Mapa de implementos
Uso recomendado
Document
org.bson
Sim, implementa Map<String, Object>
Quando você deseja uma representação de dados flexível e concisa.
BsonDocument
org.bson
Sim, implementa Map<String, BsonValue>
Quando você precisa de uma API com segurança de tipo.
JsonObject
org.bson.json
No
Quando você deseja trabalhar somente com strings JSON.

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.

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:

Tipo de BSON
Tipo de Kotlin
Array
kotlin.collections.List
Binário
org.bson.types.Binary
Boolean
kotlin.Boolean
Data
java.time.LocalDateTime
Documento
org.bson.Document
Double
kotlin.Double
Int32
kotlin.Int
Int64
kotlin.Long
Zero
null
ObjectId
org.bson.types.ObjectId
String
kotlin.String

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

Dica

O exemplo de código anterior usa métodos auxiliares que verificam o tipo retornado e lançam uma exceção se não for possível converter o valor do campo. Você pode chamar o método get() para recuperar valores como tipo Object e ignorar a verificação de tipo.

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:

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:

Tipo de BSON
Tipo de biblioteca BSON
Array
org.bson.BsonArray
Binário
org.bson.BsonBinary
Boolean
org.bson.Boolean
Data (valor longo)
org.bson.BsonDateTime
Documento
org.bson.BsonDocument
Double
org.bson.BsonDouble
Int32
org.bson.BsonInt32
Int64
org.bson.BsonInt64
Zero
org.bson.BsonNull
ObjectId
org.bson.BsonObjectId
String
org.bson.BsonString

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

Dica

O exemplo de código anterior usa métodos auxiliares que verificam o tipo gerado e lançam um BsonInvalidOperationException se não for possível converter o valor do campo. Você pode chamar o método get() para recuperar valores como tipo BsonValue e ignorar a verificação de tipo.

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

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:

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.

Voltar

Formato de dados do documento: JSON estendido