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:
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.
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:
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 os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:
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:
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:
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:
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.