$filter (Filtrar Array)
Última atualização: 2026-10-09
$filter (Filtrar Array)
$filter percorre um array, mantém os elementos que satisfazem uma condição e retorna um array novo. É o operador indicado para filtrar arrays dentro de expressões de agregação. Casos de uso típicos: selecionar itens enviados de um pedido, descartar tags inválidas ou selecionar avaliações acima de um limite de pontuação. Sua sintaxe exige um array de entrada (input), um nome de variável (as) e uma expressão condicional (cond) que referencia o elemento atual via $$variável. Ele apenas remove elementos sem transformá-los; combine com $map quando os elementos também precisarem mudar. Uma entrada null resulta em null.
| Categoria | Array |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $filter: { input: <array>, as: <variável>, cond: <condição> } }⚙️ Parâmetros
| input | A expressão de matriz a filtrar. |
|---|---|
| as | O nome da variável do elemento atual, referenciada como $$variable em cond; opcional, o padrão é $$this. |
| cond | Uma expressão de condição que resolva para um booleano; decide quais elementos permanecem. |
Retorno：Uma nova matriz de elementos que satisfazem a condição; null se a entrada for null
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $filter: manter apenas itens com estoque acima de zero
db.orders.aggregate([
{ $project: {
inStock: { $filter: { input: '$items', as: 'it', cond: { $gt: ['$$it.qty', 0] } } }
} }
])Saída：
{ '_id': 1, 'inStock': [ { 'sku': 'A01', 'qty': 2 } ] }
{ '_id': 2, 'inStock': [] }📌 Notas
- Referencie o elemento atual em cond com um prefixo $$, ex.: $$it ou $$this
- $filter apenas remove elementos; aninhe um $map para também transformá-los
- Elementos cuja condição é null ou false são descartados; uma entrada null resulta em null
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
