The $setDifference operator returns elements that are in the first array but not in any of the others. Think of it as set subtraction: A − B gives you what is in A alone.
Set subtraction.
Two+ arrays.
Unique values.
$project / $addFields.
Tags, permissions.
Union, intersection.
In MongoDB’s aggregation framework, the $setDifference operator compares two or more arrays as sets and returns elements present in the first array but absent from all subsequent arrays. For example, { $setDifference: [ [1, 2, 3], [3, 4] ] } returns [1, 2].
Set operators ignore duplicate values and compare elements for equality. Use $setDifference when you need “what does this list have that the other list does not?” — such as tags a user follows minus blocked tags, or wishlist items not yet in the cart.
Order matters: the first array is the minuend (what you start with). The second and later arrays are subtracted from it. Swap the arrays and you get a different result.
The $setDifference operator takes an array of two or more array expressions:
{ $setDifference: [ <array1>, <array2>, ... ] }{ $setDifference: [ [1, 2, 3], [3, 4] ] }
// Result: [1, 2]
{ $setDifference: [ ["a", "b", "c"], ["b"], ["c", "d"] ] }
// Result: ["a"]$setIntersection).null if any input array is null.$project, $addFields, or $set.[1] (in A only)[2, 3] (in both)[1, 2, 3, 4] (all unique)false (same set?)| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (set / array) |
| Syntax | { $setDifference: [ arr1, arr2, ... ] } |
| Minimum arrays | Two |
| Output | Array of elements in first set minus others |
| Common stages | $project, $addFields, $set |
{
$setDifference: [
[1, 2, 3],
[3, 4]
]
}→ [1, 2]
{
$setDifference: [
"$tags",
"$blocked"
]
}Tag diff
[
"$all",
"$a",
"$b"
]Minus A and B
[ ]All excluded
Find tags a user keeps but has blocked, wishlist items not in the cart, skills gaps, and subtract multiple exclusion lists with $setDifference.
Find tags a user follows that are not in their blocked list.
Suppose you have a users collection:
[
{
"_id": 1,
"name": "Alice",
"tags": ["mongodb", "nodejs", "database"],
"blockedTags": ["spam", "database"]
},
{
"_id": 2,
"name": "Bob",
"tags": ["python", "ml"],
"blockedTags": ["python"]
},
{
"_id": 3,
"name": "Carol",
"tags": ["mongodb", "mongodb", "tutorial"],
"blockedTags": []
}
]Compute allowed tags as tags minus blockedTags:
db.users.aggregate([
{
$project: {
name: 1,
tags: 1,
blockedTags: 1,
allowedTags: {
$setDifference: [
"$tags",
"$blockedTags"
]
}
}
}
])Elements in tags that also appear in blockedTags are excluded. Set semantics deduplicate mongodb for Carol.
Wishlist gaps, skill comparisons, and counting remaining items.
Find product IDs still on the wishlist but not yet purchased:
db.customers.aggregate([
{
$project: {
name: 1,
stillWanted: {
$setDifference: [
"$wishlist",
"$cart"
]
}
}
}
])
// wishlist: ["P100", "P200", "P300"]
// cart: ["P200"]
// stillWanted: ["P100", "P300"]The first array is the wishlist; the second is subtracted. Items in both lists disappear from the result.
Compare a job’s required skills against a candidate’s skills:
db.jobs.aggregate([
{
$lookup: {
from: "candidates",
localField: "candidateId",
foreignField: "_id",
as: "candidate"
}
},
{ $unwind: "$candidate" },
{
$project: {
title: 1,
missingSkills: {
$setDifference: [
"$requiredSkills",
"$candidate.skills"
]
}
}
}
])
// required: ["mongo", "node", "react"]
// candidate skills: ["mongo", "node"]
// missingSkills: ["react"]Put the “required” list first and subtract what the candidate already has. The result is the skill gap.
Use $size on the difference result:
db.users.aggregate([
{
$project: {
name: 1,
allowedCount: {
$size: {
$setDifference: [
"$tags",
"$blockedTags"
]
}
}
}
}
])$size counts how many unique allowed tags remain after subtraction. Handy for dashboards and validation rules.
Remove elements found in either of two block lists:
db.users.aggregate([
{
$project: {
name: 1,
visibleTags: {
$setDifference: [
"$tags",
"$blockedTags",
"$systemHiddenTags"
]
}
}
}
])
// tags minus (blockedTags ∪ systemHiddenTags)Pass more than two arrays. The first array minus the union of all others — one operator instead of chaining multiple steps.
$setDifference WorksAll arguments resolve to arrays (field paths, literals, or nested expressions).
The second and subsequent arrays are combined; any matching value is excluded.
Each unique element from the first array not in the exclusion set is added to the result.
Elements in set A but not in B (or B ∪ C ∪ …).
The $setDifference operator subtracts one or more arrays from the first array using set semantics. It answers “what is in A but not in B?” inside aggregation pipelines without application-side set logic.
Remember: first array is the source, duplicates are deduplicated, and order follows the first array’s survivors. Next in the series: $setEquals.
$ifNull for missing arrays (e.g. treat null as [])$size to count remaining elements$setIntersection when you need shared elements instead[B, A] ≠ [A, B]$setDifference when you need ordered list diff (use $filter)$setDifferenceUse these points when comparing arrays as sets in pipelines.
Set subtraction.
PurposeTwo or more arrays.
SyntaxSet semantics.
OutputFirst = source.
Rulenull out.
Edge caseMove on to $setEquals to test whether two arrays represent the same set, or review $filter for single-array conditions.
5 people found this page helpful