The $cmp operator compares two values and returns -1, 0, or 1 in MongoDB aggregation pipelines. It is the building block for multi-branch logic with $switch and custom ranking.
Returns -1, 0, or 1.
Two values in an array.
Numbers, strings, dates.
Power categorization logic.
Sort, rank, categorize.
When to use each.
In MongoDB’s aggregation framework, the $cmp operator compares two expressions and returns a numeric result: -1 if the first is less, 0 if equal, and 1 if the first is greater. For example, $cmp(85, 80) returns 1 because 85 is greater than 80.
Think of $cmp like a three-way sign: less than, equal, or greater than. Pair it with $switch or $eq to turn comparison results into labels, tiers, or custom sort keys.
The $cmp operator takes two expressions in an array:
{ $cmp: [ <expression1>, <expression2> ] }$cmp — compares the first expression to the second.-1 (less), 0 (equal), 1 (greater).$project, $addFields, or $set.$cmp: [ 75, 80 ] → -1 (75 < 80)$cmp: [ 80, 80 ] → 0 (equal)$cmp: [ 90, 80 ] → 1 (90 > 80)1 for “greater than”, -1 for “less than”| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (comparison) |
| Syntax | { $cmp: [ expr1, expr2 ] } |
| Returns | -1, 0, or 1 |
| Greater than check | { $eq: [ { $cmp: [ a, b ] }, 1 ] } |
| Common stages | $project, $addFields, $set |
{
$cmp: [ 90, 80 ]
}Returns 1
{
$cmp: [ 80, 80 ]
}Returns 0
{
$cmp: [ 75, 80 ]
}Returns -1
{
$cmp: ["$a", "$b"]
}Compare two fields
Compare student scores, assign performance labels with $switch, and compare two document fields.
Use a students collection and see raw $cmp results with $project.
Suppose you have a students collection with name and score fields:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "name": "Alice", "score": 85 },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "name": "Bob", "score": 75 },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "name": "Charlie", "score": 90 }
]Compare each student’s score to the passing threshold of 80:
db.students.aggregate([
{
$project: {
name: 1,
score: 1,
vs80: { $cmp: [ "$score", 80 ] }
}
}
])cmp(85, 80) → 1 (above threshold).cmp(75, 80) → -1 (below threshold).cmp(90, 80) → 1 (above threshold).Turn comparison results into labels, tiers, and field-to-field checks.
Assign performance labels based on score thresholds (High ≥ 80, Medium ≥ 60, else Low):
db.students.aggregate([
{
$project: {
name: 1,
score: 1,
performance: {
$switch: {
branches: [
{
case: { $eq: [ { $cmp: [ "$score", 80 ] }, 1 ] },
then: "High"
},
{
case: { $eq: [ { $cmp: [ "$score", 60 ] }, 1 ] },
then: "Medium"
}
],
default: "Low"
}
}
}
}
])$eq: [ { $cmp: [ "$score", 80 ] }, 1 ] is true when score strictly greater than 80. For scores exactly 80, use $gte instead, or add a branch for cmp === 0.
Check whether actual inventory meets the expected level:
db.inventory.aggregate([
{
$project: {
item: 1,
expected: 1,
actual: 1,
stockStatus: {
$switch: {
branches: [
{
case: { $eq: [ { $cmp: [ "$actual", "$expected" ] }, 1 ] },
then: "Overstocked"
},
{
case: { $eq: [ { $cmp: [ "$actual", "$expected" ] }, 0 ] },
then: "Exact"
}
],
default: "Understocked"
}
}
}
}
])Comparing two fields with $cmp returns 1 when actual exceeds expected, 0 when they match, and -1 when actual is lower.
For a simple “passed or failed” check, $gte is often clearer than $cmp:
db.students.aggregate([
{
$project: {
name: 1,
score: 1,
// Using $cmp (returns -1, 0, or 1)
cmpResult: { $cmp: [ "$score", 60 ] },
// Using $gte (returns true or false) — simpler for pass/fail
passed: { $gte: [ "$score", 60 ] }
}
}
])
// score: 75 → cmpResult: 1, passed: true
// score: 60 → cmpResult: 0, passed: true
// score: 45 → cmpResult: -1, passed: falseUse $cmp when you need three outcomes. Use $gte, $gt, $lte, or $lt when you only need true/false.
$switch.$cmp WorksThe pipeline resolves both expressions — fields like "$score" or literal thresholds.
MongoDB applies BSON comparison rules and returns -1, 0, or 1.
Use the integer in $switch, $cond, or $eq to branch your pipeline.
Labels, ranks, and filters based on relative value order.
The $cmp operator is a flexible comparison tool in MongoDB aggregation pipelines. Its three-way return value (-1, 0, 1) makes it especially powerful inside $switch for categorization and ranking logic.
For beginners, remember: 1 means greater, -1 means less, 0 means equal. For simple pass/fail checks, $gte is often easier to read than $cmp.
$cmp with $switch for multi-tier categorization1 = greater, 0 = equal, -1 = less$gte when you only need a true/false result$cmp returns a boolean (it returns -1, 0, or 1)cmp === 1 when you need “greater than or equal”$cmp with $eq (equality only)$cmp as a query filter outside expressions$cmpUse these points when comparing values in MongoDB.
-1, 0, or 1.
Purpose{ $cmp: [a, b] }
First > second.
RuleGreat for tiers.
PatternUse $gte for true/false.
ImportantMove on to $comment for pipeline annotations, or review $and for logical expressions.
5 people found this page helpful