$filter (aggregation)
On this page
Definition
Compatibility
You can use $filter
for deployments hosted in the following
environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
$filter
has the following syntax:
{ $filter: { input: <array>, as: <string>, cond: <expression>, limit: <number expression> } }
Field | Specification |
---|---|
input | An expression that resolves to an array. If If |
as | Optional. A name for the variable that represents each
individual element of the input array. If no name is
specified, the variable name defaults to this . |
cond | An expression that resolves
to a boolean value used to determine if an element should be
included in the output array. The expression references each
element of the input array individually with the variable
name specified in as . |
limit | Optional. A number expression that restricts the number of matching
array elements that If the specified |
For more information on expressions, see Expressions.
Behavior
Example | Results | ||||||||
---|---|---|---|---|---|---|---|---|---|
| [ 1, 2, 3.1, NumberLong(4) ] | ||||||||
| [ 1, 2 ] | ||||||||
| [ 1 ] |
Examples
A collection sales
has the following documents:
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" } ] } ] )
Filter Based on Number Comparison
The following example filters the items
array to only include
documents that have a price
greater than or equal to 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 the limit Field
This example uses the sales
collection from the previous example.
The example uses the limit
field to specify the number of matching
elements returned in each items
array.
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: [] } ]
limit Greater than Possible Matches
This example uses the sales
collection from the previous example.
The example uses a limit
field value that is larger than the
possible number of matching elements that can be returned. In this case,
limit
does not affect the query results and returns all documents
matching the $gte
filter criteria.
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: [] } ]
Filter Based on String Equality Match
This example uses the sales
collection from the previous example.
The following aggregation filters for items
that have a name
value of 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: [] } ]
Filter Based on Regular Expression Match
This example uses the sales
collection from the previous example.
The following aggregation uses $regexMatch
to filter for
items
that have a name
value that starts with 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' } ] } ]