MongoDB $subtract Operator

What Is $subtract?

$subtract is a MongoDB aggregation expression that returns expression1 minus expression2. Use it for numbers, for the millisecond difference between two dates, or to subtract milliseconds from a date.

$subtract = a − b for aggregation

{ $subtract: [ <expression1>, <expression2> ] }

10 − 3 → 7
date − date → milliseconds
date − number → earlier date (number = ms)

null / missing operand → null
exactly two arguments (not a list of many)

How to Use $subtract in MongoDB

Put the value you keep first, then the value you remove.

1. Choose an expression stage ($addFields or $project).
2. Pass two expressions: result = first − second.
3. For a total like price + fee − discount, nest $add inside $subtract.
4. For dates: date − date → ms; date − ms → date (date must be first).

Pseudocode

for each document:
    a = evaluate(expression1)
    b = evaluate(expression2)
    if a is null or b is null:
        result = null
    else:
        result = a − b   // numbers, dates, or date − ms
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while writing subtraction expressions.

Live Preview

Watch $subtract compute a − b for simple sale totals. Try price only, or price + fee minus discount.

a = 10
b = 5

$subtract → 5

{ total: 5 }

Worked Walkthrough — Sale Total

One sale has price 10, fee 2, and discount 5. Total is (price + fee) − discount.

Document:
  { item: "abc", price: 10, fee: 2, discount: 5 }

subtotal = price + fee
         = 10 + 2
         = 12

total = subtotal − discount
      = 12 − 5
      = 7

$subtract([
  { $add: ["$price", "$fee"] },
  "$discount"
]) → 7

Check: 10 + 2 − 5 = 7 ✓

MongoDB Examples

We store one sale with price, fee, and discount. First we subtract the discount from price, then we nest $add for a full total. Run these in mongosh after inserting the sample data once.

db.sales.insertOne({
  _id: 1,
  item: "abc",
  price: 10,
  fee: 2,
  discount: 5
});

db.sales.find()

[
  {
    _id: 1,
    item: "abc",
    price: 10,
    fee: 2,
    discount: 5
  }
]

price 10
+ fee   2
− disc  5
--------
total   7

db.sales.aggregate([
  {
    $addFields: {
      afterDiscount: {
        $subtract: ["$price", "$discount"]
      }
    }
  }
]);

{
  _id: 1,
  item: "abc",
  price: 10,
  fee: 2,
  discount: 5,
  afterDiscount: 5
}

db.sales.aggregate([
  {
    $addFields: {
      total: {
        $subtract: [
          { $add: ["$price", "$fee"] },
          "$discount"
        ]
      }
    }
  }
]);

{
  _id: 1,
  item: "abc",
  price: 10,
  fee: 2,
  discount: 5,
  total: 7
}

Performance Notes

Arithmetic is cheap compared with large sorts or joins. Filter early with $match when only some documents need a computed total.

Key Takeaways