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
Canônico	Um formato de string que evita a perda de informações do tipo BSON durante as conversões de dados. Esse formato prioriza a preservação do tipo na perda de legibilidade humana e interoperabilidade com formatos mais antigos. Para especificar este modo, passe `bsoncxx::ExtendedJsonMode::k_canonical` como um argumento `mode` para o método `to_json()`.
Descontraído	Um formato de string que descreve documentos BSON com alguma perda de informação de tipo. Este formato prioriza a legibilidade humana e a interoperabilidade na perda de determinadas informações de tipos. Para especificar este modo, passe `bsoncxx::ExtendedJsonMode::k_relaxed` como um argumento `mode` para o método `to_json()`.
Legacy	Um formato de string que descreve documentos BSON com alguma perda de informações de tipo. Este formato corresponde ao JSON estendido relaxado com algumas exceções. O driver C++ usa esse modo por padrão.

Observação

O driver C++ analisa o tipo de JSON estendido $uuid de uma string para um objeto b_binary 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": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "1601499771648" },
  "numViews": 36520312
}

Ler Extended JSON

Você pode ler uma string de Extended JSON em um documento C++ BSON chamando o método bsoncxx::from_json(). Este método analisa uma string de JSON estendida e retorna um bsoncxx::document::value contendo os dados.

O exemplo a seguir mostra como ler uma string de Extended JSON em um documento BSON usando o método from_json():

bsoncxx::document::value doc = bsoncxx::from_json(R"(
        {
            "_id": {"$oid": "507f1f77bcf86cd799439011"},
            "myNumber": {"$numberLong": "4794261"}
        }
    )");

Escrever JSON estendido

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

Observação

Versão legada

A opção de formato legado informa ao driver C++ para serializar os BSON types com o formato Libbson Legacy Extended JSON. O driver utiliza este modo como padrão .

Para obter mais informações, consulte a página JSON estendido legado na documentação da API do driver C.

O método bsoncxx::to_json() está disponível para vários tipos de bibliotecas principais e padrão, incluindo array e document. O exemplo a seguir converte um valor document em uma string de JSON estendida no formato canônico:

bsoncxx::builder::basic::document doc_builder;
doc_builder.append(kvp("myNumber", 11223344));
doc_builder.append(kvp("myString", "String value"));
bsoncxx::document::value doc = doc_builder.extract();
std::string json_str =
    bsoncxx::to_json(doc, bsoncxx::ExtendedJsonMode::k_canonical);
std::cout << json_str << std::endl;

{"myNumber":{"$numberInt":"11223344"},"myString":"String value"}

Informações adicionais

Documentação da API

Para saber mais sobre os tipos e métodos mencionados neste guia, consulte a seguinte documentação da API:

Páginas manuais do servidor

Para aprender mais sobre Extended JSON, consulte MongoDB Extended JSON (v2) no manual do MongoDB Server.

Voltar

BSON

Indexes