The $subtract operator subtracts one value from another in MongoDB aggregation pipelines. Use it for budget balances, inventory variance, date durations, and any calculation where you need a minus b.
First minus second.
[ a, b ] array.
Fields & literals.
Millis difference.
Balance, variance.
Minus vs sum.
In MongoDB’s aggregation framework, the $subtract operator computes expression1 − expression2. For example, { $subtract: [ 10, 3 ] } returns 7, and { $subtract: [ "$budget", "$spent" ] } returns how much budget remains.
When both operands are dates, the result is the difference in milliseconds. Combine with $divide to express duration in days or hours. Pair with $abs when you need the magnitude of a difference regardless of sign.
Order matters: { $subtract: [ "$actual", "$expected" ] } gives a positive value when actual exceeds expected. Swap the operands if you need the opposite sign.
The $subtract operator takes an array of two expressions:
{ $subtract: [ <expression1>, <expression2> ] }{ $subtract: [ 10, 3 ] }
// Result: 7
{ $subtract: [ "$total", "$discount" ] }
// total minus discount
{ $subtract: [ "$endDate", "$startDate" ] }
// Date difference in milliseconds$project, $addFields, $set, or nested expressions.null in either operand — returns null.a - ba + b + c{ $subtract: [ a, { $add: [ b, c ] } ] }| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (arithmetic) |
| Syntax | { $subtract: [ a, b ] } |
| Operands | Exactly two expressions |
| Date result | Milliseconds (number) |
| Days from dates | $divide: [ { $subtract: [...] }, 86400000 ] |
| Common stages | $project, $addFields, $set |
{
$subtract: [ 100, 25 ]
}Returns 75
{
$subtract: ["$a", "$b"]
}Field difference
$abs: {
$subtract: [...]
}Absolute diff
$subtract: [
"$end", "$start"
]Millis apart
Compute budget remainders, inventory variance, date durations, and absolute differences with $subtract.
Start with a budgets collection and compute remaining amounts.
Suppose you have a budgets collection tracking planned vs actual spending:
[
{ "_id": 1, "department": "Marketing", "budget": 5000, "spent": 3200 },
{ "_id": 2, "department": "Engineering", "budget": 12000, "spent": 11500 },
{ "_id": 3, "department": "HR", "budget": 3000, "spent": 3500 }
]Calculate how much budget remains:
db.budgets.aggregate([
{
$project: {
department: 1,
budget: 1,
spent: 1,
remaining: {
$subtract: [ "$budget", "$spent" ]
}
}
}
])Each document gets a computed remaining field. Negative values mean spending exceeded the budget.
Measure differences between expected and actual values, and compute time spans.
Find how far actual stock differs from expected, regardless of direction:
db.inventory.aggregate([
{
$project: {
item: 1,
expected: 1,
actual: 1,
variance: {
$abs: {
$subtract: [ "$actual", "$expected" ]
}
}
}
}
])
// expected: 100, actual: 92 → variance: 8
// expected: 50, actual: 58 → variance: 8$subtract gives a signed difference. Wrapping it in $abs returns the magnitude only — useful for QA and reporting.
Subtract two date fields and convert milliseconds to days:
db.projects.aggregate([
{
$project: {
name: 1,
startDate: 1,
endDate: 1,
durationDays: {
$divide: [
{ $subtract: [ "$endDate", "$startDate" ] },
86400000
]
}
}
}
])
// 86400000 = milliseconds in one day (24 × 60 × 60 × 1000)Date subtraction returns milliseconds. Divide by 86,400,000 to get whole days, or use other divisors for hours or minutes.
Subtract a discount and tax from a total using nested expressions:
db.orders.aggregate([
{
$project: {
orderId: 1,
subtotal: 1,
discount: 1,
tax: 1,
netAmount: {
$subtract: [
{ $subtract: [ "$subtotal", "$discount" ] },
"$tax"
]
}
}
}
])
// subtotal: 100, discount: 10, tax: 5
// netAmount: 100 - 10 - 5 = 85$subtract accepts only two operands. Nest calls or use $add with negative values for longer expressions.
Subtract fixed amounts or compute characters remaining:
db.posts.aggregate([
{
$project: {
title: 1,
charsRemaining: {
$subtract: [
280,
{ $strLenCP: "$body" }
]
}
}
}
])
// 280 - body length = characters left before limitMix literals with field expressions. Negative results mean the text exceeds the limit.
$subtract WorksEach expression resolves to a number, date, or nested result from field paths or literals.
For numbers: standard arithmetic. For dates: millisecond difference.
The difference is written to the field you define in $project or $addFields.
Chain with $abs, $divide, or $cond as needed.
The $subtract operator is a fundamental arithmetic tool in MongoDB aggregation pipelines. It computes the difference between two numbers or the millisecond span between two dates, enabling budget tracking, variance analysis, and duration calculations.
Remember operand order: first minus second. Next in the series: $switch.
[ a, b ] means a - b$abs when only the magnitude of a difference matters$ifNull when missing fields should count as zero$subtract or use $add for multi-value expressions$subtract takes exactly twonull$subtract with the query $inc update operator$subtractUse these points when writing arithmetic in MongoDB pipelines.
Two operands.
PurposeArray syntax.
SyntaxMillis diff.
DatesVariance.
PatternFirst minus second.
RuleMove on to $switch for multi-branch conditional logic, or review $abs for absolute differences.
5 people found this page helpful