The $mod operator performs modulo (remainder) math in MongoDB. It appears in two forms: as a query filter in find() and $match, and as an aggregation expression that computes remainders inside pipelines.
dividend % divisor.
Query vs aggregation.
Filter multiples of N.
Parity checks.
Buckets, sampling.
Context matters.
Modulo returns the remainder after division. For example, 10 % 3 = 1, 15 % 3 = 0, and 20 % 3 = 2. MongoDB’s $mod lets you apply this logic to stored numeric fields.
In an aggregation expression, { $mod: [ dividend, divisor ] } computes and returns the remainder. In a query, { field: { $mod: [ divisor, remainder ] } } matches documents where field % divisor == remainder.
The argument order differs between query and aggregation $mod. In queries, the second value is the expected remainder. In aggregation, the second value is the divisor you divide by.
MongoDB uses $mod in two contexts. Learn both:
{ $mod: [ <dividend>, <divisor> ] }{ <field>: { $mod: [ <divisor>, <remainder> ] } }[dividend, divisor]; returns the computed remainder.[divisor, remainder]; matches when field % divisor == remainder.$mod returns null if either operand is null.{ value: { $mod: [ 3, 0 ] } } → matches where value is divisible by 3{ $mod: [ "$value", 3 ] } → returns remainder (10→1, 15→0, 20→2)| Question | Answer |
|---|---|
| Operator type | Query operator and aggregation expression operator |
| Aggregation syntax | { $mod: [ dividend, divisor ] } |
| Query syntax | { field: { $mod: [ divisor, remainder ] } } |
| Return type (aggregation) | Integer remainder (or null) |
| Common uses | Divisibility filters, odd/even, bucketing |
{ $mod: [ "$value", 3 ] }Aggregation expression
{
value: { $mod: [ 3, 0 ] }
}Query filter
{
value: { $mod: [ 2, 0 ] }
}remainder 0
{
remainder: {
$mod: [ "$value", 5 ]
}
}Add computed field
Compute remainders in aggregation, filter divisible values in queries, check odd/even parity, and assign buckets with $mod.
Start with a numbers collection and explore both aggregation and query forms of $mod.
Suppose you have a numbers collection:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "value": 10 },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "value": 15 },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "value": 20 }
]Use aggregation $mod to add a remainder field (divide each value by 3):
db.numbers.aggregate([
{
$project: {
value: 1,
remainder: { $mod: [ "$value", 3 ] }
}
}
])10 % 3 = 115 % 3 = 0 (divisible by 3)20 % 3 = 2Query filters, parity checks, and bucket assignment.
Find documents where value is a multiple of 3 using query syntax:
db.numbers.find({
value: { $mod: [ 3, 0 ] }
})Query $mod uses [divisor, remainder]. Here [3, 0] means “match when value % 3 == 0.” Only 15 qualifies; 10 and 20 are filtered out.
In aggregation $match, use expression $mod with $eq:
db.numbers.aggregate([
{
$match: {
$expr: {
$eq: [
{ $mod: [ "$value", 2 ] },
0
]
}
}
}
])Inside $expr, aggregation $mod computes value % 2. When the result equals 0, the number is even. This pattern works for any parity or divisibility check in pipelines.
Split records into 4 buckets using modulo for round-robin sampling:
db.users.aggregate([
{
$project: {
name: 1,
userId: 1,
bucket: { $mod: [ "$userId", 4 ] }
}
}
])$mod maps each userId to bucket 0, 1, 2, or 3. You can then process one bucket per job run, spread load across workers, or sample a subset evenly.
Add a readable parity label using $mod and $cond:
db.numbers.aggregate([
{
$project: {
value: 1,
parity: {
$cond: {
if: {
$eq: [
{ $mod: [ "$value", 2 ] },
0
]
},
then: "even",
else: "odd"
}
}
}
}
])10 and 20 become "even"; 15 becomes "odd". Combine $mod with $cond whenever you need categorical labels from numeric rules.
$mod WorksFields or literals are evaluated per document. Check whether you are in query or aggregation context.
Aggregation returns dividend % divisor. Query compares field % divisor to the expected remainder.
Aggregation stores the remainder in a new field. Query includes or excludes documents based on the match.
Use for divisibility, parity, bucketing, and cyclic data patterns across queries and pipelines.
The $mod operator brings modulo arithmetic to MongoDB queries and aggregation pipelines. Use the query form to filter by divisibility, and the aggregation form to compute remainders as new fields.
The most common beginner mistake is swapping the argument order. Remember: query uses [divisor, remainder], aggregation uses [dividend, divisor]. Next in the series: $month.
$mod or aggregation $mod{ $mod: [ N, 0 ] } for “divisible by N” filters$mod with $eq inside $exprfind() filter$mod works on non-numeric strings$mod with JavaScript’s % operator syntax$modUse these points when working with modulo logic in MongoDB.
dividend % divisor.
PurposeQuery vs aggregation.
SyntaxDiffers by context.
Critical[N, 0] in queries.
Use caseThrows an error.
Edge caseMove on to $month for date extraction, or review $divide for division in pipelines.
5 people found this page helpful