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	Um formato de string que evita a perda de informações do tipo BSON durante conversões de dados. Esse formato prioriza a preservação do tipo na perda de legibilidade humana e interoperabilidade com formatos mais antigos. Para saber mais sobre esse formato, consulte JsonMode.EXTENDED na documentação da API.
Descontraído	Um formato de string que descreve documentos BSON com alguma perda de informação de tipo. Esse formato prioriza a legibilidade humana e a interoperabilidade na perda de determinados tipos de informações. O driver Scala usa o modo Relaxed por padrão. Para saber mais sobre esse formato, consulte JsonMode.RELAXED na documentação da API.
Shell	Um formato de string que corresponda à sintaxe usada no MongoDB shell. Esse formato prioriza a compatibilidade com o shell do MongoDB , que frequentemente usa funções JavaScript para representar tipos. Para saber mais sobre esse formato, consulte JsonMode.SHell na documentação da API.

Observação

O driver Scala analisa o $uuid tipo de JSON estendido de uma string para um Binary objeto de subtipo 4 binário. Para obter mais informações sobre a $uuid análise do campo, 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

Você pode ler uma string JSON estendida em objetos Scala usando as classes de documento do driver Scala ou usando a biblioteca BSON diretamente. As seções a seguir mostram como usar cada abordagem.

Classe de documento

Você pode ler uma string JSON estendida em um objeto de documento Scala chamando o método estático parse() em BsonDocument e, em seguida, envolvendo o resultado em uma instância Scala Document. Essa abordagem analisa a string JSON estendida em qualquer um dos formatos e retorna um Document contendo os dados.

O exemplo a seguir mostra como você pode ler uma string JSON estendida em um objeto Document chamando BsonDocument.parse() e passando o resultado para a fábrica Document:

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

Iterable((_id,BsonObjectId{value=507f1f77bcf86cd799439011}), (myNumber,BsonInt64{value=4794261}))

Para saber mais sobre documentos no MongoDB, consulte Documentos no manual do MongoDB Server .

Biblioteca BSON

Você também pode ler uma string de Extended JSON em objetos Scala sem usar as classes de documentos do driver Scala do MongoDB, basta usar a classe JsonReader. Essa classe contém métodos para analisar sequencialmente os campos e valores em qualquer formato de string de Extended JSON, sendo gerado objetos Scala. As classes de documentos driver também usam esta classe para analisar Extended JSON.

O seguinte exemplo de código mostra como usar a classe JsonReader para converter uma string de Extended JSON em objetos Scala:

val ejsonStr = """{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "myNumber": {"$numberLong": "4794261"}}"""
val reader = new JsonReader(ejsonStr)
reader.readStartDocument()
val id = reader.readObjectId("_id")
val myNumber = reader.readInt64("myNumber")
reader.readEndDocument()
println(s"$id is type: ${id.getClass.getName}")
println(s"$myNumber is type: ${myNumber.getClass.getName}")

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: long

Para obter mais informações, consulte a documentação da API do JsonReader.

Escrever JSON estendido

Você pode gravar uma string JSON estendida a partir de seus dados usando as classes de documento do driver Scala ou usando a biblioteca BSON diretamente. As seções a seguir mostram como usar cada abordagem.

Classe de documento

Você pode gravar uma string de JSON estendida a partir de uma instância de Document ou BsonDocument chamando o método toJson(). Por padrão, o método toJson() gera a string no formato de modo relaxado. Para usar um formato diferente, passe uma instância da classe JsonWriterSettings para o método toJson().

O exemplo a seguir chama o método toJson() sem argumentos para gerar o JSON estendido no formato de modo relaxado padrão:

val document = Document(
  "_id" -> BsonObjectId(new ObjectId("507f1f77bcf86cd799439012")),
  "myNumber" -> BsonInt64(11223344L)
)
val ejsonStr = document.toJson()
println(ejsonStr)

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

Biblioteca BSON

Você também pode gerar uma string de Extended JSON a partir de dados em objetos Scala usando a biblioteca BSON com a classe JsonWriter . Para construir uma instância de JsonWriter, passe uma subclasse de um Writer Java para especificar como você deseja gerar a saída do Extended JSON. Você também 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 relaxado. As classes de documentos de driver Scala também usam esta classe para converter BSON para Extended JSON.

O exemplo de código abaixo mostra como usar o JsonWriter para criar uma string de Extended JSON e fazer sua saída para System.out. O exemplo especifica o formato passando o método construtor outputMode() para a constante JsonMode.EXTENDED:

val writer = new StringWriter()
val jsonWriter = new JsonWriter(writer,
    JsonWriterSettings.builder().outputMode(JsonMode.EXTENDED).build())
jsonWriter.writeStartDocument()
jsonWriter.writeObjectId("_id", new ObjectId("507f1f77bcf86cd799439012"))
jsonWriter.writeInt64("myNumber", 11223344L)
jsonWriter.writeEndDocument()
println(writer.toString())

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

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

Conversão personalizada de tipo de BSON

Além de especificar o outputMode() para formatar a saída JSON, você pode personalizar ainda mais a saída adicionando conversores à sua instância JsonWriterSettings.Builder. Esses métodos de conversores detectam BSON types específicos e executam a lógica definida pelo Converter passado para eles.

O código de amostra a seguir exibe como anexar conversores, definidos como expressões Lambda, para simplificar a saída JSON no modo relaxado:

val settings = JsonWriterSettings.builder()
  .outputMode(JsonMode.RELAXED)
  .objectIdConverter((value, writer) => writer.writeString(value.toHexString))
  .timestampConverter((value, writer) => {
    val instant = Instant.ofEpochSecond(value.getTime.toLong)
    writer.writeString(
      DateTimeFormatter.ISO_LOCAL_DATE_TIME.withZone(ZoneOffset.UTC).format(instant))
  })
  .build()
val document = Document(
  "_id" -> BsonObjectId(new ObjectId("507f1f77bcf86cd799439012")),
  "createdAt" -> new BsonTimestamp(1601516589, 1),
  "myNumber" -> BsonInt64(4794261L)
)
println(document.toJson(settings))

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-10-01T01:43:09", "myNumber": 4794261}
// Without specifying the converters, the Relaxed mode JSON output
// would look something like this:
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$timestamp": {"t": 1601516589, "i": 1}}, "myNumber": 4794261}

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

Voltar

Codecs

Séries temporais