$toLong is a MongoDB aggregation expression that converts a value to a 64-bit long integer. It is shorthand for { $convert: { input: <expr>, to: "long" } }.
Remember
$toLong = convert value → 64-bit long
{ $toLong: <expression> }
doubles → truncate toward 0
int strings → "100" OK; "2.5" ERROR
Date → millis since epoch
true → 1, false → 0
null / missing → null
Bigger than int32? Prefer $toLong over $toInt
Pass an integer string, number, or Date to $toLong.
Optional: sort or match on the converted long.
If strings may be invalid, prefer $convert with onError.
Piece
Required?
Role
$toLong
Yes
Convert expression → long (or null)
Expression
Yes
Int string, number (truncated), bool, Date, or long
$convert
No
Same conversion with error/null handling
Pseudocode
Pseudocode
for each document:
x = evaluate(expression)
if x is null or missing:
result = null
else if x is Date:
result = millisSinceEpoch(x)
else if x is double/decimal:
result = truncateTowardZero(x) // must fit int64
else if x is integer string / bool / int / long:
result = long(x)
else:
error // e.g. "2.5" string
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while converting to long integers.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $toLong: <expression> }
Shorthand for
{ $convert: { input: <e>, to: "long" } }
String example
"3000000000" → Long("3000000000")
Truncation
1.99999 → 1 (toward zero)
Date
Milliseconds since Unix epoch
vs $toInt
64-bit vs 32-bit; use long for large IDs
Try it
Live Preview
Pick an input and see the long-style result (browser demo of the same idea).
Same conversion. Stage one builds convertedId like Example 2.
Sort on the long.$sort: { convertedId: -1 } orders numerically, highest first.
Why convert first? Sorting raw strings can put "100" before "90"; longs compare by value.
Ada first.3000000000 is greater than 100.
Edge Cases & Pitfalls
Check these before using $toLong in production pipelines.
vs int
Use long when values may exceed int32
$toInt fails past ~2.1 billion. Prefer $toLong for large IDs and millisecond timestamps.
strings
"2.5" as a string fails
String inputs must be whole integers. Use $toDouble first (then $toLong), or $convert with onError.
truncate
Doubles truncate, they do not round
1.99999 → 1. Use $round first if you need nearest-integer behavior.
date
Dates become milliseconds
$toLong on a Date returns millis since the Unix epoch—useful for numeric time math.
Analysis
Performance Notes
Approach
Cost
Best for
$toLong per query
Per-document convert
Cleaning imported ID strings
Store Long / NumberLong
Cheapest long-term
IDs and counters you sort often
$convert + onError
Slightly more work
Dirty / nullable inputs
Prefer storing long integers when you control writes. Converting on every read is fine for cleanup, but avoid repeated string→long work on hot paths.
Remember
Key Takeaways
Role: convert a value to a 64-bit long integer.
vs $toInt: use long for values past ~2.1 billion.
Strings: whole integers only—"2.5" errors.
Dates: become milliseconds since the epoch.
One line:$toLong answers “turn this into a 64-bit whole number—safe for large IDs and millis.”
Frequently Asked Questions
$toLong converts a value to a 64-bit long integer inside an aggregation pipeline. Use it in stages such as $project and $addFields.
Use $toLong when values may exceed the 32-bit int range (about ±2.1 billion). Common cases include large IDs, Unix millisecond timestamps, and big counters.
$toLong is shorthand for { $convert: { input: <expr>, to: "long" } }. Use $convert with onError when invalid values should return a fallback instead of failing the pipeline.
$toLong truncates toward zero. For example, 1.99999 becomes 1. It does not round to the nearest integer.
No. String inputs must be base-10 integers such as "100" or "-2". Decimal-looking strings like "2.5" cause a conversion error.
$toLong returns null when the input is null or missing. It does not throw an error for null input.
