$mod (original) (raw)

$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.

To specify a $mod expression, use the following syntax:

{ field: { $mod: [ divisor, remainder ] } }

$mod returns an error if the [ divisor, remainder ] array doesn't contain two elements. For examples, seeNot Enough Elements Error and Too Many Elements Errorrespectively.

Also, starting in MongoDB 5.1 (and 5.0.4), $modreturns 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.

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.

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 theinventory collection where value of the qty field modulo4 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 }

]

The $mod operator errors when passed an array with fewer than two elements.

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

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

The $mod operator errors when passed an array with more than two elements.

For example, the following operation attempts to use the $modoperator 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

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.

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 theofficial JavaScript documentation.

Results:

[

  { _id: 1, item: 'abc123', qty: 0 },

  { _id: 3, item: 'ijk123', qty: 12 }

]