$match (Filtrar Documentos)
Última atualização: 2026-10-09
$match (Filtrar Documentos)
$match filtra documentos com uma condição de consulta, passando apenas os documentos correspondentes para os estágios seguintes. É o equivalente de agregação do predicado de consulta de find(). Coloque $match o mais cedo possível — ele pode usar índices e reduz o número de documentos que entram nos estágios posteriores, tornando-o a regra número 1 de desempenho em agregação.
| Categoria | Estágios Principais |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $match: { <consulta> } }⚙️ Parâmetros
| consulta | A mesma expressão de consulta que find(), com suporte a operadores de comparação/lógicos/de elemento. |
|---|
Retorno：Fluxo de documentos filtrado (para o próximo estágio)
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $match: apenas pedidos com status A
db.orders.aggregate([
{ $match: { status: "A" } },
{ $group: { _id: "$cust_id", total: { $sum: "$amount" } } }
])Saída：
// Retorna total por cliente
{ "_id": "A123", "total": 250 }
{ "_id": "B456", "total": 130 }📌 Notas
- Coloque $match primeiro para aproveitar índices
- Não pode usar $where ou $text dentro de $match ($text deve ser o primeiro estágio)
- As otimizações de índice param após o estágio $match
🏷️ 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
Fluxos de alterações: monitoramento de alterações em tempo real
$facet + $bucket + Pesquisa de texto/geoespacial
$lookup e associações com múltiplos conjuntos
Modelos do Mongoose e projeto de esquemas
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $match e find()?
AAs condições de consulta são idênticas, mas $match é usado dentro de um pipeline de agregação e passa os resultados para o próximo estágio.
Q$match pode ser colocado no meio de um pipeline?
ASim, mas você perde a otimização de índice. Regra prática: coloque-o primeiro sempre que possível.
QPor que colocar $match no início do pipeline?
AFiltrar cedo reduz o volume de dados passado aos estágios posteriores e permite que $match use um índice, o que aumenta significativamente o desempenho. Colocado depois, ele ainda funciona, mas não pode usar índices.
