Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Menu Docs
Página inicial do Docs
/ /
Expressões
Página inicial do Docs
/
Desenvolvimento
/
Linguagem de query
/
Expressões
Página inicial do Docs
/
Desenvolvimento
/
Linguagem de query
/
Expressões

$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>,
         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 input array. 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ê arrayIndexAs omitir, você poderá utilizar a variável de sistema na expressão para retornar o índice do elemento $$IDX atual.

Para obter exemplos, consulte Acessar o índice de cada item em uma 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 da array correspondentes são retornados na ordem em que aparecem na array de entrada.

Se o especificado limit for maior que o número de elementos correspondentes da array, retornará todos os elementos correspondentes da$filter array. Se o limite null for, retornará todos os elementos da array$filter correspondentes.

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 ]

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

Acesse o índice de cada item em uma array

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

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 da matriz é 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 documentos com estes campos:

  • Nome da pessoa.

  • secondaryHobbies matriz 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 retorna o índice do elemento atual $$IDX na input array. Você pode usar $$IDX se omitir o arrayIndexAs campo 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 arrayIndexAs de:

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

Voltar

$expMovingAvg

Próximo

$floor

Nesta página