Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

$converter (operador de expressão )

Definição

$convert

Converte um valor para um tipo especificado.

Compatibilidade

Você pode utilizar o $convert para implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

Alterado na versão 8.3.

{   $convert:      {         input: <expression>,         to: <type expression> || {            type: <type expression>,            subtype: <int>         },         base: <expression>,       // new in 8.3         format: <string>,         onError: <expression>,         onNull: <expression>      }}

$convert obtém um documento com os seguintes campos:

Campo
necessidade
Descrição

input

Obrigatório

O argumento pode ser qualquer expressão válida. Para mais informações sobre expressões, consulte Expressões.

A partir do MongoDB 8.1, você pode definir o campo to como binData se definir o campo input como um dos seguintes tipos:

  • int

  • long

  • double

A partir do MongoDB,8.3 você também pode definir o to campo como binData se o input campo for um array array de valores numéricos. Para exemplos, consulte Converter um array de valores numéricos em binData.

O MongoDB também suporta estes tipos numéricos como entrada ao converter um valor em binData.

A partir do MongoDB 9.0, se o campo input for resolvido como um objeto, você poderá definir o campo to como binData. Para exemplos, consulte Converter um objeto em binData.

to

Obrigatório

Especifica o tipo para converter a expressão input . Você pode definir to para um destes valores:

  • Uma string ou identificador numérico para o tipo de destino. Consulte to.type.

  • Um objeto contendo os campos to.type e to.subtype. Use este formato para converter para binData e especifique um subtipo de binData.

to.type

Obrigatório se especificar to como um objeto

O argumento pode ser qualquer expressão válida que resolva para um identificador numérico ou de string. Para identificadores disponíveis, consulte Identificadores de tipo.

to.subtype

Opcional

Se to.type for binData, to.subtype especifica o subtipo do binData a ser convertido. Para valores válidos, consulte Subtipos binários. Padrão: 0 (Subtipo binário genérico).

byteOrder

Opcional

Especifica a ordem de bytes endian big ou little para conversões entre binData e tipos numéricos. Se não for especificado, o padrão é ordenação de bytes little endian.

base

Opcional

Base de número inteiro para conversões entre tipos de string e numéricos.

  • Se null, $convert se comporta como se você tivesse omitido a base.

  • Se especificado, o MongoDB interpreta o valor na base escolhida ao converter entre strings e os tipos numéricos int, long, double e decimal. Para outras conversões, o MongoDB valida o valor de base, mas o ignora.

  • A base deve ser 2, 8, 10 ou 16.

Novidades na versão 8.3.

format

Obrigatório ao converter de ou para binData e string

Especifica o formato de conversões entre binData e string

  • base64

  • base64url

  • utf8

  • hex

  • uuid

Se format for uuid, to.subtype deve ser 4.

onError

Opcional

Valor a ser retornado ao encontrar um erro durante a conversão, incluindo conversões de tipo não suportadas. Os argumentos podem ser qualquer expressãoválida.

Se não for especificada, a operação gera um erro ao encontrar um erro e é interrompida.

onNull

Opcional

Valor a ser retornado se o input for nulo ou estiver ausente. Os argumentos podem ser qualquer expressão válida.

Se não for especificado, $convert retornará nulo se input for nulo ou estiver ausente.

Além de $convert, o MongoDB fornece os seguintes operadores de agregação como abreviação quando o comportamento padrão "onError" e "onNull" é aceitável:

Identificadores de tipo

O campo to.type aceita os seguintes identificadores numéricos e de string:

Identificador de string
Identificador numérico
Notas

"double"

1

"string"

2

"objeto"

3

"array"

4

"binData"

5

"objectId"

7

"bool"

8

"data"

9

"int"

16

"long"

18

"decimal"

19

Subtipos binários

A tabela a seguir lista os valores válidos para o campo to.subtype:

Número
Descrição

0

Subtipo binário genérico

1

Dados de Função

2

Binário (antigo)

3

UUID (antigo)

4

UUID

5

md5

6

Valor BSON criptografado

7

Dados de série temporal compactados

Novidades na versão 5.2.

8

Dados confidenciais, como uma chave ou segredo. O MongoDB não registra valores literais para dados binários com subtipo 8. Em vez disso, o MongoDB registra um valor de espaço reservado de ###.

9

Dados vetoriais, que são arrays densamente compactadas de números do mesmo tipo.

128

Dados personalizados

Comportamento

As seções a seguir descrevem como converter valores em diferentes tipos.

Converter em BinData

A partir do MongoDB 8.1, você pode definir o campo to como binData se definir o campo input como um dos seguintes tipos:

  • int

  • long

  • double

A partir do MongoDB 8.1, $convert retorna um erro ao tentar converter entre diferentes subtipos de binData. No MongoDB 8.0, $convert retorna o valor original e o subtipo original: nenhuma conversão é realizada. Versões do MongoDB anteriores a 8.0 não têm conversão binData.

Converter de tipos numéricos para binData:

Ao converter um tipo numérico para binData:

  • Um int se torna um 4-byte binData.

  • Um long se torna um 8-byte binData.

  • Um double se torna um 8-byte binData.

O byteOrder da saída numérica padroniza para "little", ou a colocação do byte menos significativo primeiro. Em contraste, "big" coloca o byte mais significativo primeiro.

Converta long em binData:

Entrada:

db.t.insertOne( { a: Long(42) } )
db.t.aggregate([  {    $project: {      _id: 0,      convertedBD: {        $convert: {           input: "$a",           to: "binData",      }    },  }}])

Saída:

[  {    convertedBD: Binary.createFromBase64('KgAAAAAAAAA=', 0)  }]

Converta long em binData com ordenação de bytes big-endian:

Entrada:

db.t.insertOne( { a: Long(42) } )
db.t.aggregate([  {    $project: {      _id: 0,      convertedBD: {        $convert: {           input: "$a",           to: "binData",           byteOrder: "big",        }      },    }  }])

Saída:

[  {    convertedBD: Binary.createFromBase64('AAAAAAAAACo=', 0),  }]

Converta double em binData:

Entrada:

db.t.insertOne( { a: Double(42.0) } )
db.t.aggregate([  {    $project: {      _id: 0,      convertedBD: {        $convert: {           input: "$a",           to: "binData",        }      },    }  }])

Saída:

[  {    convertedBD: Binary.createFromBase64('AAAAAAAARUA=', 0)  }]

Converta int em binData:

Entrada:

db.t.insertOne( { a: 42 } )
db.t.aggregate([  {    $project: {      _id: 0,      convertedBD: {        $convert: {           input: "$a",           to: "binData",        }      },    }  }])

Saída:

[  {    convertedBD: Binary.createFromBase64('KgAAAA==', 0)  }]

Converta uma array de valores numéricos para binData:

Este exemplo mostra como $convert converte arrays contendo diferentes tipos de valores numéricos em binData.

Entrada:

db.t.insertMany([    // Empty array    { a: [ ] },
    // Bool array    { a: [            false, true,  true,  true,            true,  true,  true,  true,            false, false, false, false,            false, true,  true,  true         ]    },
    // Int array     { a: [NumberInt(0), NumberInt(1), NumberInt(0), NumberInt(10)] },        // Double array     { a: [ Double(0.0), Double(1.0), Double(0.0), Double(1.0), Double(3.14) ] },])
db.t.aggregate([    {      $project: {        _id: 0,        original: "$a",        convertedVector: {          $convert: {            input: "$a",            to: { type: "binData" }           }        }      }    }])

Saída:

[  {    original: [],    convertedVector: Binary.fromPackedBits(new Uint8Array([]))  },  {    original: [      false, true,  true,  true,      true,  true,  true,  true,      false, false, false, false,      false, true,  true,  true    ],    convertedVector: Binary.fromPackedBits(new Uint8Array([ 127, 7 ]))  },  {    original: [ 0, 1, 0, 10 ],    convertedVector: Binary.fromInt8Array(new Int8Array([ 0, 1, 0, 10 ]))  },  {    original: [ 0, 1, 0, 1, 3.14 ],    convertedVector: Binary.fromFloat32Array(new Float32Array([ 0, 1, 0, 1, 3.140000104904175 ]))  }]

Converta um objeto para binData

Novidades na versão 9.0.

Quando o campo input é resolvido para um objeto e o campo to é binData, $convert retorna a representação BSON bruta do objeto. O subtipo do valor binData retornado é 0, a menos que você especifique um valor diferente em to.subtype.

Como a saída é o BSON bruto do objeto, a ordem dos campos do objeto e a ordem dos elementos em seus array afetam os bytes retornados.

$convert valida os campos format, byteOrder e base para esta conversão, mas esses campos não têm efeito na saída.

A tabela a seguir mostra exemplos de conversão de objeto para binData:

Exemplo
Resultados
{ input: {}, to: "binData" }
Binary.createFromBase64('BQAAAAA=', 0)
{   input: {      a: "hello",      b: { x: NumberInt(42), y: [NumberInt(1), NumberInt(2), NumberInt(3)] },      c: BinData(0, "AQIDBA==")   },   to: "binData"}
Binary.createFromBase64('SgAAAAJhAAYAAABoZWxsbwADYgApAAAAEHgAKgAAAAR5ABoAAAAQMAABAAAAEDEAAgAAABAyAAMAAAAAAAVjAAQAAAAAAQIDBAA=', 0)
{ input: { a: "a", b: "b" }, to: "binData" }
Binary.createFromBase64('FwAAAAJhAAIAAABhAAJiAAIAAABiAAA=', 0)
{ input: { b: "b", a: "a" }, to: "binData" }
Binary.createFromBase64('FwAAAAJiAAIAAABiAAJhAAIAAABhAAA=', 0)

A saída difere do exemplo anterior porque a ordem dos campos difere.

{ input: { a: [ NumberInt(1), NumberInt(2) ] }, to: "binData" }
Binary.createFromBase64('GwAAAARhABMAAAAQMAABAAAAEDEAAgAAAAAA', 0)
{ input: { a: [ NumberInt(2), NumberInt(1) ] }, to: "binData" }
Binary.createFromBase64('GwAAAARhABMAAAAQMAACAAAAEDEAAQAAAAAA', 0)

A saída difere do exemplo anterior porque a ordem dos elementos do array é diferente.

{ input: { a: "a" }, to: { type: 5, subtype: 128 } }
Binary.createFromBase64('DgAAAAJhAAIAAABhAAA=', 128)
{ input: { a: "a" }, to: "binData", format: "hex" }
Binary.createFromBase64('DgAAAAJhAAIAAABhAAA=', 0)

$convert ignora o campo format.

{ input: { a: "a" }, to: "binData", format: "bson" }

Error: Invalid 'format' argument for $convert: bson

$convert valida o campo format antes de ignorá-lo.

{ input: null, to: "binData" }

zero

Converter de string para BinData

O MongoDB também suporta conversões entre binData e strings.

Os exemplos seguintes demonstram como converter strings em binData.

Exemplo
Resultado
{   input: "hn3uUsMxSE6S0cVkebjmfg==",   to: {      type: "binData",      subtype: 0   },   format: "base64"}
Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)
{   input: "hn3uUsMxSE6S0cVkebjmfg==",   to: "binData",   format: "base64"}
Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)
{   input: "867dee52-c331-484e-92d1-c56479b8e67e",   to: {      type: "binData",      subtype: 0   },   format: "base64"}
Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'in $convert with no onError value: Input is not a valid base64string.
{   input: "hn3uUsMxSE6S0cVkebjmfg==",   to: {      type: "binData",      subtype: 4   },   format: "base64"}
Failed to parse BinData 'hn3uUsMxSE6S0cVkebjmfg==' in $convertwith no onError value: Input is not a valid base64 string.
{   input: "867dee52-c331-484e-92d1-c56479b8e67e",   to: {      type: "binData",      subtype: 4   },   format: "uuid"}
UUID('867dee52-c331-484e-92d1-c56479b8e67e')
{   input: "äöäöä",   to: {      type: "binData",      subtype: 4   },   format: "uuid"}
Failed to parse BinData 'äöäöä' in $convert with no onErrorvalue: Input is not a valid UUID string.
{   input: "867dee52-c331-484e-92d1-c56479b8e67e",   to: { type: "binData" },   format: "uuid"}
Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'in $convert with no onError value: Only the UUID subtype (4)is allowed with the 'uuid' format.

Observação

A partir do MongoDB 8.1, $convert retorna um erro ao tentar converter entre diferentes subtipos de binData. No MongoDB 8.0, $convert retorna o valor original e o subtipo original: nenhuma conversão é realizada. Versões do MongoDB anteriores a 8.0 não têm conversão binData.

Converter em array

Novidades na versão 8.3.

A tabela a seguir lista os tipos de input que podem ser convertidos em uma array:

Tipo de entrada
Comportamento

BinData

Retorna uma array de valores numéricos.

O tipo numérico dos elementos de array depende do formato binData.

String

Retorna uma array correspondente ao conteúdo dentro da string.

A string deve conter caracteres que representam uma array JSON válida.

Nulo ou Ausente

Retorna nulo.

A tabela a seguir lista alguns exemplos de conversão de string para array:

Exemplo
Resultados
{ input: "[1, 2, 3]", to: "array" }

[ 1, 2, 3 ]

{ input: '["a", "b", "c"]', to: "array" }

[ 'a', 'b', 'c' ]

{ input: "[]", to: "array" }

[ ]

{ input: "{}", to: "array" }

Erro: input não corresponde ao tipo esperado 'array'

{ input: 123, to: "array" }

Erro: conversão não suportada de int para array em $convert sem valor onError

{ input: "123", to: "array" }

Erro: o input não representa um JSON válido: valor autônomo inesperado

{ input: "[{\"$oid\": \"507f1f77bcf86cd799439011\"}]", to:"array" }

[ { '$oid': '507f1f77bcf86cd799439011' } ]

{ input: "[1, 2, 3]", to: "array", format: "base64url" }

[ 1, 2, 3 ]

{ input: "asdf", to: "array", onError: "on error!" }

'on error!'

{ input: null, to: "array", onNull: "on null!" }

'on null!'

Converter binData para Array

Este exemplo mostra como $convert converte binData de diferentes formatos em arrays contendo valores de seus respectivos tipos:

input:

db.t.insertMany([  // Empty PACKED_BIT vector converts to empty array  { v: BinData(9, "EAA=") },
  // PACKED_BIT vector converts to bool array  { v: BinData(9, "EAB/Bw==") },
  // INT8 vector converts to int array  { v: BinData(9, "AwAAAQ==") },
  // FLOAT32 vector converts to double array  { v: BinData(9, "JwCamZk+") },
  // FLOAT32 vector with special values converts to [-Infinity, 0, Infinity]  { v: BinData(9, "JwAAAID/AAAAAAAAgH8=") }])
db.t.aggregate([  {    $project: {      _id: 0,      original: "$v",      asArray: {        $convert: {          input: "$v",          to: { type: "array" }        }      }    }  }])

Saída:

[  { original: Binary.fromPackedBits(new Uint8Array([])), asArray: [] },  {    original: Binary.fromPackedBits(new Uint8Array([ 127, 7 ])),    asArray: [      false, true,  true,  true,      true,  true,  true,  true,      false, false, false, false,      false, true,  true,  true    ]  },  {    original: Binary.fromInt8Array(new Int8Array([ 0, 1 ])),    asArray: [ 0, 1 ]  },  {    original: Binary.fromFloat32Array(new Float32Array([ 0.30000001192092896 ])),    asArray: [ 0.30000001192092896 ]  },  {    original: Binary.fromFloat32Array(new Float32Array([ -Infinity, 0, Infinity ])),    asArray: [ -Infinity, 0, Infinity ]  }]

Converter em objeto

Novidades na versão 8.3.

A tabela a seguir lista os tipos de input que podem ser convertidos em um objeto:

Tipo de entrada
Comportamento

String

Retorna um document correspondente ao conteúdo dentro da string.

A string deve conter caracteres que representam um objeto JSON válido.

Nulo ou Ausente

Retorna nulo.

A tabela a seguir lista alguns exemplos de conversão para objeto :

Exemplo
Resultados
{ input: "{\"a\": 1, \"b\": 2}", to: "object" }

{ a: 1, b: 2 }

{ input: "{}", to: "object" }

{ }

{ input: "[]", to: "object" }

Erro: o input não corresponde ao tipo esperado "objeto"

{ input: "123", to: "object" }

Erro: o input não representa um JSON válido: valor autônomo inesperado

{ input: "{\"nam\\u0000e\": \"foo\"}", to: "object" }

Erro: o input não representa um JSON válido: byte nulo incorporado ilegal

{ input: "{\"name\": \"fo\\u0000o\"}", to: "object" }

{ name: 'fox00o' }

{ input: "{\"a\": 1, \"b\": 2, \"a\": 3}", to: "object" }

{ a: 3, b: 2 }

{ input: "{\"foo\": null}", to: "object" }

{foo: null }

{ input: "{\"foo\": false}", to: "object" }

{foo: false }

{ input: "{\"__proto__\": {\"foo\": null}}", to: "object" }

{ ['__proto__']: {foo: null } }

{ input: "{\"foo\": \"NaN\"}", to: "object" }

{ foo: 'NaN' }

{ input: "{\"foo\": 123}", to: "object" }

{foo: 123 }

{ input: "{\"foo\": 4294967296}", to: "object" }

{foo: Long('4294967296') }

{ input: "{\"foo\": 1.123123}", to: "object" }

{foo: 1.123123 }

{ input: "{\"foo\": 1.2e+3}", to: "object" }

{foo: 1200 }

{ input: "{\"largePos\": 18446744073709551615}", to: "object" }

{ largePos: 18446744073709552000 }

{ input: "{\"largeNeg\": -18446744073709551615}", to: "object" }

{ largeNeg: -18446744073709552000 }

{ input: null, to: "object" }

zero

{   input: "{\"objectId\": \"507f1f77bcf86cd799439011\",   \"uuid\": \"3b241101-e2bb-4255-8caf-4136c566a962\",   \"date\": \"2018-03-27T16:58:51.538Z\", \"regex\":   \"/^ABC/i\", \"js\": \"function (s) {return s +   \\\"foo\\\";}\", \"timestamp\": \"Timestamp(1565545664,   1)\", \"arr\": [1, 2, 3]}", to: "object"}

{
objectId: '507f1f77bcf86cd799439011',
uuid: '3b241101-e2bb-4255-8caf-4136c566a962',
date: '2018-03-27T16:58:51.538Z',
regex: '/^ABC/i',
js: 'function (s) {return s + "foo";}',
timestamp: 'Timestamp(1565545664, 1)',
arr: [ 1, 2, 3 ]
}

converter para booleano

A tabela a seguir lista os tipos de entrada que podem ser convertidos em booleanos:

Tipo de entrada
Comportamento

Array

Retorna verdadeiro

Dados binários

Retorna verdadeiro

Boolean

Sem operação. Retorna o valor booleano.

Código

Retorna verdadeiro

Data

Retorna verdadeiro

Decimal

Returns true if not zero
Return false if zero

Double

Returns true if not zero
Return false if zero

Inteiro

Returns true if not zero
Return false if zero

JavaScript

Retorna verdadeiro

Long

Returns true if not zero
Return false if zero

Tecla máxima

Retorna verdadeiro

Chave mín.

Retorna verdadeiro

Zero

Retorna o valor especificado para a opção onNull. Por padrão, retorna nulo.

Objeto

Retorna verdadeiro

ObjectId

Retorna verdadeiro

expressão regular

Retorna verdadeiro

String

Retorna verdadeiro

Timestamp

Retorna verdadeiro

Para aprender mais sobre os tipos de dados no MongoDB, consulte MongoDB BSON Types.

A tabela a seguir lista alguns exemplos de conversão para booleana:

Exemplo
Resultados
{ input: true, to: "bool" }

true

{ input: false, to: "bool" }

false

{ input: 1.99999, to: "bool" }

true

{ input: Decimal128( "5" ), to: "bool" }

true

{ input: Decimal128( "0" ), to: "bool" }

false

{ input: 100, to: "bool" }

true

{   input: ISODate( "2018-03-26T04:38:28.044Z" ),   to: "bool"}

true

{ input: "hello", to: "bool" }

true

{ input: "false", to: "bool" }

true

{ input: "", to: "bool" }

true

{ input: null, to: "bool" }

zero

converter para número inteiro

A tabela a seguir lista os tipos de entrada que podem ser convertidos para um número inteiro:

Tipo de entrada
Comportamento

Boolean

Retorna 0 para false.
Retorna 1 para true.

BinData

Retorna o valor binData como um número inteiro. binData é interpretado como o número inteiro assinado do complemento com sinal de dois.

O número de bytes no valor binData deve ser 1, 2 ou 4.

Se o input tiver um comprimento inesperado, um erro será gerado. Você pode controlar este comportamento configurando $convert.onError.

Double

Retorna valor truncado.

O valor double truncado deve cair dentro do valor mínimo e máximo para um número inteiro.

Você não pode converter um valor double cujo valor truncado é menor que o valor inteiro mínimo ou é maior que o valor inteiro máximo.

Decimal

Retorna valor truncado.

O valor decimal truncado deve cair dentro do valor mínimo e máximo para um número inteiro.

Você não pode converter um valor decimal cujo valor truncado é menor que o valor inteiro mínimo ou é maior que o valor inteiro máximo.

Inteiro

Nenhum oplog. Retorna o valor inteiro.

Long

Retorna o valor longo como um número inteiro.

O valor longo deve cair dentro do valor mínimo e máximo para um número inteiro.

Você não pode converter um valor longo que seja menor que o valor inteiro mínimo ou maior que o valor inteiro máximo.

String

Retorna o valor numérico da string como um número inteiro.

Se você omitir base ou definir como null, o valor da string deverá ser um número inteiro de base 10 válido e estar dentro do valor mínimo e máximo para um número inteiro.

Se você especificar base, a string deverá conter somente dígitos válidos nesta base. Prefixos, como "0x", não são permitidos. O número inteiro resultante deve estar dentro do valor mínimo e máximo para um número inteiro.

A tabela a seguir lista alguns exemplos de conversão para número inteiro:

Exemplo
Resultados
{ input: true, to: "int" }

1

{ input: false, to: "int" }

0

{ input: 1.99999, to: "int" }

1

{ input: Decimal128( "5.5000" ), to: "int" }

5

{   input: Decimal128( "9223372036000.000" ),   to: "int"}

Erro

{ input: Long( "5000" ), to: "int" }

5.000

{ input: Long( "922337203600" ), to: "int" }

Erro

{ input: "-2", to: "int" }

-2

{ input: "2.5", to: "int" }

Erro

{ input: null, to: "int" }

zero

{   input: Binary(Buffer.from("00100000", "hex"), 0),   to: "int",   byteOrder: "big",}

1048576

{   input: Binary(Buffer.from("FFFFE796", "hex"), 0),   to: "int",}

-1763180545

{   input: Binary(Buffer.from("001000000000000", "hex"), 0),   to: "int",   byteOrder: "big",}

Erro: falha ao converter BinData devido ao comprimento inválido: 7

converter para decimal

A tabela a seguir lista os tipos de entrada que podem ser convertidos em um número decimal:

Tipo de entrada
Comportamento

Boolean

Retorna Decimal128( "0" ) para false.
Retorna Decimal128( "1" ) para true.

Double

Retorna o valor double como decimal.

Decimal

Nenhum oplog. Retorna o decimal.

Inteiro

Retorna o valor int como decimal.

Long

Retorna o valor longo como decimal.

String

Retorna o valor numérico da string como decimal.

Se você omitir base ou definir como null, o valor da string deverá ser um decimal de base 10 válido e estar dentro do valor mínimo e máximo para um decimal.

Se você especificar base, a string deverá conter somente dígitos válidos nesta base. Prefixos, como "0x", não são permitidos. O decimal resultante deve estar dentro do valor mínimo e máximo para um decimal.

Data

Retorna o número de milissegundos desde a época que corresponde ao valor de data.

A tabela a seguir lista alguns exemplos de conversão para decimal:

Exemplo
Resultados
{ input: true, to: "decimal" }

Decimal128("1")

{ input: false, to: "decimal" }

Decimal128("0")

{ input: 2.5, to: "decimal" }

Decimal128( "2,50000000000000" )

{ input: Int32( 5 ), to: "decimal" }

Decimal128("5")

{ input: Long( 10000 ), to: "decimal" }

Decimal128("10.000")

{ input: "-5.5", to: "decimal" }

Decimal128("-5,5")

{   input: ISODate( "2018-03-26T04:38:28.044Z" ),   to: "decimal"}

Decimal128("1522039108044")

converter para double

A tabela a seguir lista os tipos de entrada que podem ser convertidos em double:

Tipo de entrada
Comportamento

Boolean

Retorna NumberDouble(0) para false.
Retorna NumberDouble(1) para true.

BinData

Retorna o valor binData como um valor duplo. binData é interpretado como um ponto flutuante de precisão única ou precisão dupla IEEE 754 .

O número de bytes no valor binData deve ser 4 ou 8.

Se o input tiver um comprimento inesperado, um erro será gerado. Você pode controlar este comportamento configurando $convert.onError.

Double

Nenhum oplog. Retorna o double.

Decimal

Retorna o valor decimal como double.

O valor decimal deve cair dentro do valor mínimo e máximo para um double.

Você não pode converter um valor decimal cujo valor é menor que o double mínimo ou maior que o double máximo.

Inteiro

Retorna o valor inteiro como double.

Long

Retorna o valor longo como double.

String

Retorna o valor numérico da string como double.

Se você omitir base ou definir como null, o valor da string deverá ser uma base válida 10 double e estar dentro do valor mínimo e máximo para um valor double.

Se você especificar base, a string deverá conter somente dígitos válidos nesta base. Prefixos, como "0x", não são permitidos. O double resultante deve estar dentro do valor mínimo e máximo para um double.

Data

Retorna o número de milissegundos desde a época que corresponde ao valor de data.

A tabela a seguir lista alguns exemplos de conversão em double:

Exemplo
Resultados
{ input: true, to: "double" }

1

{ input: false, to: "double" }

0

{ input: 2.5, to: "double" }

2.5

{ input: Int32( 5 ), to: "double" }

5

{ input: Long( "10000" ), to: "double" }

10.000

{ input: "-5.5", to: "double" }

-5.5

{ input: "5e10", to: "double" }

50000000000

{   input: ISODate( "2018-03-26T04:38:28.044Z" ),   to: "double"}

1522039108044

{   input: Binary(Buffer.from("04CCCCCD", "hex"), 0),   to: "double",   byteOrder: "big",}

4.814824932714571e-36

{   input: Binary(Buffer.from("0000", "hex"), 0),   to: "double",   byteOrder: "big",}

Erro: falha ao converter binData devido ao comprimento inválido: 2

Números subnormais

A partir do MongoDB 8.3, o servidor é capaz de analisar toda a faixa de todos os números de double de ponto flutuante de precisão representáveis. Isso inclui números subnormais em que o dígito mais significativo tem zeros à esquerda e o expoente tem o menor valor possível. Para obter detalhes, consulte Número subnormal.

Nas versões anteriores do MongoDB, o servidor retorna um erro quando você tenta analisar esses números. O exemplo a seguir gera um erro em versões anteriores ao MongoDB 8.3:

db.t.insertOne( { v: "7.08263e-317" } )
db.t.aggregate([  {    $project: {      converted: {        $convert: { input: "$v", to: "double" },      }    }   }])

Este exemplo falha com um erro semelhante ao seguinte:

MongoServerError[ConversionFailure]: Executor error during aggregate command on namespace: test.t ::caused by :: Failed to parse number '7.08263e-317' in $convert with no onError value: Out of range

converter para longo

A tabela a seguir lista os tipos de entrada que podem ser convertidos para um longo:

Tipo de entrada
Comportamento

Boolean

Retorna 0 para false.
Retorna 1 para true.

BinData

Retorna o valor binData como um longo. binData é interpretado como o número inteiro assinado do complemento com sinal de dois.

O número de bytes no valor binData deve ser 1, 2 4 ou 8.

Se o input tiver um comprimento inesperado, um erro será gerado. Você pode controlar este comportamento configurando $convert.onError.

Double

Retorna valor truncado.

O valor double truncado deve cair dentro do valor mínimo e máximo por um longo período.

Você não pode converter um valor double cujo valor truncado é menor que o valor mínimo longo ou é maior que o valor máximo longo.

Decimal

Retorna valor truncado.

O valor decimal truncado deve cair dentro do valor mínimo e máximo por um longo período.

Não é possível converter um valor decimal cujo valor truncado seja menor que o valor longo mínimo ou maior que o valor longo máximo.

Inteiro

Retorna o valor int como um longo.

Long

Sem operação. Retorna o valor longo.

String

Retorna o valor numérico da string.

Se você omitir base ou definir como null, o valor da string deverá ter uma base válida de 10 comprimento e estar dentro do valor mínimo e máximo por um longo período.

Se você especificar base, a string deverá conter somente dígitos válidos nesta base. Prefixos, como "0x", não são permitidos. O longo resultante deve estar dentro do valor mínimo e máximo para um longo.

Data

Converte a data para o número de milissegundos desde a época.

A tabela a seguir lista alguns exemplos de conversão:

Exemplo
Resultados
{ input: true, to: "long" }

Long("1")

{ input: false, to: "long"  }

Long("0")

{ input: 2.5, to: "long"  }

Longo("2")

{ input: Decimal128( "5.5000" ), to: "long" }

Long("5")

{   input: Decimal128( "9223372036854775808.0" ),   to: "long"}

Erro

{ input: Int32( 8 ), to: "long" }

Long("8")

{   input: ISODate( "2018-03-26T04:38:28.044Z" ),   to: "long"}

Long("1522039108044")

{ input: "-2", to: "long" }

Long("-2")

{ input: "2.5", to: "long" }

Erro

{ input: null, to: "long" }

zero

{   input: Binary(Buffer.from("001000000", "hex"), 0),   to: "long",   byteOrder: "big",}

Long("1048576")

converter em data

A tabela a seguir lista os tipos de entrada que podem ser convertidos em uma data:

Tipo de entrada
Comportamento

Double

Retorna uma data que corresponde ao número de milissegundos representado pelo valor double truncado.

O número positivo corresponde ao número de milissegundos desde 1° de janeiro de 1970.

O número negativo corresponde ao número de milissegundos antes de 1° de janeiro de 1970.

Decimal

Retorna uma data que corresponde ao número de milissegundos representados pelo valor decimal truncado.

O número positivo corresponde ao número de milissegundos desde 1° de janeiro de 1970.

O número negativo corresponde ao número de milissegundos antes de 1° de janeiro de 1970.

Long

Retorna uma data que corresponde ao número de milissegundos representados pelo valor longo.

O número positivo corresponde ao número de milissegundos desde 1° de janeiro de 1970.

O número negativo corresponde ao número de milissegundos antes de 1° de janeiro de 1970.

String

Retorna uma data que corresponde à string de data.

A string deve ser uma string de data válida, como:

  • "2018-03-03"

  • "2018-03-03T12:00:00Z"

  • "2018-03-03T12:00:00+0500"

ObjectId

Retorna uma data que corresponde ao carimbo de data/hora do ObjectId.

Timestamp

Retorna uma data que corresponde ao carimbo de data/hora.

A tabela a seguir lista alguns exemplos de conversão em data:

Exemplo
Resultados
{   input: 120000000000.5,   to: "date"}

ISODATE("1973-10-20T21:20:00,000Z")

{   input: Decimal128( "1253372036000.50" ),   to: "date"}

ISODATE("2009-09-19T14:53:56,000Z")

{   input: Long( "1100000000000" ),   to: "date}

ISODATE("2004-11-09T11:33:20,000Z")

{   input:  Long( "-1100000000000" ),   to: "date"}

ISODATE("1935-02-22T12:26:40,000Z")

{   input: ObjectId( "5ab9c3da31c2ab715d421285" ),   to: "date"}

ISODATE("2018-03-27T04:08:58,000Z")

{ input:  "2018-03-03", to: "date" }

ISODATE("2018-03-03T00:00:00,000Z")

{   input: "2018-03-20 11:00:06 +0500",   to: "date"}

ISODATE("2018-03-20T06:00:06,000Z")

{ input: "Friday", to: "date" }

Erro

{   input: Timestamp( { t: 1637688118, i: 1 } ),   to: "date"}

ISODATE("2021-11-23T17:21:58,000Z")

converter para ObjectId

A tabela a seguir lista os tipos de entrada que podem ser convertidos para um ObjectId:

Tipo de entrada
Comportamento

String

Retorna um ObjectId para a string hexadecimal de comprimento 24.

Não é possível converter um valor de string que não seja uma string hexadecimal de comprimento 24.

A tabela a seguir lista alguns exemplos de conversão em data:

Exemplo
Resultados
{   input: "5ab9cbfa31c2ab715d42129e",   to: "objectId"}

ObjectId("5ab9cbfa31c2ab715d42129e")

{   input: "5ab9cbfa31c2ab715d42129",   to: "objectId"}

Erro

converter em string

A tabela a seguir lista os tipos de entrada que podem ser convertidos em uma string:

Tipo de entrada
Comportamento

Array

Retorna o Array como uma string.

Novidades na versão 8.3.

BinData

Se o BinData for um UUID, retorna o UUID como uma string. Caso contrário, retorna o valor da string codificada base64.

Boolean

Retorna o valor booleano como uma string.

Data

Retorna o Date como uma string.

Decimal

Retorna o valor Decimal como uma string.

Double

Retorna o valor Double como uma string.

Inteiro

Retorna o valor Integer como uma string.

Long

Retorna o valor Long como uma string.

Tecla máxima

Retorna o MaxKey como uma string.

Novidades na versão 8.3.

Chave mín.

Retorna o MinKey como uma string.

Novidades na versão 8.3.

Objeto

Retorna o objeto como uma string.

Novidades na versão 8.3.

ObjectId

Retorna o valor ObjectId como uma string hexadecimal.

Expressão regular

Retorna o Regular Expression como uma string.

Novidades na versão 8.3.

String

Nenhuma operação. Retorna o valor da string.

Timestamp

Retorna o Timestamp como uma string.

Novidades na versão 8.3.

Observação

Quando você especifica base e o input é um tipo numérico, $convert retorna a representação de string do valor inteiro nessa base. A conversão de base para strings só é permitida para valores inteiros; caso contrário, $convert retorna um erro de conversão, a menos que você especifique onError.

A tabela a seguir lista alguns exemplos de conversão para string:

Exemplo
Resultados
{ input: true, to: "string" }

"verdadeiro"

{ input: false, to: "string" }

"falso"

{ input: 2.5, to: "string" }

"2,5"

{ input: Int32( 2 ), to: "string" }

"2"

{ input:  Long( 1000 ), to: "string" }

"1.000"

{   input: ObjectId( "5ab9c3da31c2ab715d421285" ),   to: "string"}

"5ab9c3da31c2ab715d421285"

{   input:  ISODate( "2018-03-27T16:58:51.538Z" ),   to: "string"}

"2018-03-27T16:58:51.538Z"

{   input: BinData(4, "hn3f"),   to: "string",   format: "base64"}

'hn3f'

{   input: 10.5,   to: "string",   base: 2,   onError: "invalid"}

"inválido"

Exemplos

Os exemplos nesta página usam dados do conjunto de dados sample_mflix. Para obter detalhes sobre como carregar este conjunto de dados em sua implantação do MongoDB autogerenciado, consulte Carregar o conjunto de dados de amostra. Se você fez alguma modificação nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

Exemplo de conversão de base

As strings hexadecimais são uma forma compacta de representar números inteiros, e muitos sistemas trocam identificadores como valores hexadecimais. O exemplo a seguir converte o imdb.id numérico de cada filme em uma string hexadecimal:

db.movies.aggregate( [   { $match: { title: { $in: [      "The Godfather",      "Toy Story",      "Metropolis"   ] } } },   { $sort: { title: 1 } },   {      $project: {         _id: 0,         title: 1,         imdbId: "$imdb.id",         hexId: { $convert: { input: "$imdb.id", to: "string", base: 16 } }      }   }] )
[  {    title: 'Metropolis',    imdbId: 293416,    hexId: '47A28'  },  {    title: 'The Godfather',    imdbId: 68646,    hexId: '10C26'  },  {    title: 'Toy Story',    imdbId: 114709,    hexId: '1C015'  }]

Para converter uma string hexadecimal de volta para um número inteiro, passe a string para $convert com base: 16 e to: "int".

Exemplo de conversão de tipo

A seguinte operação de agregação converte o campo imdb.rating, que é um double na maioria dos documento, mas uma string vazia em outros, para um double. Ele também converte o campo metacritic, que está ausente em alguns documento, para um inteiro. O estágio $match seleciona três filmes que ilustram cada resultado de conversão:

db.movies.aggregate( [   { $match: { title: { $in: [      "The Danish Girl",      "The Godfather",      "Gertie the Dinosaur"   ] } } },   {      $project: {         _id: 0,         title: 1,         rating: {            $convert: {               input: "$imdb.rating",               to: "double",               onError: "Error",               onNull: 0            }         },         metacritic: {            $convert: {               input: "$metacritic",               to: "int",               onError: "Error",               onNull: 0            }         }      }   },   { $sort: { title: 1 } }] )
[  {    title: 'Gertie the Dinosaur',    rating: 7.3,    metacritic: 0  },  {    title: 'The Danish Girl',    rating: 'Error',    metacritic: 0  },  {    title: 'The Godfather',    rating: 9.2,    metacritic: 100  }]

Para The Danish Girl, a string vazia em imdb.rating não pode ser convertida em um double, portanto onError retorna "Error". Para Gertie the Dinosaur e The Danish Girl, metacritic está ausente, portanto onNull retorna 0.

Observação

Esses exemplos usam mongosh. Os tipos padrão são diferentes no shell mongo legado.

Saiba mais

  • Converta um valor para uma array com $toArray

  • Converta uma string em um objeto com $toObject

  • Converta um valor em booleano com $toBool

  • Converta um valor em um número inteiro com $toInt

  • Converta um valor para um decimal com $toDecimal

  • Converta um valor em um double com $toDouble

  • Converta um valor em um longo com $toLong

  • Converta um valor para uma data com $toDate

  • Converter um valor para um ObjectId com $toObjectId

  • Converta um valor em uma string com $toString

  • Converta uma string de data em um objeto de data com $dateFromString

  • Converta um objeto de data em uma string com $dateToString

Voltar
$cond
Próximo
$cos
Avalie esta página

Nesta página