Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ /

MongoDB Extended JSON (v2)

Nesta página

  • Uso estendido do MongoDB JSON v2
  • Tipos de dados JSON e representações associadas
  • Exemplos

Importante

Desambiguação

A página a seguir aborda o MongoDB Extended JSON v2. Para saber mais sobre o Legacy MongoDB Extended JSON v1, consulte MongoDB Extended JSON (v1).

Para ver os tipos de dados suportados no mongosh, consulte a página Tipos de dados mongosh.

O JSON só pode representar diretamente um subconjunto dos tipos suportados pelo BSON. Para preservar informações de tipo, MongoDB adiciona as seguintes extensões ao formato JSON.

  • Modo canônico
    Um formato de string que enfatiza a preservação do tipo às custas de legibilidade e interoperabilidade. Ou seja, conversão de canônico para BSON geralmente preservará informações de tipo, exceto em certos casos específicos.
  • Modo relaxado
    Um formato de string que enfatiza a legibilidade e a interoperabilidade às custas da preservação do tipo. Ou seja, a conversão de formato relaxado para BSON pode perder informações de tipo.

Ambos os formatos estão em conformidade com o JSON RFC e podem ser analisados pelos vários drivers e ferramentas do MongoDB.

Os drivers a seguir usam o JSON estendido v2.0

  • C

  • C++

  • Go

  • Java

  • Node

  • Perl

  • PHPC

  • Python

  • Scala

Para C# e Ruby que usam Extended JSON do MongoDB herdado v1, consulte o Extended JSON do MongoDB (v1).

O MongoDB fornece os seguintes métodos para JSON estendido:

Método
Descrição
serialize

Serializa um objeto BSON e retorna os dados no formato JSON estendido.

EJSON.serialize( db.<collection>.findOne() )
deserialize

Converte um documento serializado em pares de campo e valor. Os valores têm tipos de JSON.

EJSON.deserialize( <serialized object> )
stringify

Converte os pares de elemento e tipo em um objeto desserializado para strings.

EJSON.stringify( <deserialized object> )
parse

Converte strings em pares de elementos e tipos .

EJSON.parse( <string> )

Para exemplos de uso, consulte Conversões de objeto JSON estendidas abaixo.

Para obter detalhes adicionais, consulte a documentação de:

A partir da versão 4.2:

Binário
Mudanças
Utiliza o formato JSON v2.0 estendido (modo canônico).

Usar JSON estendido v2.0 (Modo canônico) para os metadados. Requer a versão mongorestore 4.2 ou posterior que ofereça suporte a JSON estendido v2.0 (Modo canônico ou relaxado).

Em geral, use versões correspondentes de mongodump e mongorestore. Para restaurar arquivos de dados criados com uma versão específica do mongodump, use a versão correspondente do mongorestore.

Creates output data in Extended JSON v2.0 (Relaxed mode) by default.
Creates output data in Extended JSON v2.0 (Canonical mode) if used with --jsonFormat.
Expects import data to be in Extended JSON v2.0 (either Relaxed or Canonical mode) by default.
Can recognize data that is in Extended JSON v1.0 format if the option --legacy is specified.

Em geral, as versões do mongoexport e mongoimport devem corresponder. Para importar dados criados a partir de mongoexport, você deve usar a versão correspondente de mongoimport.

A seguir, são apresentados alguns tipos de dados BSON comuns e as representações associadas em Canonical e Relaxed.

A lista completa está aqui.

Array

Canônico
Descontraído
[ <elements> ]
<Same as Canonical>

Onde os elementos da array são os seguintes:

  • <elements>

    • Os elementos da array usam Extended JSON.

    • Para especificar uma array vazia, omita o conteúdo [ ].

Binary

Canônico
Descontraído
{ "$binary":
{
"base64": "<payload>",
"subType": "<t>"
}
}
<Same as Canonical>

Onde os valores são os seguintes:

  • "<payload>"

    • Cadeia de caracteres de carga codificada Base64 (com preenchimento como "=").

  • "<t>"

    • Uma string hexadecimal de um ou dois caracteres que corresponde a um subtipo binário BSON. Consulte a documentação estendida do bson http://bsonspec.org/spec.html para conhecer os subtipos disponíveis.

Date

Para datas entre os anos 1970 e 9999, inclusive:

Canônico
Descontraído
{"$date": {"$numberLong": "<millis>"}}
{"$date": "<ISO-8601 Date/Time Format>"}

Para datas anteriores ao ano 1970 ou posteriores ao ano 9999:

Canônico
Descontraído
{"$date": {"$numberLong": "<millis>"}}
<Same as Canonical>

Onde os valores são os seguintes:

  • "<millis>"

    • Um inteiro assinado de 64 bits como string. O valor representa milissegundos em relação à época.

  • "<ISO-8601 Date/Time Format>"

    • Uma data no formato ISO-8601 de data/hora da Internet como string.

    • A data/hora tem uma precisão de tempo máxima de milissegundos:

      • Segundos fracionários têm exatamente 3 casas decimais se a parte fracionária não for zero.

      • Caso contrário, segundos fracionários DEVEM ser omitidos se zero.

Decimal128

Canônico
Descontraído
{ "$numberDecimal": "<number>" }
<Same as Canonical>

Onde os valores são os seguintes:

Document

Canônico
Descontraído
{ <content> }
<Same as Canonical>

Onde o conteúdo do documento é o seguinte:

  • <content>

    • Nome:pares de valores que usam JSON estendido.

    • Para especificar um documento vazio, omita o conteúdo { }.

Double

Para números finitos:

Canônico
Descontraído
{"$numberDouble": "<decimal string>" }
<non-integer number>

Para números infinitos ou NAN:

Canônico
Descontraído
{"$numberDouble": <"Infinity"|"-Infinity"|"NaN"> }
<Same as Canonical>

Onde os valores são os seguintes:

  • "<decimal string>"

    • Um ponto flutuante assinado de 64-bit como uma string.

  • <non-integer number>

    • Um número não inteiro. Números inteiros são analisados como um inteiro em vez de um double.

Int64

Canônico
Descontraído
{ "$numberLong": "<number>" }
<integer>

Onde os valores são os seguintes:

  • "<number>"

    • Um inteiro assinado de 64 bits como string.

  • <integer>

    • Um número inteiro assinado de 64 bits.

Int32

Canônico
Descontraído
{ "$numberInt": "<number>" }
<integer>

Onde os valores são os seguintes:

  • "<number>"

    • Um inteiro assinado de 32 bits como string.

  • <integer>

    • Um número inteiro assinado de 32 bits.

MaxKey

Canônico
Descontraído
{ "$maxKey": 1 }
<Same as Canonical>

O tipo de dados MaxKey BSON compara mais alto do que todos os outros tipos. Consulte Comparação/Ordem de Classificação para obter mais informações sobre a ordem de comparação dos tipos de BSON.

MinKey

Canônico
Descontraído
{ "$minKey": 1 }
<Same as Canonical>

O tipo de dados MinKey BSON é comparado abaixo de todos os outros tipos. Consulte Comparação/Ordem de Classificação para obter mais informações sobre a ordem de comparação dos tipos de BSON.

ObjectId

Canônico
Descontraído
{ "$oid": "<ObjectId bytes>" }
<Same as Canonical>

Onde os valores são os seguintes:

  • "<ObjectId bytes>"

    • Uma cadeia hexadecimal grande e de 24 caracteres que representa os bytes ObjectId.

Regular Expression

Canônico
Descontraído
{ "$regularExpression":
{
"pattern": "<regexPattern>",
"options": "<options>"
}
}
<Same as Canonical>

Onde os valores são os seguintes:

  • "<regexPattern>"

    • Uma string que corresponde ao padrão de expressão regular. A string pode conter caracteres JSON válidos e caracteres de aspas duplas sem recapitulação ("), mas não pode conter caracteres de barra invertida sem recapitulação (/).

  • "<options>"

    • Uma string que especifica opções de expressão regular BSON. Você deve especificar as opções em ordem alfabética. Para obter informações sobre as opções aceitas, consulte $options.

Timestamp

Canônico
Descontraído
{"$timestamp": {"t": <t>, "i": <i>}}
<Same as Canonical>

Onde os valores são os seguintes:

  • <t>

    • Um número inteiro positivo para os segundos desde a época.

  • <i>

    • Um número inteiro positivo para o incremento.

Os exemplos a seguir ilustram o uso do JSON estendido.

Nome do campo de exemplo
Formato canônico
Formato relaxado
"_id:"
{"$oid":"5d505646cf6d4fe581014ab2"}
{"$oid":"5d505646cf6d4fe581014ab2"}
"arrayField":
["hello",{"$numberInt":"10"}]
["hello",10]
"dateField":
{"$date":{"$numberLong":"1565546054692"}}
{"$date":"2019-08-11T17:54:14,692Z"}
"dateBefore1970":
{"$date":{"$numberLong":"-1577923200000"}}
{"$date":{"$numberLong":"-1577923200000"}}
"decimal128Field":
{"$numberDecimal":"10,99"}
{"$numberDecimal":"10,99"}
"documentField":
{"a":"hello"}
{"a":"hello"}
"doubleField":
{"$numberDouble":"10,5"}
10.5
"infiniteNumber"
{"$numberDouble":"infinity"}
{"$numberDouble":"infinity"}
"int32field":
{"$numberInt":"10"}
10
"int64Field":
{"$numberLong":"50"}
50
"minKeyField":
{"$minKey":1}
{"$minKey":1}
"maxKeyField":
{"$maxKey":1}
{"$maxKey":1}
"regexField":
{"$regularExpression":{"pattern":"^H","options":"i"}}
{"$regularExpression":{"pattern":"^H","options":"i"}}
"timestampField":
{"$timestamp":{"t":1565545664,"i":1}}
{"$timestamp":{"t":1565545664,"i":1}}
"uuid":
{"$uuid":"3b241101-e2bb-4255-8caf-4136c566a962"}
{"$uuid":"3b241101-e2bb-4255-8caf-4136c566a962"}

Os exemplos curtos a seguir criam um objeto de documento e, em seguida, convertem o objeto em diferentes formas usando os métodos de conversão de objetos JSON estendidos .

Criar um documento na coleção conversions:

db.conversions.insertOne( { insertDate: new Date() } )

mongosh retorna um objeto de documento:

{
acknowledged: true,
insertedId: ObjectId("61fbaf25671c45f3f5f4074a")
}

Serialize os dados armazenados em um objeto de documento MongoDB:

serialized = EJSON.serialize( db.conversions.findOne() )

mongosh analisa um objeto JavaScript e retorna valores utilizando tipos de "$" com prefixo:

{
_id: { '$oid': '61fbaf25671c45f3f5f4074a' },
insertDate: { '$date': '2022-02-03T10:32:05.230Z' }
}

Deserializar um objeto serializado:

EJSON.deserialize( serialized )

mongosh analisa um objeto JavaScript e retorna valores usando o mongosh formulário de tipo padrão:

{
_id: new ObjectId( "61fbaf25671c45f3f5f4074a" ),
insertDate: ISODate( "2022-02-03T10:32:05.230Z" )
}

Converter um objeto em uma string:

stringified = EJSON.stringify( db.conversions.findOne() )

mongosh gera os elementos do objeto convertido como strings:

{
"_id": {"$oid":"61fbaf25671c45f3f5f4074a"},
"insertDate":{"$date":"2022-02-03T10:32:05.230Z"}
}

Analisar uma string para criar um objeto:

EJSON.parse( stringified )

mongosh retorna as strings convertidas como documentos:

{
_id: new ObjectId("61fbaf25671c45f3f5f4074a"),
insertDate: ISODate("2022-02-03T10:32:05.230Z")
}

Voltar

Ordem de comparação e classificação