/ /

$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: The fully managed service for MongoDB deployments in the cloud

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

The $convert takes a document with the following fields:

Campo	Descrição
`input`	O argumento pode ser qualquer expressão válida. Para mais informações sobre expressões, consulte Expressões.
`to`	The argument can be any valid expression that resolves to a numeric or string identifier. For available identifiers, see Type Identifiers.
`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. If unspecified, `$convert` returns null if the `input` is null or missing.

In addition to $convert, MongoDB provides the following aggregation operators as shorthand when the default "onError" and "onNull" behavior is acceptable:

Identificadores de tipo

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

Identificador de string	Identificador numérico	Notas
"double"	1	See Converting to a Double.
"string"	2	See Converting to a String.
"objectId"	7	See Converting to an ObjectId.
"bool"	8	See Converting to a Boolean.
"data"	9	See Converting to a Date.
"int"	16	See Converting to an Integer.
"long"	18	See Converting to a Long.
"decimal"	19	See Converting to a Decimal.

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

$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	Retorna `0` para `false`. Retorna `1` para `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

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

$toDecimal

Convertendo em 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`.
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

$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	Retorna `0` para `false`. Retorna `1` para `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

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

$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

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

{
   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 maneira 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 campoimdb.rating , que é um double na maioria dos documentos, mas uma string vazia em outros, para um double. Ele também converte o campometacritic , que está faltando em alguns documentos, para um número inteiro. O estágio $match seleciona três filmes que ilustram cada resultado da 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 valor duplo, então onError retorna "Error". Para Gertie the Dinosaur e The Danish Girl, metacritic está ausente, então onNull retorna 0.

Observação

These examples use mongosh. The default types are different in the legacy mongo shell.

Voltar

$cond

$cos