Trabalhe com dados JSON estendidos

Visão geral

Neste guia, você verá como usar o formato de dados JSON estendido ao interagir com documentos do MongoDB.

JSON é um formato de dados legível por humanos que representa os valores de objetos, arrays, números, strings, booleans e nulos. Este formato suporta apenas um subconjunto de tipos de dados BSON, que é o formato que o MongoDB utiliza para armazenar dados. O formato Extended JSON aceita mais tipos de BSON, definindo um conjunto reservado de chaves prefixadas com "$" para representar informações de tipos de campo que correspondem diretamente a cada tipo em BSON.

Para saber mais sobre JSON, BSON e Extended JSON, consulte o recurso JSON e BSON e a entrada de manual do Extended JSON MongoDB Server.

Formatos Extended JSON

O MongoDB Extended JSON fornece formatos de string para representar dados BSON. Cada formato está em conformidade com o JSON RFC e atende a casos de uso específicos.

A tabela abaixo descreve cada formato de Extended JSON:

Nome	Descrição
Estendido ou Canônico	A string format that avoids loss of BSON type information during data conversions. This format prioritizes type preservation at the loss of human-readability and interoperability with older formats. To learn more about this format, see JsonMode.EXTENDED in the API documentation.
Descontraído	A string format that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of certain type information. The Kotlin Sync driver uses Relaxed mode by default. To learn more about this format, see JsonMode.RELAXED in the API documentation.
Shell	A string format that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell, which often uses JavaScript functions to represent types. To learn more about this format, see JsonMode.SHELL in the API documentation.

Observação

O driver Kotlin Sync analisa o tipo de JSON estendido $uuid de uma string para um objeto BsonBinary de subtipo binário 4. Para obter mais informações sobre a análise do campo $uuid, consulte a seção regras especiais para analisar campos $uuid na especificação de JSON estendida.

Exemplos de JSON estendido

Os exemplos abaixo mostram um documento contendo um campo de ObjectId, data e número longo representado em cada formato Extended JSON. Clique na aba correspondente ao formato do exemplo que deseja ver:

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": { "$numberLong": "1601499609" }},
  "numViews": { "$numberLong": "36520312" }
}

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
  "numViews": 36520312
}

{
  "_id": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

Ler Extended JSON

Esta seção mostra como ler valores de JSON estendido em objetos Kotlin das seguintes maneiras:

Use as classes de documentos
Usar a classe JsonReader

Use as classes de documentos

Para ler uma string de JSON estendida em um objeto de documento Kotlin , chame o método estático parse() da classe Document ou BsonDocument. Este método analisa a string de JSON estendida e armazena seus dados em uma instância da classe de documento especificada.

O exemplo seguinte utiliza o método parse() para ler uma string de Extended JSON em um objeto Document :

val ejsonStr = """
    {
        "_id": { "$${"oid"}": "507f1f77bcf86cd799439011" },
        "myNumber": { "$${"numberLong"}": "4794261" }
    }
""".trimIndent()
val doc = Document.parse(ejsonStr)
println(doc)

Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}

Usar a classe JsonReader

Para ler uma string de Extended JSON em objetos Kotlin sem usar as classes de documento do driver Kotlin Sync, use a classe JsonReader da biblioteca BSON. Esta classe contém métodos para analisar sequencialmente os campos e valores da string de JSON estendida e devolvê-los como objetos Kotlin . As classes de documento driver também usam esta classe para analisar Extended JSON.

O código abaixo usa métodos fornecidos pela classe JsonReader para converter uma string de Extended JSON em objetos Kotlin :

val string = """
    {
        "_id": { "$${"oid"}": "507f1f77bcf86cd799439011" },
        "myNumber": { "$${"numberLong"}": "4794261" }
    }
""".trimIndent()
val jsonReader = JsonReader(string)
jsonReader.readStartDocument()
// Reads the "_id" field value
jsonReader.readName("_id")
val id = jsonReader.readObjectId()
// Reads the "myNumber" field value 
jsonReader.readName("myNumber")
val myNumber = jsonReader.readInt64()
jsonReader.readEndDocument()
println("$id is type: ${id::class.qualifiedName}")
println("$myNumber is type: ${myNumber::class.qualifiedName}")
jsonReader.close()

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: kotlin.Long

Escrever JSON estendido

Esta seção mostra como escrever valores de JSON estendido a partir de objetos Kotlin das seguintes maneiras:

Use as classes de documentos
Usar a classe JsonWriter

Use as classes de documentos

Para gravar uma string de JSON estendida a partir de um objeto Document ou BsonDocument, chame o método toJson(). Você pode passar a esse método um parâmetro de objeto JsonWriterSettings para especificar o formato de JSON estendido.

O exemplo a seguir grava dados Document como JSON estendido do modo relaxado:

val doc = Document()
    .append("_id", ObjectId("507f1f77bcf86cd799439012"))
    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
    .append("myNumber", 4794261)
val settings = JsonWriterSettings.builder()
    .outputMode(JsonMode.RELAXED)
    .build()
println(doc.toJson(settings))

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}

Usar a classe JsonWriter

Para gerar uma string de Extended JSON a partir de dados armazenados em objetos Kotlin , você pode usar a classe JsonWriter da biblioteca BSON. Para construir um objeto JsonWriter, passe uma subclasse de um Writer Java para especificar como você deseja gerar a saída do Extended JSON. Opcionalmente, você pode passar uma instância do JsonWriterSettings para especificar opções, como o formato do Extended JSON. Por padrão, o JsonWriter usa o formato de modo Relaxed. As classes de documento de driverdo Kotlin Sync também usam esta classe para converter BSON para Extended JSON.

O exemplo a seguir usa um objeto JsonWriter para criar valores de string JSON estendido do modo canônico e enviá-los para System.out:

 val settings = JsonWriterSettings.builder()
    .outputMode(JsonMode.EXTENDED)
    .build()
JsonWriter(BufferedWriter(OutputStreamWriter(System.out)), settings).use { jsonWriter ->
    jsonWriter.writeStartDocument()
    jsonWriter.writeName("_id")
    jsonWriter.writeObjectId(ObjectId("507f1f77bcf86cd799439012"))
    jsonWriter.writeName("myNumber")
    jsonWriter.writeInt64(11223344L)
    jsonWriter.writeEndDocument()
    jsonWriter.flush()
}

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}

Conversão personalizada de tipo de BSON

Além de especificar o formato de saída JSON estendido, você pode personalizar ainda mais a saída adicionando conversores ao seu objeto JsonWriterSettings. Esses métodos de conversor especificam a lógica para lidar com diferentes tipos de dados durante o processo de conversão.

O exemplo a seguir converte o mesmo documento que o exemplo Usar classes de documentos. No entanto, este exemplo define os métodos conversores objectIdConverter() e dateTimeConverter() em um objeto JsonWriterSettings para simplificar a saída de Extended JSON do modo Relaxed:

val settings = JsonWriterSettings.builder()
    .outputMode(JsonMode.RELAXED)
    .objectIdConverter { value, writer ->
        writer.writeString(value.toHexString())
    }
    .dateTimeConverter { value, writer ->
        val zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC)
        writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime))
    }
    .build()
val doc = Document()
    .append("_id", ObjectId("507f1f77bcf86cd799439012"))
    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
    .append("myNumber", 4794261)
println(doc.toJson(settings))

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Séries temporais

Indexes