$mod
On this page
Definition
Syntax
To specify a $mod expression, use the following syntax:
{ field: { $mod: [ divisor, remainder ] } }
Behavior
$mod returns an error if the [ divisor, remainder ] array
doesn't contain two elements. For examples, see
Not Enough Elements Error and Too Many Elements Error
respectively.
Also, starting in MongoDB 5.1 (and 5.0.4), $mod
returns an error if the divisor or remainder values evaluate to:
NaN(not a number).Infinity.A value that can't be represented using a 64-bit integer.
If a document in the collection contains a field where the value is NaN
(not a number) or Infinity, $mod doesn't include the document in the
output.
Negative Dividend
When the dividend is negative, the remainder is also negative. For more details on this behavior, see the official JavaScript documentation.
For an example, see Negative Dividend.
Examples
Use $mod to Select Documents
Create an inventory collection:
db.inventory.insertMany( [ { "_id" : 1, "item" : "abc123", "qty" : 0 }, { "_id" : 2, "item" : "xyz123", "qty" : 5 }, { "_id" : 3, "item" : "ijk123", "qty" : 12 } ] )
Then, the following query selects those documents in the
inventory collection where value of the qty field modulo
4 equals 0:
db.inventory.find( { qty: { $mod: [ 4, 0 ] } } )
The query returns the following documents:
[ { '_id' : 1, 'item' : 'abc123', 'qty' : 0 }, { '_id' : 3, 'item' : 'ijk123', 'qty' : 12 } ]
Not Enough Elements Error
The $mod operator errors when passed an array with fewer than
two elements.
Array with Single Element
The following operation incorrectly passes the $mod operator
an array that contains a single element:
db.inventory.find( { qty: { $mod: [ 4 ] } } )
The statement results in the following error:
MongoServerError: malformed mod, not enough elements
Empty Array
The following operation incorrectly passes the $mod operator
an empty array:
db.inventory.find( { qty: { $mod: [ ] } } )
The statement results in the following error:
MongoServerError: malformed mod, not enough elements
Too Many Elements Error
The $mod operator errors when passed an array with more than
two elements.
For example, the following operation attempts to use the $mod
operator with an array that contains four elements:
db.inventory.find( { qty: { $mod: [ 4, 1, 2, 3 ] } } )
The statement results in the following error:
MongoServerError: malformed mod, too many elements
Floating Point Arguments
The $mod expression rounds decimal input towards zero.
The following examples demonstrate this behavior:
Example
Input query:
db.inventory.find( { qty: { $mod: [ 4.0, 0 ] } } )
Results:
[ { _id: 1, item: 'abc123', qty: 0 }, { _id: 3, item: 'ijk123', qty: 12 } ]
Example
Input query:
db.inventory.find( { qty: { $mod: [ 4.5, 0 ] } } )
Results:
[ { _id: 1, item: 'abc123', qty: 0 }, { _id: 3, item: 'ijk123', qty: 12 } ]
Example
Input query:
db.inventory.find( { qty: { $mod: [ 4.99, 0 ] } } )
Results:
[ { _id: 1, item: 'abc123', qty: 0 }, { _id: 3, item: 'ijk123', qty: 12 } ]
Each query applies 4 to the $mod expression regardless of
decimal points, resulting in the same result set.
Negative Dividend
The $mod expression produces a negative result when the dividend
is negative.
The following example demonstrates this behavior:
Example
Input query:
db.inventory.find( { qty: { $mod: [ -4, -0 ] } } )
This query returns two documents because the qty has a remainder
of -0 when the dividend is negative and -0 equals 0 in
JavaScript. For details on this equality, see the
official JavaScript documentation.
Results:
[ { _id: 1, item: 'abc123', qty: 0 }, { _id: 3, item: 'ijk123', qty: 12 } ]