$sqrt is a MongoDB aggregation expression that returns the square root of a non-negative number. Input must be ≥ 0. Negative values make the pipeline fail.
Remember
$sqrt = Math.sqrt for aggregation
{ $sqrt: <expression> }
input → must be ≥ 0
output → double (or decimal if input is decimal)
√9 → 3
√0 → 0
null / missing → null
negative → pipeline error
Ensure the argument is ≥ 0 (filter with $match or guard with $cond).
Pass that expression to $sqrt.
For distance / hypotenuse, build a² + b² first, then take $sqrt.
Piece
Required?
Role
$sqrt
Yes
Square root → non-negative result
Expression
Yes
Number ≥ 0, field, or nested math
$pow / $add
No
Build sums of squares before the root
Pseudocode
Pseudocode
for each document:
x = evaluate(expression)
if x is null or missing:
result = null
else if x is NaN:
result = NaN
else if x < 0:
error // aggregation fails
else:
result = sqrt(x)
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while writing square-root expressions.
Take the root.$sqrt(25) is 5—the classic 3-4-5 hypotenuse.
Edge Cases & Pitfalls
Check these before using $sqrt in production pipelines.
domain
Negatives fail the pipeline
Unlike JavaScript Math.sqrt(-1) → NaN, MongoDB errors on negative input. Filter or guard first.
null
Null and missing become null
Missing fields return null, not an error. Handle them before roots if nulls are invalid in your data.
vs $pow
Prefer $sqrt over $pow(..., 0.5)
$pow works for any exponent. For square roots, $sqrt is clearer for readers and reviews.
zero
√0 is valid
$sqrt(0) returns 0. Zero is in the allowed domain.
Analysis
Performance Notes
Approach
Cost
Best for
$sqrt alone
Per-document math
Stored areas, variances, scores
$pow + $add + $sqrt
Still O(docs)
Distance / hypotenuse formulas
$match then $sqrt
Fewer docs to compute
Only some rows need a root
Math expressions are cheap compared with large sorts or joins. Filter early with $match when only some documents need a square root.
Remember
Key Takeaways
Role: square root of a non-negative number.
Domain: argument must be ≥ 0.
Geometry:$sqrt(a² + b²) for hypotenuse.
Negatives: pipeline error — not NaN.
One line:$sqrt answers “which non-negative number, squared, gives this value?”
Frequently Asked Questions
$sqrt returns the square root of a non-negative number as a double (or decimal if you use decimal input). Use it inside aggregation expression stages such as $project and $addFields.
Use { $sqrt: <expression> }. The expression can be a field like "$area", a literal such as 25, or nested math like { $add: [ "$a", "$b" ] }.
The aggregation fails with an error. Square roots of negative numbers are not supported as real values. Filter or clamp with $abs / $cond before calling $sqrt when negatives are possible.
$sqrt is the clear form for square roots. { $pow: [ "$x", 0.5 ] } can produce the same idea, but $sqrt is easier to read and intent is obvious.
$sqrt returns null when the input is null or the field is missing. If the argument is NaN, $sqrt returns NaN.
Yes for the math on non-negative numbers. Think of $sqrt as MongoDB’s aggregation version of Math.sqrt—run it in the pipeline, not as a standalone find() filter. Unlike Math.sqrt(-1) → NaN, MongoDB errors on negatives.
