$converter (agregação)

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplo

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

{
   $convert:
      {
         input: <expression>,
         to: <type expression> || {
            type: <type expression>,
            subtype: <int>
         },
         format: <string>,
         onError: <expression>,
         onNull: <expression>
      }
}

O $convert pega 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 Operadores de Expressão.

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 especificar um subtipo 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 double, consulte Converter para double.
"string"	2	Para obter mais informações sobre a conversão para string, consulte Converter para string.
"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 booleano, consulte Converter para booleano.
"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 um número inteiro, consulte Converter para um número inteiro.
"long"	18	Para obter mais informações sobre a conversão para long, consulte Converter para long.
"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)

format

Necessário na conversão de ou para binData.

Especifica o formato binData da entrada ou saída. Pode ser um destes valores:

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:

Comportamento

Converter em BinData

Você só pode converter strings em binData. Todos os outros tipos de entrada resultam em erro.

Veja as seguintes conversões de exemplo para 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.

{
   input: 123,
   to: { type: "binData", subtype: 0 }
}

Unsupported conversion from int to binData in $convert with no onError value

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

Dica

Veja também:

$toBool

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`.
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. O valor da string deve ser um inteiro de base ₁₀ (por exemplo, `"-5"`, `"123456"`) e estão dentro do valor mínimo e máximo para um inteiro. Não é possível converter um valor de string de um número float, decimal ou não base ₁₀ (por exemplo `"-5.0"`, `"0x6400"`) ou um valor que está fora do valor mínimo e máximo de 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

Dica

Veja também:

$toInt operador.

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. O valor da string deve ter um valor numérico ₁₀ de base (por exemplo, `"-5.5"`, `"123456"`). Não é possível converter um valor de string de um número ₁₀ que não seja de base (por exemplo, `"0x6400"`)
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")

Dica

Veja também:

$toDecimal

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`.
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. O valor da string deve ser de um valor numérico ₁₀ de base (por exemplo, `"-5.5"`, `"123456"`) e cair dentro do valor mínimo e máximo para um double. Você não pode converter um valor de string de um número ₁₀ que não seja de base (por exemplo, `"0x6400"`) ou um valor que está fora 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" }

{ 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

Dica

Veja também:

$toDouble

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`.
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. O valor da string deve ter uma base ₁₀ de comprimento (por exemplo. `"-5"`, `"123456"`) e ficam dentro do valor mínimo e máximo por um longo período. Você não pode converter um valor de string de um número flutuante ou decimal ou sem base ₁₀ (por exemplo `"-5.0"`, `"0x6400"`) ou um valor que fica fora do valor mínimo e máximo por um longo período.
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

Dica

Veja também:

$toLong

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")

Dica

Veja também:

$toDate operador, operador
$dateFromString

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

Dica

Veja também:

$toObjectId operador.

converter em string

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

Tipo de entrada	Comportamento
BinData	Retorna o valor de dados binários como uma string.
Boolean	Retorna o valor booleano como uma string.
Double	Retorna o valor double como string.
Decimal	Retorna o valor decimal como uma string.
Inteiro	Retorna o valor inteiro como uma string.
Long	Retorna o valor longo como uma string.
ObjectId	Retorna o valor ObjectId como uma string hexadecimal.
String	Nenhum oplog. Retorna o valor da string.
Data	Retorna a data como uma string.

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'

Dica

Veja também:

$toString operador, operador
$dateToString

Exemplo

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.

Voltar

$cond

$cos