$converter (agregação)

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplo

O MongoDB 5.0 é o fim da vida útil a partir de de 2024 outubro. Esta versão da documentação não é mais suportada. Para atualizar sua 5.0 implantação do, consulte o MongoDB 6.0 procedimentos de atualizaçã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

$convert tem a seguinte sintaxe:

{
 $convert:
     {
        input: <expression>,
        to: <type expression>,
        onError: <expression>,  // Optional.
        onNull: <expression>    // Optional.
      }
}

O $convert pega um documento com os seguintes campos:

Campo

Descrição

input

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

to

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 Convertendo para dupla.
"string"	2	Para obter mais informações sobre a conversão em cadeia de caracteres, consulte Convertendo em uma cadeia de caracteres.
"objectId"	7	Para obter mais informações sobre a conversão para ObjectId, consulte Convertendo para um ObjectId.
"bool"	8	Para obter mais informações sobre a conversão para booleana, consulte Convertendo para booleana.
"data"	9	Para obter mais informações sobre a conversão para data,consulte Conversão para uma data.
"int"	16	Para obter mais informações sobre a conversão para um número inteiro, consulte Conversão para um número inteiro.
"long"	18	Para obter mais informações sobre a conversão para longo,consulte Conversão para longo.
"decimal"	19	Para obter mais informações sobre a conversão para decimal, consulte Convertendo para decimal.

onError

Opcional. O 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. O valor a devolver se o input for nulo ou estiver ausente. Os argumentos podem ser qualquer expressãová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

Convertendo para um 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

Convertendo para um 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.

Convertendo para um 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

Convertendo em double

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

Tipo de entrada	Comportamento
Boolean	Returns NumberLong(0) for `false`. Returns NumberLong(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

Convertendo para um 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

Convertendo para uma 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.

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

"Não foi possível converter para data de tipo."

Dica

Veja também:

$toDate operador, operador
$dateFromString

Convertendo para um 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.

Convertendo em uma string

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

Tipo de entrada	Comportamento
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"

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