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

$mod

On this page

  • Definition
  • Syntax
  • Behavior
  • Examples

Definition

$mod

Select documents where the value of a field divided by a divisor has the specified remainder. That is, $mod performs a modulo operation to select documents. The first argument is the dividend, and the second argument is the remainder.

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 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 }
]

Back

$jsonSchema

Next

$regex