Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

$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 MongoDB na nuvem

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.
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 matriz correspondentes que $filter retorna. Não é possível especificar um limite inferior a 1. Os elementos da array correspondentes são retornados na ordem em que aparecem na 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 de array correspondentes.

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' } ]
   }
]
← $expMovingAvg (agregação)
$first (agregação) →

Nesta página