$toDouble is a MongoDB aggregation expression that converts a value to a double (64-bit floating-point number). It is shorthand for { $convert: { input: <expr>, to: "double" } }.
Remember
$toDouble = convert value → double
{ $toDouble: <expression> }
numbers / numeric strings → double
true → 1, false → 0
Date → millis since epoch
null / missing → null
invalid string → pipeline error
Good for scores & measurements
(money? prefer $toDecimal)
Optional: sort or aggregate on the converted double.
If strings may be invalid, prefer $convert with onError.
Piece
Required?
Role
$toDouble
Yes
Convert expression → double (or null)
Expression
Yes
Number, numeric string, bool, Date, or double
$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 convertible (number, "26.1", bool, Date, …):
result = double(x)
else:
error // aggregation fails
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while converting to double.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $toDouble: <expression> }
Shorthand for
{ $convert: { input: <e>, to: "double" } }
String example
"26.1" → 26.1
Boolean
true → 1, false → 0
Date
Milliseconds since Unix epoch
vs $toDecimal
Double is binary float; decimal is better for money
Try it
Live Preview
Pick an input and see the double-style result (browser demo of the same idea).
Simulates $toDouble for numeric strings and booleans (same idea as the mongosh examples below).
Same conversion. Stage one builds degrees like Example 2.
Sort on the double.$sort: { degrees: -1 } orders highest first.
Why convert first? Sorting raw strings can fail for values like "9.5" vs "10.0"; doubles compare numerically.
Hottest first. Delhi (26.1) appears before Mumbai (25.4).
Edge Cases & Pitfalls
Check these before using $toDouble in production pipelines.
invalid
Non-numeric strings fail the pipeline
Values like "abc" or "26.1C" throw a conversion error. Strip units first (for example with $substrBytes), or use $convert with onError.
null
Null and missing become null
$toDouble returns null for null/missing inputs—it does not become zero.
money
Not ideal for currency
Binary floats can round. For money, prefer $toDecimal.
base
Only base-10 strings
Hex-style strings such as "0x6400" are not accepted. Use $convert with a base option when needed.
Analysis
Performance Notes
Approach
Cost
Best for
$toDouble per query
Per-document convert
Cleaning imported numeric strings
Store doubles
Cheapest long-term
Fields you sort/avg often
$convert + onError
Slightly more work
Dirty / nullable inputs
Prefer storing numeric types when you control writes. Converting on every read is fine for cleanup, but avoid repeated string→double work on hot paths.
Remember
Key Takeaways
Role: convert a value to a 64-bit double.
Use for: scores, measurements, general float math.
Invalid: bad strings error—use $convert for soft fails.
Money: prefer $toDecimal instead.
One line:$toDouble answers “turn this into a floating-point number I can sort and average.”
Frequently Asked Questions
$toDouble converts a value to a double (64-bit floating-point number) inside an aggregation pipeline. Use it in stages such as $project and $addFields.
Use $toDouble for general numeric work—scores, measurements, averages—where tiny floating-point rounding is acceptable. Use $toDecimal for currency and exact decimal math.
$toDouble is shorthand for { $convert: { input: <expr>, to: "double" } }. Use $convert with onError when invalid values should return a fallback instead of failing the pipeline.
$toDouble returns null when the input is null or missing. Invalid non-numeric strings cause a conversion error.
Yes. false → 0, true → 1. A Date becomes the millisecond count since the Unix epoch as a double.
Base-10 numeric strings such as "26.1" or "-5.5". Non-decimal forms like "0x6400" are not accepted by $toDouble.
