$toObjectId (Converter para ObjectId)
Última atualização: 2026-10-09
$toObjectId (Converter para ObjectId)
$toObjectId converte uma string hexadecimal de 24 caracteres em um ObjectId, a conversão mais comum para junções. Usos típicos: converter IDs em string importados de CSV ou APIs em ObjectIds para $lookup, ou comparar valores de _id em string com ObjectIds em $match. A string precisa ser um literal ObjectId válido ou a conversão gera erro; null permanece null. Prefira $convert com onError para proteger entrada inválida.
| Categoria | Conjunto, Condição e Conversão |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $toObjectId: <expressão> }⚙️ Parâmetros
| expressão | Uma string hexadecimal de 24 caracteres. |
|---|
Retorno：Um ObjectId; null quando a entrada é null
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $toObjectId: converter um ID em string para junção
db.orders.aggregate([
{ $project: {
uid: { $toObjectId: '$userIdStr' }
} }
])Saída：
{ '_id': 1, 'uid': { '$oid': '64b7f1c2e4b0a1b2c3d4e5f6' } }📌 Notas
- A string precisa ter 24 caracteres hexadecimais; qualquer outra coisa gera erro
- null permanece null
- Para $lookup, os dois lados precisam compartilhar um tipo — converta antes de juntar
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO que acontece com uma string inválida?
AGera erro; onError de $convert retorna um valor de reserva em vez disso.
QPor que meu $lookup não encontra correspondência?
AGeralmente é uma incompatibilidade de tipo — um lado string, o outro ObjectId; unifique com $toObjectId antes.
QE uma string vazia?
AEla gera erro em vez de resultar em null; trate com $ifNull antes.
