$mod
On this page
Definition
Syntax
To specify a $mod
expression, use the following syntax:
{ field: { $mod: [ divisor, remainder ] } }
Behavior
The $mod
operator returns an error if the [ divisor, remainder ]
array
contains fewer or more than two elements. For examples, see
Not Enough Elements Error and Too Many Elements Error respectively.
Also, starting in MongoDB 4.4.10, $mod
returns an error if the
divisor
or remainder
values evaluate to:
NaN
(not a number).Infinity
.A value that cannot 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 } ]