Extended JSON

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.
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.
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.

Observação

O driver Ruby 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

Você pode ler uma string de Extended JSON em uma array Ruby chamando o método BSON::ExtJSON.parse. Este método analisa uma string de JSON estendida e retorna uma array contendo os dados.

O exemplo abaixo mostra como ler uma string de Extended JSON em uma array de hashes usando o método parse:

require 'bson'
ex_json = '''[
    {"foo": [1, 2]},
    {"bar": {"hello": "world"}},
    {"code": {
    "$scope": {},
    "$code": "function x() { return 1; }"
    }},
    {"bin": {
    "$type": "80",
    "$binary": "AQIDBA=="
    }}
    ]'''
doc = BSON::ExtJSON.parse(ex_json)
puts doc.class
puts doc

{"foo" => [1, 2]}
{"bar" => {"hello" => "world"}}
{"code" => #<BSON::CodeWithScope:0x0000000123f398e0 @javascript="function x() { return 1; }", @scope={}>}
{"bin" => <BSON::Binary:0x7144 type=user data=0x01020304...>}

Escrever JSON estendido

Você pode gravar uma string de JSON estendida usando o método as_extended_json. Por padrão, este método retorna a string de JSON estendida no formato canônico, mas você pode especificar formatos relaxados ou legado passando um argumento mode.

Observação

Versão legada

A opção de formato legado diz ao driver Ruby para serializar os tipos BSON com o formato MongoDB Extended JSON v1, que é anterior aos formatos relaxados e canônicos atuais.

Para obter mais informações, consulte a página MongoDB Extended JSON v1 no manual do servidor.

O método as_extended_json está disponível para vários tipos de bibliotecas principais e padrão, incluindo Array e Hash. O exemplo a seguir cria strings de JSON estendida nos formatos canônico, relaxado e legado a partir de uma array de hashes:

require 'bson'
hash_array = [
    { "foo" => [1, 2] },
    { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) },
    { "number" => BSON::Int64.new(42) }
]
json_string_canonical = hash_array.as_extended_json
json_string_relaxed = hash_array.as_extended_json(mode: :relaxed)
json_string_legacy = hash_array.as_extended_json(mode: :legacy)
puts "canonical:\t #{json_string_canonical}"
puts "relaxed:\t #{json_string_relaxed}"
puts "legacy:\t\t #{json_string_legacy}"

canonical: [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":{"$numberLong":"42"}}]
relaxed:   [{"foo":[1,2]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":42}]
legacy:    [{"foo":[1,2]},{"bin":{"$binary":"AQIDBA==","$type":"80"}},{"number":42}]

Informações adicionais

Para obter mais informações, consulte os seguintes recursos:

Documentação da API

Páginas manuais do servidor

MongoDB Extended JSON (v2)

Voltar

BSON

Dados de Time Series