Database Manual / Reference / Query Language / Query Predicates / Miscellaneous

$mod

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.也就是说，$mod执行模运算来选择文档。第一个参数是除数，第二个论点是余数。

Syntax语法

To specify a $mod expression, use the following syntax:要指定$mod表达式，请使用以下语法：

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

Behavior行为

$mod returns an error if the [ divisor, remainder ] array doesn't contain two elements. 如果[ divisor, remainder ]数组不包含两个元素，则返回错误。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:此外，从MongoDB 5.1（和5.0.4）开始，如果divisor或remainder的计算结果为以下情况，$mod将返回错误：

  • NaN (not a number).（不是数字）。
  • Infinity.。
  • A value that can't be represented using a 64-bit integer.无法使用64位整数表示的值。

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.如果集合中的文档包含值为NaN（不是数字）或Infinity的字段，则$mod不会将该文档包含在输出中。

Negative Dividend负相除

When the dividend is negative, the remainder is also negative. For more details on this behavior, see the official JavaScript documentation.当除数为负时，余数也为负。有关此行为的更多详细信息，请参阅官方JavaScript文档。

For an example, see Negative Dividend.例如，请参阅负相除。

Examples示例

Use $mod to Select Documents使用$mod选择文档

Create an inventory collection:创建inventory集合：

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:然后，以下查询选择inventory集合中qty字段模4的值等于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.传递少于两个元素的数组时，$mod运算符出错。

Array with Single Element单元素数组

The following operation incorrectly passes the $mod operator an array that contains a single element:以下操作错误地向$mod运算符传递了一个包含单个元素的数组：

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:以下操作错误地将空数组传递给$mod运算符：

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.传递包含两个以上元素的数组时，$mod运算符出错。

For example, the following operation attempts to use the $mod operator with an array that contains four elements:例如，以下操作尝试对包含四个元素的数组使用$mod运算符：

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.$mod表达式将十进制输入四舍五入为零。

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.无论小数点如何，每个查询都会对$mod表达式应用4，从而得到相同的结果集。

Negative Dividend负相除

The $mod expression produces a negative result when the dividend is negative.当股息为负时，$mod表达式会产生负结果。

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.此查询返回两个文档，因为当除数为负时，qty的余数为-0，而在JavaScript中，-0等于0。有关此等式的详细信息，请参阅官方JavaScript文档。

Results:结果：

[
  { _id: 1, item: 'abc123', qty: 0 },
  { _id: 3, item: 'ijk123', qty: 12 }
]