The $filter operator returns a new array with only the elements that pass a condition. It is an aggregation expression operator — like JavaScript’s Array.filter(), but inside MongoDB pipelines.
Keep matching elements only.
input, as, cond.
Reference each item with $$as.
Shape arrays in output.
Tags, line items, scores.
Cap how many matches return.
In MongoDB’s aggregation framework, the $filter operator selects elements from an array based on a boolean condition. You provide the source array (input), a variable name (as), and a condition (cond). MongoDB loops through each element and keeps only those where cond evaluates to true.
Inside cond, reference the current array element with a double dollar sign: if as is "item", use "$$item". A single $ refers to document fields; $$ refers to variables defined in the expression.
The $filter operator takes an object with input, as, and cond:
{
$filter: {
input: <array expression>,
as: <string>,
cond: <boolean expression>,
limit: <number> // optional
}
}// Keep strings that equal "active"
{ $eq: [ "$$tag", "active" ] }
// Keep objects where price > 100
{ $gt: [ "$$item.price", 100 ] }
// Combine conditions with $and
{ $and: [
{ $gte: [ "$$score", 70 ] },
{ $eq: [ "$$score.passed", true ] }
] }input — the array to filter (field path like "$tags" or a literal array).as — variable name for the current element (e.g. "item" or "tag").cond — boolean expression; element is kept when this is true.limit — optional; stops after collecting this many matching elements.$project, $addFields, or $set.$filter works on arrays inside a document and returns a smaller array. $match works on whole documents and removes documents from the pipeline. Use $filter when you need to trim embedded lists without dropping the parent document.
| Question | Answer |
|---|---|
| Operator type | Aggregation array expression operator |
| Syntax | { $filter: { input, as, cond [, limit] } } |
| Input | Array or array expression |
| Output | Filtered array (or null) |
| Common stages | $project, $addFields, $set |
{
$filter: {
input: "$tags",
as: "tag",
cond: {
$eq: ["$$tag", "sale"]
}
}
}Keep matching strings
{
$filter: {
input: "$items",
as: "item",
cond: {
$gt: ["$$item.qty", 0]
}
}
}Filter object arrays
{
$filter: {
input: "$scores",
as: "s",
cond: { $gte: ["$$s", 80] },
limit: 3
}
}Cap result count
{
$filter: {
input: null,
as: "x",
cond: true
}
}Returns null
Walk through sample data, an aggregation pipeline, and the output step by step.
Start with a products collection and filter string tags with $project.
Suppose you have a products collection where each document has a tags array:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"name": "Laptop",
"tags": ["electronics", "sale", "featured"]
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"name": "Mouse",
"tags": ["electronics", "accessory"]
},
{
"_id": ObjectId("609c26812e9274a86871bc6c"),
"name": "Desk",
"tags": ["furniture", "sale"]
}
]Keep only tags that equal "sale" in a new field called saleTags:
db.products.aggregate([
{
$project: {
name: 1,
saleTags: {
$filter: {
input: "$tags",
as: "tag",
cond: { $eq: [ "$$tag", "sale" ] }
}
}
}
}
])tags.$$tag holds the current value.$$tag equals "sale" are kept; others are dropped.[], not null.Filter arrays of objects, combine conditions, and cap results with limit.
When arrays contain objects, use dot notation on the $$ variable:
db.orders.aggregate([
{
$project: {
orderId: 1,
activeItems: {
$filter: {
input: "$items",
as: "item",
cond: { $gt: [ "$$item.qty", 0 ] }
}
}
}
}
])$$item refers to each object in the items array. The condition { $gt: [ "$$item.qty", 0 ] } keeps only items that still have stock.
Filter students who passed and scored at least 70:
db.classes.aggregate([
{
$project: {
className: 1,
topStudents: {
$filter: {
input: "$students",
as: "student",
cond: {
$and: [
{ $gte: [ "$$student.score", 70 ] },
{ $eq: [ "$$student.passed", true ] }
]
}
}
}
}
}
])$and requires both conditions to be true. This pattern is useful when a single comparison is not enough.
Use the optional limit field to return only the first N matching elements:
db.products.aggregate([
{
$project: {
name: 1,
firstTwoSaleTags: {
$filter: {
input: "$tags",
as: "tag",
cond: { $eq: [ "$$tag", "sale" ] },
limit: 2
}
}
}
}
])Even if more than two tags match, MongoDB stops after collecting two results. This is helpful for previews, pagination-style trimming, or performance when you only need a sample.
$project before sending data to clients.$filter WorksThe input expression resolves to an array — usually a field like "$tags" or "$items".
MongoDB assigns the current element to the as variable and evaluates cond using $$as.
When cond is true, the element is added to the result array. Optional limit stops early.
You get a new array with only the elements that passed the condition — the original field stays unchanged unless you overwrite it.
The $filter operator is essential when documents store embedded arrays and you need to return only the relevant items. It keeps parent documents intact while shaping nested data — perfect for tags, line items, scores, and nested user lists.
For beginners, remember three parts: input (the array), as (the loop variable name), and cond (the test using $$variable). Place it inside $project or $addFields and you have MongoDB’s built-in array filtering.
as names like "item" or "tag"$$, not single $$and / $or for multi-condition filterslimit when you only need the first few matches$filter with the $match pipeline stage$$ when referencing the as variable[] — null input returns null$filter as a top-level query operator outside expressions$filterUse these points when filtering arrays in aggregation pipelines.
Keep matching elements.
Purposeinput, as, cond.
SyntaxReference each item.
UsageTags, items, scores.
Use caseFilters arrays, not docs.
Edge caseContinue with $floor, $map, and other aggregation pipeline operators.
5 people found this page helpful