Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Operators
/
Query and Projection Operators
/
Evaluation Query Operators

$mod

On this page

  • Behavior
  • Examples
$mod

Select documents where the value of a field divided by a divisor has the specified remainder (i.e. perform a modulo operation to select documents). 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 5.1 (and 5.0.4 and 4.4.10), $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.

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.

Back

$jsonSchema

On this page