The $switch operator evaluates multiple case branches and returns the result from the first match — like a switch/case statement in programming. Use it instead of deeply nested $cond when you have three or more outcomes.
Many cases at once.
branches + default.
Top-down order.
Label records.
Grades, tiers, status.
Switch vs if/else.
In MongoDB’s aggregation framework, the $switch operator checks an ordered list of case expressions. When a case evaluates to true, MongoDB returns the corresponding then value and stops. If no case matches, it returns the optional default value (or null if omitted).
This is ideal for letter grades, priority tiers, shipping categories, and any scenario where a single field maps to one of several labels based on numeric ranges or equality checks.
Put the most specific or highest-priority cases first. MongoDB only uses the first branch that matches — later branches are skipped.
The $switch operator uses a branches array and an optional default:
{
$switch: {
branches: [
{ case: <expression>, then: <expression> },
{ case: <expression>, then: <expression> },
...
],
default: <expression>
}
}{
$switch: {
branches: [
{
case: { $gte: [ "$score", 90 ] },
then: "A"
},
{
case: { $gte: [ "$score", 80 ] },
then: "B"
}
],
default: "C"
}
}branches — array of objects, each with case (boolean) and then (result).default — optional fallback when no case matches.case must evaluate to a boolean (use $gte, $eq, $and, etc.).then and default can be strings, numbers, or nested expressions.$project, $addFields, $set, or $group.$switch over nested $cond for readability.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (conditional) |
| Syntax | { $switch: { branches: [...], default: ... } } |
| Evaluation order | Top to bottom; first match wins |
| default branch | Optional; null if omitted and no match |
| case type | Must evaluate to boolean |
| Common stages | $project, $addFields, $set, $group |
{
$switch: {
branches: [
{ case: { $gte: ["$s",90] },
then: "A" },
...
],
default: "F"
}
}Score tiers
{
case: { $eq: ["$status","active"] },
then: 1
}Match a value
default: "Unknown"Fallback label
// no default
→ nullOmit default
Assign letter grades, map order priorities, label shipping tiers, and compare with nested $cond.
Map numeric scores to letter grades using ordered case branches.
Suppose you have a students collection with exam scores:
[
{ "_id": 1, "name": "Alice", "score": 95 },
{ "_id": 2, "name": "Bob", "score": 82 },
{ "_id": 3, "name": "Carol", "score": 71 },
{ "_id": 4, "name": "Dave", "score": 58 }
]Assign A through F based on score thresholds (highest tier first):
db.students.aggregate([
{
$project: {
name: 1,
score: 1,
grade: {
$switch: {
branches: [
{
case: { $gte: [ "$score", 90 ] },
then: "A"
},
{
case: { $gte: [ "$score", 80 ] },
then: "B"
},
{
case: { $gte: [ "$score", 70 ] },
then: "C"
},
{
case: { $gte: [ "$score", 60 ] },
then: "D"
}
],
default: "F"
}
}
}
}
])MongoDB checks each branch in order. A score of 95 matches the first branch (>= 90) and returns "A" without checking lower tiers.
Apply $switch to business rules and categorical labels.
Classify orders by total amount:
db.orders.aggregate([
{
$project: {
orderId: 1,
total: 1,
priority: {
$switch: {
branches: [
{
case: { $gte: [ "$total", 1000 ] },
then: "high"
},
{
case: { $gte: [ "$total", 100 ] },
then: "medium"
}
],
default: "low"
}
}
}
}
])
// total: 1500 → priority: "high"
// total: 250 → priority: "medium"
// total: 45 → priority: "low"Each branch defines a threshold. The default catches everything below the lowest tier.
Map numeric status codes to human-readable labels:
db.tasks.aggregate([
{
$addFields: {
statusLabel: {
$switch: {
branches: [
{
case: { $eq: [ "$statusCode", 1 ] },
then: "Open"
},
{
case: { $eq: [ "$statusCode", 2 ] },
then: "In Progress"
},
{
case: { $eq: [ "$statusCode", 3 ] },
then: "Done"
}
],
default: "Unknown"
}
}
}
}
])Use $eq in each case for exact value matching. The default branch handles unexpected codes gracefully.
The same grade logic with nested $cond is harder to read:
// Nested $cond (works, but verbose)
grade: {
$cond: [
{ $gte: [ "$score", 90 ] }, "A",
{ $cond: [
{ $gte: [ "$score", 80 ] }, "B",
{ $cond: [
{ $gte: [ "$score", 70 ] }, "C", "F"
]}
]}
]
}
// $switch — same logic, flat and clear
grade: {
$switch: {
branches: [
{ case: { $gte: [ "$score", 90 ] }, then: "A" },
{ case: { $gte: [ "$score", 80 ] }, then: "B" },
{ case: { $gte: [ "$score", 70 ] }, then: "C" }
],
default: "F"
}
}Both approaches produce the same result. Prefer $switch when you have three or more outcomes.
When no branch matches and default is omitted, the result is null:
{
$switch: {
branches: [
{
case: { $eq: [ "$type", "premium" ] },
then: "VIP"
}
]
}
}
// type: "premium" → "VIP"
// type: "standard" → nullInclude a default branch when you always need a fallback value.
$switch WorksEach branch has a case (condition) and a then (result).
The first branch whose case evaluates to true wins. Remaining branches are skipped.
If no case matches, MongoDB returns default (or null).
Use in $project or $addFields to enrich documents.
The $switch operator simplifies multi-branch conditional logic in MongoDB aggregation pipelines. It replaces hard-to-read nested $cond chains with a flat list of cases and an optional default.
Order branches from most specific to least specific, and always include a default when you need a guaranteed fallback. Next in the series: $tan.
$switch when you have three or more possible outcomesdefault branch for unexpected valuescase expressions with $gte, $eq, or $andcase fields$cond deeply when $switch would be clearerdefault is required — omitting it returns null$switchUse these points when building multi-way conditionals.
Case list.
Purposecase + then.
SyntaxTop-down.
RuleFallback value.
OptionalFlat vs nested.
CompareMove on to $tan for tangent calculations, or review $cond for simple if-then-else logic.
5 people found this page helpful