In MongoDB, the $add aggregation pipeline operator adds values together. Such values can be numbers, or they can be numbers and a date.

The $add operator accepts the values as arguments. The arguments can be any valid expression as long as they resolve to either all numbers or to numbers and a date.

Sample Data

Suppose we have a collection called data with the following documents:

{
	"_id" : 1,
	"a" : 100,
	"b" : 50,
	"c" : ISODate("2021-01-03T23:30:15.100Z")
}
{
	"_id" : 2,
	"a" : 20000,
	"b" : 15,
	"c" : ISODate("2019-12-08T04:00:20.112Z")
}
{
	"_id" : 3,
	"a" : 1700,
	"b" : 3,
	"c" : ISODate("2020-09-24T10:45:01.007Z")
}

Add Numbers

We can use the $add operator to add the a and b fields together.

Example:

db.data.aggregate(
   [
     { $project: { 
       _id: 0,
       a: 1, 
       b: 1, 
       result: { 
         $add: [ "$a", "$b" ] } } 
         }
   ]
)

Result:

{ "a" : 100, "b" : 50, "result" : 150 }
{ "a" : 20000, "b" : 15, "result" : 20015 }
{ "a" : 1700, "b" : 3, "result" : 1703 }

Add Numbers with a Date

If one of the arguments is a date, the other arguments are treated as milliseconds to add to the date.

Example:

db.data.aggregate(
   [
     { $project: { 
       _id: 0,
       a: 1, 
       c: 1, 
       result: { 
         $add: [ "$a", "$c" ] } } 
         }
   ]
).pretty()

Result:

{
	"a" : 100,
	"c" : ISODate("2021-01-03T23:30:15.100Z"),
	"result" : ISODate("2021-01-03T23:30:15.200Z")
}
{
	"a" : 20000,
	"c" : ISODate("2019-12-08T04:00:20.112Z"),
	"result" : ISODate("2019-12-08T04:00:40.112Z")
}
{
	"a" : 1700,
	"c" : ISODate("2020-09-24T10:45:01.007Z"),
	"result" : ISODate("2020-09-24T10:45:02.707Z")
}

We can see that the numeric values in the a field have been added as milliseconds to the c field.

More Arguments

The previous examples add two values together, but you can add more if required.

Here’s an example of adding all three fields together:

db.data.aggregate(
   [
     { $project: { 
       _id: 0,
       a: 1, 
       b: 1,
       c: 1, 
       result: { 
         $add: [ "$a", "$b", "$c" ] } } 
         }
   ]
).pretty()

Result:

{
	"a" : 100,
	"b" : 50,
	"c" : ISODate("2021-01-03T23:30:15.100Z"),
	"result" : ISODate("2021-01-03T23:30:15.250Z")
}
{
	"a" : 20000,
	"b" : 15,
	"c" : ISODate("2019-12-08T04:00:20.112Z"),
	"result" : ISODate("2019-12-08T04:00:40.127Z")
}
{
	"a" : 1700,
	"b" : 3,
	"c" : ISODate("2020-09-24T10:45:01.007Z"),
	"result" : ISODate("2020-09-24T10:45:02.710Z")
}

This time, both numbers were added to the date.

Only One Date Allowed

Although you can add many expressions together, you can only include one date. Passing multiple dates results in an error.

Example:

db.data.aggregate(
   [
     { $project: { 
       _id: 0,
       a: 1, 
       b: 1,
       c: 1, 
       result: { 
         $add: [ "$c", ISODate("2020-09-24T10:45:01.007Z") ] } } 
         }
   ]
).pretty()

Result:

uncaught exception: Error: command failed: {
	"ok" : 0,
	"errmsg" : "only one date allowed in an $add expression",
	"code" : 16612,
	"codeName" : "Location16612"
} : aggregate failed :
_getErrorWithCode@src/mongo/shell/utils.js:25:13
doassert@src/mongo/shell/assert.js:18:14
_assertCommandWorked@src/mongo/shell/assert.js:618:17
assert.commandWorked@src/mongo/shell/assert.js:708:16
DB.prototype._runAggregate@src/mongo/shell/db.js:266:5
DBCollection.prototype.aggregate@src/mongo/shell/collection.js:1046:12
@(shell):1:1

Passing No Arguments

Passing no arguments to $add results in 0 being returned.

Example:

db.data.aggregate(
   [
     { $project: { 
       result: { 
         $add: [  ] } } 
         }
   ]
)

Result:

{ "_id" : 1, "result" : 0 }
{ "_id" : 2, "result" : 0 }
{ "_id" : 3, "result" : 0 }

Passing Null Values

Passing null results in null.

Example:

db.data.aggregate(
   [
     { $project: { 
       result: { 
         $add: [ null ] } } 
         }
   ]
)

Result:

{ "_id" : 1, "result" : null }
{ "_id" : 2, "result" : null }
{ "_id" : 3, "result" : null }