$convert (Conversão de Tipos)

Última atualização: 2026-10-09

$convert (Conversão de Tipos)

$convert converte um valor para um tipo BSON de destino e é o ponto de entrada mestre para conversões de tipos. O parâmetro to aceita double, string, objectId, bool, date, int, long e decimal. Falhas de conversão geram erro por padrão, mas onError fornece uma substituição; entrada null resulta em null por padrão e onNull o substitui. Usos típicos: transformar strings numéricas em números para aritmética ou analisar strings de data em datas. Comparado a atalhos como $toInt, $convert adiciona tratamento de falhas.

📝 Sintaxe

{ $convert: { input: <expressão>, to: <tipo>, onError: <substituição>, onNull: <resultado nulo> } }

⚙️ Parâmetros

Retorno：O valor convertido; onError/onNull se aplicam em caso de falha ou null

▶ Exemplo

Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):

// $convert: analisar preço em string para número, substituição 0
db.products.aggregate([
  { $project: {
      priceNum: { $convert: { input: '$priceStr', to: 'double', onError: 0 } }
  } }
])

Saída：

{ '_id': 1, 'priceNum': 19.9 }
{ '_id': 2, 'priceNum': 0 }

📌 Notas

• Falhas geram erro por padrão; sempre forneça onError em produção
• Entrada null resulta em null; substitua com onNull
• $toInt/$toDouble etc. são atalhos para $convert, mas sem onError

🏷️ Tags Relacionados

💡 Casos Relacionados

📚 Tutoriais Relacionados

❓ Perguntas Frequentes

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós