$filter (agregação)

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplos
Filtrar com base na comparação de números
Use o campo limite
limite maior do que as correspondências possíveis
Filtrar com base na correspondência de igualdade da string
Filtrar com base na correspondência de expressões regulares

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>,
         as: <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` se resolver em um valor não nulo e não array, os erros de pipeline.
`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`.
`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 Operadores de Expressão.

Comportamento

Exemplo

Resultados

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

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

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

[ 1, 2 ]

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

[ 1 ]

Exemplos

Uma coleção sales possui 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

Este exemplo utiliza a coleção sales do exemplo anterior.

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

Este exemplo utiliza a coleção sales do exemplo anterior.

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

Este exemplo utiliza a coleção sales do exemplo anterior.

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

Este exemplo utiliza a coleção sales do exemplo anterior.

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' } ]
   }
]

Voltar

$expMovingAvg

$first