/ /

Expressões

Página inicial do Docs

Desenvolvimento

Linguagem de query

Expressões

Página inicial do Docs

Desenvolvimento

Linguagem de query

Expressões

$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 de valores numéricos. Para obter exemplos, consulte Converter uma array de valores numéricos em binData.

O MongoDB também suporta estes tipos numéricos como entrada ao converter um valor 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 dos seguintes identificadores numéricos ou de cadeia de caracteres:

Identificador de string	Identificador numérico	Notas
"double"	1	Para obter mais informações sobre a conversão para dupla, consulte Converter para dupla.
"string"	2	Para obter mais informações sobre a conversão em cadeia de caracteres, consulte Converter em cadeia de caracteres.
"objeto"	3	Para obter mais informações sobre a conversão para um objeto, consulte Converter para objeto.
"array"	4	Para obter mais informações sobre a conversão em array, consulte Converter em array.
"binData"	5	Para obter mais informações sobre a conversão para binData, consulte Converter para BinData.
"objectId"	7	Para obter mais informações sobre a conversão para ObjectId, consulte Converter para ObjectId.
"bool"	8	Para obter mais informações sobre a conversão para booleana, consulte Converter para booleana.
"data"	9	Para obter mais informações sobre a conversão para data, consulte Converter para data.
"int"	16	Para obter mais informações sobre a conversão para número inteiro, consulte Converter para número inteiro.
"long"	18	Para obter mais informações sobre a conversão para longo, consulte Converter para longo.
"decimal"	19	Para obter mais informações sobre a conversão para decimal, consulte Converter para decimal.

to.subtype

Opcional

Se to.type for binData, to.subtype especifica o subtipo do binData a ser convertido. Você pode especificar um destes valores para 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

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.

nullSe, se comporta como se você omitisse a$convert 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, retornará nulo$convert 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:

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 ]))
  }
]

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

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "base64"
}

Failed to parse BinData 'hn3uUsMxSE6S0cVkebjmfg==' in $convert
with 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 onError
value: 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

Converter em array

Novidades na versão 8.3.

A tabela a seguir lista os tipos de entrada 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: a entrada 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: a entrada 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 ]

Observação

A opção format é ignorada.

{ 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:

Entrada:

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 entrada que podem ser convertidos em um objeto:

Tipo de entrada	Comportamento
String	Retorna um documento 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: a entrada não corresponde ao tipo esperado "objeto"

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

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

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

Erro: a entrada 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 saber mais sobre os tipos de dados no MongoDB, consulte a página 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	Returns `0` for `false`. Returns `1` for `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 `null` como, o valor da string deverá ser um número inteiro de base ₁₀ 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" }

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

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

{
   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	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `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 `null` como, o valor da string deverá ser um ₁₀ decimal de base 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	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `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 `null` como, o valor da string deverá ser uma base válida dupla e estar dentro do valor mínimo e máximo para um valor ₁₀ duplo. Se você especificar `base`, a string deverá conter somente dígitos válidos nesta base. Prefixos, como `"0x"`, não são permitidos. O valor duplo resultante deve estar dentro do valor mínimo e máximo para um valor duplo.
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" }

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

2.5

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

{ 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 gama de todos os números de ponto flutuante de precisão dupla 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	Returns `0` for `false`. Returns `1` for `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 `null` como, o valor da string deverá ter uma base válida de 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 como uma `Array` 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 como uma `Date` string.
Decimal	Retorna o valor como uma `Decimal` string.
Double	Retorna o valor como uma `Double` string.
Inteiro	Retorna o valor como uma `Integer` string.
Long	Retorna o valor como uma `Long` string.
Tecla máxima	Retorna como uma `MaxKey` string. Novidades na versão 8.3.
Chave mín.	Retorna como uma `MinKey` string. Novidades na versão 8.3.
Objeto	Retorna o objeto como uma string. Novidades na versão 8.3.
ObjectId	Retorna o valor como uma string `ObjectId` hexadecimal.
Expressão regular	Retorna como uma `Regular Expression` string. Novidades na versão 8.3.
String	Nenhuma operação. Retorna o valor da string.
Timestamp	Retorna como uma `Timestamp` 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;$convert caso contrário, retorna um erro de conversão, a menos que você onError especifique.

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

Exemplo de conversão de base

Crie uma collection examples com um documento de espaço reservado :

db.examples.insertOne({ _id: 1 })

O exemplo a seguir converte entre números e strings usando bases diferentes:

db.examples.aggregate([
  {
    $project: {
      _id: 0,
      bin:        { $convert: { input: 10,    to: "string", base: 2  } },
      hex:        { $convert: { input: 10,    to: "string", base: 16 } },
      intFromBin: { $convert: { input: "1010", to: "int",   base: 2  } },
      intFromHex: { $convert: { input: "A",    to: "int",   base: 16 } }
    }
  }
])

Esta operação retorna o seguinte documento:

{
  bin: "1010",
  hex: "A",
  intFromBin: 10,
  intFromHex: 10
}

Exemplo de conversão de tipo

Crie uma collection orders com os seguintes documentos:

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds" },
   { _id: 5, item: "bananas", qty: 5000000000, price: Decimal128("1.25") }
] )

A seguinte operação de agregação na coleção orders converte o price para um decimal:

// Define stage to add convertedPrice and convertedQty fields with
//    the converted price and qty values.
// If price or qty values are missing, the conversion returns a
//    value of decimal value or int value of 0.
// If price or qty values cannot be converted, the conversion returns
//    a string
priceQtyConversionStage = {
   $addFields: {
      convertedPrice: { $convert:
         {
            input: "$price",
            to: "decimal",
            onError: "Error",
            onNull: Decimal128("0")
         } },
      convertedQty: { $convert:
         {
            input: "$qty",
            to: "int",
            onError:{ $concat:
               [
                  "Could not convert ",
                  { $toString:"$qty" },
                  " to type integer."
               ]
            },
         onNull: Int32("0")
      } },
   }
};
totalPriceCalculationStage = {
   $project: { totalPrice: {
     $switch: {
        branches: [
          { case:
             { $eq: [ { $type: "$convertedPrice" }, "string" ] },
             then: "NaN"
          },
          { case:
             { $eq: [ { $type: "$convertedQty" }, "string" ] },
             then: "NaN"
          },
        ],
        default: { $multiply: [ "$convertedPrice", "$convertedQty" ] }
     }
} } };
db.orders.aggregate( [
   priceQtyConversionStage,
   totalPriceCalculationStage
])

A operação retorna os seguintes documentos:

{ _id: 1, totalPrice: Decimal128("50") },
{ _id: 2, totalPrice: Decimal128("200.0") },
{ _id: 3, totalPrice: Decimal128("9.98") },
{ _id: 4, totalPrice: Decimal128("0") },
{ _id: 5, totalPrice: 'NaN' }

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 valor duplo 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

$cos

Definição

Compatibilidade

Sintaxe

Comportamento

Converter em BinData

Converter de tipos numéricos para binData:

Converter de string para BinData

Observação

Converter em array

Observação

Converter binData para Array

Converter em objeto

converter para booleano

converter para número inteiro

converter para decimal

converter para double

Números subnormais

converter para longo

converter em data

converter para ObjectId

converter em string

Observação

Exemplos

Exemplo de conversão de base

Exemplo de conversão de tipo

Observação

Saiba mais

Converter de tipos numéricos para `binData`: