$lookup (Junção de Coleções)
Última atualização: 2026-10-09
$lookup (Junção de Coleções)
$lookup realiza uma junção externa à esquerda entre a coleção atual e outra coleção, anexando documentos correspondentes como um array a cada resultado. Equivalente ao LEFT JOIN do SQL, ele permite que pipelines combinem dados entre coleções sem várias consultas. Note que ele suporta apenas correspondências por igualdade — sem junções por intervalo ou condicionais.
| Categoria | Estágios Principais |
|---|---|
| Versão do MongoDB | 3.2+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $lookup: { from: <coleção>, localField: <campo-local>, foreignField: <campo-estrangeiro>, as: <array-de-saída> } }▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $lookup: junta pedidos com clientes
db.orders.aggregate([
{ $lookup: {
from: "customers",
localField: "cust_id",
foreignField: "_id",
as: "customer"
} }
])Saída：
{ "_id": 1, "cust_id": "A123", "customer": [{ "_id": "A123", "name": "Alice" }] }📌 Notas
- from deve referenciar uma coleção no mesmo banco de dados
- Os nomes dos campos devem corresponder exatamente e os tipos devem estar alinhados entre localField e foreignField
- Sem correspondência resulta em um array vazio [], não null
- Desde o 3.6, $lookup suporta um pipeline interno (campo pipeline) para junções mais ricas; a partir do 5.0, a sintaxe concisa de subconsulta correlacionada elimina a necessidade de $expr
🏷️ Tags Relacionados
💡 Casos Relacionados
Pipelines de agregação avançados: expressões e transformações complexas
Introdução aos pipelines de agregação: o método `aggregate` e o estágio básico
Prática: CRUD para um sistema de comentários de blog
Bancos de dados e coleções: gerenciamento de namespaces no MongoDB
Documentos e BSON: a base dos dados do MongoDB
$facet + $bucket + Pesquisa de texto/geoespacial
$lookup e associações com múltiplos conjuntos
Padrões avançados do Mongoose: desempenho e flexibilidade
Modelos do Mongoose e projeto de esquemas
Validação de dados e middleware do Mongoose
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
Q$lookup pode substituir JOINs no nível do banco de dados?
AEle alcança resultados semelhantes, mas $lookup mescla dados em tempo de consulta: correspondências por igualdade e comparações simples dentro do pipeline podem usar índices, porém sua otimização de junção é menos abrangente que a de bancos SQL, então avalie o desempenho em conjuntos de dados muito grandes.
QComo posso otimizar o desempenho de $lookup?
ACrie um índice no campo de chave estrangeira da coleção unida. Também prefira $match cedo no pipeline para reduzir a coleção principal antes da junção.
Q$lookup suporta junções por várias chaves?
ASim. Desde o 3.6, a forma de pipeline de $lookup com $expr permite junções por vários campos e subconsultas além da igualdade simples em uma chave.
