$add is a MongoDB aggregation expression that returns the sum of two or more numbers. Pass operands in an array. You can also add a number of milliseconds to a Date.
Remember
$add = + for aggregation
{ $add: [ <expr1>, <expr2>, ... ] }
numbers → sum of all values
date + number → date plus that many milliseconds
null / missing → null
needs ≥ 2 expressions in an array
List at least two expressions: fields ("$price"), literals (10), or nested math.
Pass that array to $add to get the sum.
For dates, keep one operand a Date and the other a millisecond number.
Piece
Required?
Role
$add
Yes
Sum of operands
Array of expressions
Yes (≥ 2)
Numbers, fields, nested ops, or Date + ms
$ifNull
No
Default missing/null values before adding
Pseudocode
Pseudocode
for each document:
values = evaluate each expression in the array
if any value is null or missing:
result = null
else if one value is a Date and others are numbers:
result = date + sum(milliseconds)
else:
result = sum(values)
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while writing addition expressions.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $add: [ <a>, <b>, ... ] }
Minimum args
Two expressions in the array
Null rule
Any null/missing → result is null
Date pattern
{ $add: [ "$createdAt", 86400000 ] } → +1 day
Order total
{ $add: [ "$price", "$tax", "$shipping" ] }
Sample check
40 + 5 + 10 = 55
Try it
Live Preview
Watch $add sum price, tax, and shipping—the same idea as the mongosh examples below.
Same stored document. Still using price 40, tax 5, and shipping 10 from Example 1.
Sum three expressions.$add adds every value in the array: 40 + 5 + 10 = 55.
Easy check. Price with tax was 45; plus shipping 10 makes 55—so the total looks right.
Edge Cases & Pitfalls
Check these before using $add in production pipelines.
array
Always pass an array
Unlike unary ops such as $abs, $add needs [ a, b, ... ]. A bare single value is invalid.
null
Null and missing become null
One missing field makes the whole sum null. Use $ifNull when zero is a better default.
date
Numbers mean milliseconds
Date + number adds milliseconds, not days. One day is 86400000. Prefer $dateAdd for calendar units.
vs sum
$add ≠ group $sum
$add sums expressions on one document. Across many documents, use the $sum accumulator.
Analysis
Performance Notes
Approach
Cost
Best for
$add of fields
Per-document math
Totals already on each doc
Many nested adds
Still O(docs)
Multi-step line-item math
Group with $sum
Aggregation across docs
Totals over many rows
Addition is cheap compared with large sorts or joins. Filter early with $match when only some documents need a computed total.
Remember
Key Takeaways
Role: sum two or more expressions on one document.
Syntax: always an array with at least two values.
Dates: number operands are milliseconds.
Nulls: any null/missing → result is null.
One line:$add is pipeline +—sum numbers (or add milliseconds to a date) with an array of expressions.
Frequently Asked Questions
$add sums two or more numeric expressions in an aggregation pipeline. It can also add a number of milliseconds to a Date. Use it inside expression stages such as $project and $addFields.
Use { $add: [ <expression1>, <expression2>, ... ] }. Pass an array with at least two expressions—field paths, literals, or nested expressions.
Yes. $add accepts two or more expressions and returns the sum of all of them.
Yes. When one operand is a Date and another is a number, MongoDB treats the number as milliseconds and adds it to the date.
If any argument is null or missing, $add returns null. Use $ifNull to supply a default before adding.
Yes for numbers. Think of $add as MongoDB’s aggregation version of +—run it in the pipeline, not as a standalone find() filter.
