$filter ( operador de expressão )

Definição

$filter: Seleciona um subconjunto de uma matriz para retornar com base na condição especificada. Retorna uma matriz com somente os elementos que correspondem à condição. Os elementos devolvidos estão na ordem original.

Compatibilidade

Você pode utilizar o $filter para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

$filter tem a seguinte sintaxe:

{    $filter:      {         input: <array expression>,         as: <string>,         arrayIndexAs: <string>,         cond: <expression>,         limit: <number expression>      }}

Campo	Especificação
`input`	Uma expressão que se torna uma array. Se `input` resolver para `null` ou se referir a um campo ausente, `$filter` retornará `null`. Se `input` resolver para um valor que não seja da array e não seja nulo, o pipeline será executado.
`as`	Opcional. Um nome para a variável que representa cada elemento individual da array `input`. Se nenhum nome for especificado, o nome da variável padrão será `this`.
`arrayIndexAs`	opcional. Um nome para a variável de agregação que representa o índice do elemento atual na array `input`. O primeiro índice do elemento da array é `0`. Você pode utilizar o nome da variável em uma expressão. Por exemplo, se você especificar `arrayIndexAs: "myIndex"`, usará `$$myIndex` na expressão. `$$myIndex` retorna o índice do elemento atual na array `input`. Se você omitir `arrayIndexAs`, você poderá utilizar a variável de sistema `$$IDX` na expressão para retornar o índice do elemento atual. Para exemplos, consulte Acessar o índice de cada item em um array e Usar `$$IDX` para acessar o índice. Novidades na versão 8.3.
`cond`	Uma expressão que se torna um valor booleano utilizado para determinar se um elemento deve ser incluído na array de saída. A expressão referencia cada elemento da array `input` individualmente com o nome da variável especificado em `as`.
`limit`	Opcional. Uma expressão numérica que restringe o número de elementos de array correspondentes que `$filter` retorna. Não é possível especificar um limite inferior a `1`. Os elementos de array correspondentes são retornados na ordem em que aparecem no array de entrada. Se o `limit` especificado for maior que o número de elementos correspondentes da array, `$filter` retornará todos os elementos correspondentes da array. Se o limite for `null`, `$filter` retornará todos os elementos correspondentes da array.

Para mais informações sobre expressões, consulte Expressões.

Comportamento

Exemplo	Resultados
`{ $filter: { input: [ 1, "a", 2, null, 3.1, Long(4), "5" ], as: "num", cond: { $isNumber: "$$num" } }}`	`[ 1, 2, 3.1, Long(4) ]`
`{ $filter: { input: [ 1, "a", 2, null, 3.1, Long(4), "5" ], as: "num", cond: { $isNumber: "$$num" }, limit: 2 }}`	`[ 1, 2 ]`
`{ $filter: { input: [ 1, "a", 2, null, 3.1, Long(4), "5" ], as: "num", cond: { $isNumber: "$$num" }, limit: { $add: [ 0, 1 ] } }}`	`[ 1 ]`

Exemplo

Resultados

{  $filter: {     input: [ 1, "a", 2, null, 3.1, Long(4), "5" ],     as: "num",     cond: { $isNumber: "$$num" }  }}

[ 1, 2, 3.1, Long(4) ]

{  $filter: {     input: [ 1, "a", 2, null, 3.1, Long(4), "5" ],     as: "num",     cond: { $isNumber: "$$num" },     limit: 2  }}

[ 1, 2 ]

{  $filter: {     input: [ 1, "a", 2, null, 3.1, Long(4), "5" ],     as: "num",     cond: { $isNumber: "$$num" },     limit: { $add: [ 0, 1 ] }  }}

[ 1 ]

Exemplos

Os exemplos a seguir utilizam uma coleção sales com os seguintes documentos:

db.sales.insertMany( [   {      _id: 0,      items: [         { item_id: 43, quantity: 2, price: 10, name: "pen" },         { item_id: 2, quantity: 1, price: 240, name: "briefcase" }      ]   },   {      _id: 1,      items: [         { item_id: 23, quantity: 3, price: 110, name: "notebook" },         { item_id: 103, quantity: 4, price: 5, name: "pen" },         { item_id: 38, quantity: 1, price: 300, name: "printer" }      ]   },   {      _id: 2,      items: [         { item_id: 4, quantity: 1, price: 23, name: "paper" }      ]   }] )

Filtrar com base na comparação de números

O exemplo a seguir filtra a array items para incluir somente documentos que tenham um price maior ou igual a 100:

db.sales.aggregate( [   {      $project: {         items: {            $filter: {               input: "$items",               as: "item",               cond: { $gte: [ "$$item.price", 100 ] }            }         }      }   }] )

[   {      _id: 0,      items: [ { item_id: 2, quantity: 1, price: 240, name: 'briefcase' } ]   },   {      _id: 1,      items: [         { item_id: 23, quantity: 3, price: 110, name: 'notebook' },         { item_id: 38, quantity: 1, price: 300, name: 'printer' }      ]   },   { _id: 2, items: [] }]

Use o campo limite

O exemplo utiliza o campo limit para especificar o número de elementos correspondentes retornados em cada array items.

db.sales.aggregate( [   {      $project: {         items: {            $filter: {               input: "$items",               as: "item",               cond: { $gte: [ "$$item.price", 100 ] },               limit: 1            }         }      }   }] )

[   {      _id: 0,      items: [ { item_id: 2, quantity: 1, price: 240, name: 'briefcase' } ]   },   {      _id: 1,      items: [ { item_id: 23, quantity: 3, price: 110, name: 'notebook' } ]   },   { _id: 2, items: [] }]

limite maior do que as correspondências possíveis

O exemplo usa um valor de campo limit maior que o número possível de elementos correspondentes que podem ser retornados. Neste caso, limit não afeta os resultados da query e retorna todos os documentos correspondentes aos critérios de filtro $gte.

db.sales.aggregate( [   {      $project: {         items: {            $filter: {               input: "$items",               as: "item",               cond: { $gte: [ "$$item.price", 100] },               limit: 5            }         }      }   }] )

[   {      _id: 0,      items: [ { item_id: 2, quantity: 1, price: 240, name: 'briefcase' } ]   },   {      _id: 1,      items: [         { item_id: 23, quantity: 3, price: 110, name: 'notebook' },         { item_id: 38, quantity: 1, price: 300, name: 'printer' }      ]   },   { _id: 2, items: [] }]

Filtrar com base na correspondência de igualdade da string

Os seguintes filtros de aggregation para items que têm um valor de name de pen.

db.sales.aggregate( [   {      $project: {         items: {            $filter: {               input: "$items",               as: "item",               cond: { $eq: [ "$$item.name", "pen"] }            }         }      }   }] )

[   {      _id: 0,      items: [ { item_id: 43, quantity: 2, price: 10, name: 'pen' } ]   },   {      _id: 1,      items: [ { item_id: 103, quantity: 4, price: 5, name: 'pen' } ]   },   { _id: 2, items: [] }]

Filtrar com base na correspondência de expressões regulares

A seguinte aggregation usa $regexMatch para filtrar para items que têm um valor de name que começa com p:

db.sales.aggregate( [   {      $project: {         items: {            $filter: {               input: "$items",               as: "item",               cond: {                  $regexMatch: { input: "$$item.name", regex: /^p/ }               }            }         }      }   }] )

[   {      _id: 0,      items: [ { item_id: 43, quantity: 2, price: 10, name: 'pen' } ]   },   {      _id: 1,      items: [         { item_id: 103, quantity: 4, price: 5, name: 'pen' },         { item_id: 38, quantity: 1, price: 300, name: 'printer' }      ]   },   {      _id: 2,      items: [ { item_id: 4, quantity: 1, price: 23, name: 'paper' } ]   }]

Acesse o índice de cada item em uma array

Crie uma coleção de amostra denominada people com estes document:

db.people.insertMany( [   { _id: 1, name: "Melissa", hobbies: [ "softball", "drawing", "reading" ] },   { _id: 2, name: "Brad", hobbies: [ "gaming", "skateboarding" ] },   { _id: 3, name: "Scott", hobbies: [ "basketball", "music", "fishing" ] },   { _id: 4, name: "Tracey", hobbies: [ "acting", "yoga" ] },   { _id: 5, name: "Josh", hobbies: [ "programming" ] },   { _id: 6, name: "Claire" }] )

O campo hobbies contém uma array dos hobbies de cada pessoa em ordem de classificação. O primeiro passatempo no array é o principal passatempo da pessoa em que a pessoa passa a maior parte do tempo. O primeiro passatempo tem um índice de array de 0.

O exemplo a seguir usa arrayIndexAs. A variável myIndex tem o índice de cada passatempo na array hobbies. O exemplo retorna document com estes campos:

Nome da pessoa.
secondaryHobbies array que inclui todos os outros passatempos.

db.people.aggregate( [   {      $project: {         _id: 0,         name: 1,         secondaryHobbies: {            $filter: {               input: "$hobbies",               arrayIndexAs: "myIndex",               cond: { $eq: [ { $mod: [ "$$myIndex", 2 ] }, 0 ] }            }         }      }   }] )

Saída:

[   { "name" : "Melissa", "secondaryHobbies" : [ "softball", "reading" ] }   { "name" : "Brad", "secondaryHobbies" : [ "gaming" ] }   { "name" : "Scott", "secondaryHobbies" : [ "basketball", "fishing" ] }   { "name" : "Tracey", "secondaryHobbies" : [ "acting" ] }   { "name" : "Josh", "secondaryHobbies" : [ "programming" ] }   { "name" : "Claire", "secondaryHobbies" : null }]

Use `$$IDX` para acessar o índice

A variável $$IDX retorna o índice do elemento atual na array input. Você pode usar $$IDX se omitir o campo arrayIndexAs da expressão.

O exemplo a seguir retorna os mesmos documentos que o exemplo na seção anterior Acesse o índice de cada item em uma array, mas usa $$IDX em vez de arrayIndexAs:

db.people.aggregate( [   {      $project: {         _id: 0,         name: 1,         secondaryHobbies: {            $filter: {               input: "$hobbies",               cond: { $eq: [ { $mod: [ "$$IDX", 2 ] }, 0 ] }            }         }      }   }] )