The $toInt operator converts values to a 32-bit integer in MongoDB aggregation pipelines. Use it to parse whole-number strings, truncate decimals, and enable integer math on imported or mixed-type data.
Values to int32.
One expression.
Doubles → whole nums.
Parse qty fields.
Counts, IDs, imports.
32-bit vs 64-bit.
In MongoDB’s aggregation framework, the $toInt operator converts an expression to a 32-bit signed integer. Imported data often stores quantities, counts, and IDs as strings like "42" or "100". $toInt parses those into whole numbers for sorting, counting, and integer arithmetic.
$toInt is shorthand for { $convert: { input: <expression>, to: "int" } }. When converting doubles, it truncates toward zero — so 3.9 becomes 3, not 4.
Int32 range is roughly -2.1 billion to 2.1 billion. For larger whole numbers (like big user IDs or timestamps), use $toLong instead.
The $toInt operator takes one expression:
{ $toInt: <expression> }{ $toInt: "42" }
// Result: 42
{ $toInt: 3.9 }
// Result: 3 (truncates toward zero)
{ $toInt: -3.9 }
// Result: -3
{ $toInt: "$quantity" }
// Convert the quantity fieldnull — returns null.true becomes 1, false becomes 0.$project, $addFields, $set, or $group.$toInt when values fit in int32 and you need whole numbers only| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (type conversion) |
| Syntax | { $toInt: <expression> } |
| Output type | 32-bit signed integer (int32) |
| Equivalent | { $convert: { input: <expr>, to: "int" } } |
| Double behavior | Truncates toward zero (3.9 → 3) |
| Common stages | $project, $addFields, $group |
{
$toInt: "$quantity"
}Parse text integer
{
$toInt: 3.9
}Returns 3
{
$sum: {
$toInt: "$qty"
}
}Total quantities
{
$toInt: true
}Returns 1
Parse string quantities, truncate doubles to whole numbers, sum inventory counts, and handle conversion safely with $convert.
Start with an inventory collection where quantities are stored as strings and convert them with $toInt.
Suppose you have an inventory collection with string quantities from a CSV import:
[
{ "_id": 1, "item": "Widget A", "quantity": "50" },
{ "_id": 2, "item": "Widget B", "quantity": "120" },
{ "_id": 3, "item": "Widget C", "quantity": "75" },
{ "_id": 4, "item": "Widget D", "quantity": "30" }
]Parse the quantity string into a 32-bit integer:
db.inventory.aggregate([
{
$project: {
item: 1,
quantity: 1,
qtyInt: { $toInt: "$quantity" }
}
}
])$toInt parses whole-number strings into integers. Once converted, the field supports integer sorting, comparison, and arithmetic.
Truncate doubles, sum quantities, and filter by integer thresholds.
When a field stores a decimal, $toInt truncates toward zero:
db.metrics.aggregate([
{
$project: {
value: 1,
wholeNumber: { $toInt: "$value" }
}
}
])
// value: 3.9 → wholeNumber: 3
// value: -2.7 → wholeNumber: -2
// value: 10.0 → wholeNumber: 10$toInt does not round — it drops the fractional part. Use $round first if you need rounding before conversion.
Convert string quantities and compute total stock:
db.inventory.aggregate([
{
$group: {
_id: null,
totalStock: {
$sum: { $toInt: "$quantity" }
},
itemCount: { $sum: 1 }
}
}
])
// totalStock: 275 (50 + 120 + 75 + 30)$sum requires numeric input. Wrapping each quantity in $toInt converts string values before summing.
Convert quantities, then find low-stock items:
db.inventory.aggregate([
{
$addFields: {
qtyInt: { $toInt: "$quantity" }
}
},
{
$match: {
qtyInt: { $lt: 50 }
}
},
{
$project: {
item: 1,
qtyInt: 1
}
}
])
// Returns Widget D only (qtyInt: 30 < 50)Convert first, then filter. Comparing strings like "9" and "120" alphabetically would give wrong results.
When you need rounding instead of truncation:
db.metrics.aggregate([
{
$project: {
value: 1,
truncated: { $toInt: "$value" },
rounded: {
$toInt: { $round: [ "$value", 0 ] }
}
}
}
])
// value: 3.6
// truncated → 3
// rounded → 4Combine $round with $toInt when you want nearest-integer behavior instead of truncation.
When quantities may be invalid, use $convert with onError:
db.inventory.aggregate([
{
$project: {
item: 1,
qtyInt: {
$convert: {
input: "$quantity",
to: "int",
onError: 0,
onNull: 0
}
}
}
}
])
// "50" → 50
// "N/A" → 0 (fallback)
// null → 0$toInt errors on invalid strings. $convert with onError lets the pipeline continue with a safe default.
$sum and grouping.$toInt WorksThe input resolves from a field path, numeric string, number, boolean, or nested expression.
Strings are parsed; doubles and decimals are truncated toward zero; booleans become 0 or 1.
The output supports $add, $sum, sorting, and integer comparisons.
Use in counts, sums, filters, and integer arithmetic pipelines.
The $toInt operator converts values to 32-bit integers in MongoDB aggregation pipelines. It is ideal for parsing whole-number strings, truncating decimals, and enabling integer math on mixed-type data.
For values outside the int32 range, use $toLong. For decimal fractions, use $toDouble. For conversions with error handling, use $convert. Next in the series: $toLong.
$toInt for counts, quantities, and small whole numbers$sum when fields are stored as strings$round first when you need rounding, not truncation$convert with onError for messy imported data$toLong when values exceed int32 range$toInt to round (it truncates toward zero)$toInt for large IDs beyond ~2.1 billion$toInt when you need decimal fractions$toIntUse these points when converting values to integers in MongoDB.
Whole numbers.
PurposeOne argument.
Syntax3.9 → 3.
BehaviorString to int.
UsageUse $toLong.
RangeMove on to $toLong for 64-bit integers, or review $convert for flexible type transforms.
5 people found this page helpful