In MongoDB, the $mod aggregation pipeline operator divides one number by another and returns the remainder.

To use $mod, pass the two numbers in an array. The $mod operator will divide the first number by the second number and return the remainder. In other words, the first number is the dividend, and the second number is the divisor.

The arguments can be any valid expression as long as they resolve to numbers.

Example

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

{ "_id" : 1, "a" : 10, "b" : 2 }
{ "_id" : 2, "a" : 10, "b" : 3 }
{ "_id" : 3, "a" : 10.5, "b" : 2 }

We can use the $mod operator within an aggregation pipeline to divide the a field by the b field, and return the remainder:

db.data.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3 ] } } },
     { $project: { 
        _id: 0,
        a: 1,
        b: 1,
        result: { $mod: [ "$a", "$b" ] } } 
         }
   ]
)

Result:

{ "a" : 10, "b" : 2, "result" : 0 }
{ "a" : 10, "b" : 3, "result" : 1 }
{ "a" : 10.5, "b" : 2, "result" : 0.5 }

In other words, we get a modulo b.

If we want to get b modulo a, we would need to swap them around.

Example:

db.data.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3 ] } } },
     { $project: { 
        _id: 0,
        a: 1,
        b: 1,
        result: { $mod: [ "$b", "$a" ] } } 
         }
   ]
)

Result:

{ "a" : 10, "b" : 2, "result" : 2 }
{ "a" : 10, "b" : 3, "result" : 3 }
{ "a" : 10.5, "b" : 2, "result" : 2 }

Negative Numbers

Suppose we add the following documents to our collection:

{ "_id" : 4, "a" : -10, "b" : 3 }
{ "_id" : 5, "a" : 10, "b" : -3 }
{ "_id" : 6, "a" : -10, "b" : -3 }

These include negative numbers. But that’s not a problem, because negative numbers are still numbers, and we can certainly get the modulo when working with negative numbers.

Example:

db.data.aggregate(
   [
     { $match: { _id: { $in: [ 4, 5, 6 ] } } },
     { $project: { 
        _id: 0,
        a: 1,
        b: 1,
        result: { $mod: [ "$a", "$b" ] } } 
         }
   ]
)

Result:

{ "a" : -10, "b" : 3, "result" : -1 }
{ "a" : 10, "b" : -3, "result" : 1 }
{ "a" : -10, "b" : -3, "result" : -1 }

Wrong Data Type

The arguments provided to $mod can be any valid expression, as long as they resolve to numbers.

Suppose we have the following document:

{ "_id" : 7, "a" : "Ten", "b" : 2 }

And we apply $mod to that document:

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

Result:

uncaught exception: Error: command failed: {
	"ok" : 0,
	"errmsg" : "$mod only supports numeric types, not string and double",
	"code" : 16611,
	"codeName" : "Location16611"
} : aggregate failed :
_getErrorWithCode@src/mongo/shell/utils.js:25:13
doassert@src/mongo/shell/assert.js:18:14
_assertCommandWorked@src/mongo/shell/assert.js:639:17
assert.commandWorked@src/mongo/shell/assert.js:729:16
DB.prototype._runAggregate@src/mongo/shell/db.js:266:5
DBCollection.prototype.aggregate@src/mongo/shell/collection.js:1058:12
@(shell):1:1

The error states that $mod only supports numeric types.

Null Values

Providing null for any of the arguments returns null.

Suppose we have the following documents:

{ "_id" : 8, "a" : 10, "b" : null }
{ "_id" : 9, "a" : null, "b" : 10 }
{ "_id" : 10, "a" : null, "b" : null }

And we apply $mod to those documents:

db.data.aggregate(
   [
     { $match: { _id: { $in: [ 8, 9, 10 ] } } },
     { $project: { 
        _id: 0,
        a: 1,
        b: 1,
        result: { $mod: [ "$a", "$b" ] } } 
         }
   ]
)

Result:

{ "a" : 10, "b" : null, "result" : null }
{ "a" : null, "b" : 10, "result" : null }
{ "a" : null, "b" : null, "result" : null }

Missing Fields

Missing fields return null.

Suppose we have the following documents:

{ "_id" : 11, "a" : 10 }
{ "_id" : 12, "b" : 2 }
{ "_id" : 13 }

Apply $mod:

db.data.aggregate(
   [
     { $match: { _id: { $in: [ 11, 12, 13 ] } } },
     { $project: { 
        _id: 0,
        a: 1,
        b: 1,
        result: { $mod: [ "$a", "$b" ] } } 
         }
   ]
)

Result:

{ "a" : 10, "result" : null }
{ "b" : 2, "result" : null }
{ "result" : null }

Add Your Own Number

You aren’t necessarily restricted to just the numbers in the document/s. You can use your own numbers if you need to divide a field by a fixed amount.

Example:

db.data.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3 ] } } },
     { $project: { 
        _id: 0,
        a: 1,
        b: 1,
        result: { $mod: [ "$a", 5.2 ] } } 
         }
   ]
)

Result:

{ "a" : 10, "b" : 2, "result" : 4.8 }
{ "a" : 10, "b" : 3, "result" : 4.8 }
{ "a" : 10.5, "b" : 2, "result" : 0.09999999999999964 }