$atan is a MongoDB aggregation expression that returns the inverse tangent (arc tangent) of a number—the angle whose tangent equals that value. Results are in radians (about -π/2 to π/2). Input can be any real number.
Remember
$atan = Math.atan for aggregation
{ $atan: <expression> }
input → any real number (slope / tangent value)
output → radians (−π/2 … π/2)
degrees → wrap with $radiansToDegrees
null / missing → null
NaN → NaN
Build the tangent if needed (often opposite / adjacent via $divide).
Pass that expression to $atan to get radians.
Optionally wrap with $radiansToDegrees for a degree result.
Piece
Required?
Role
$atan
Yes
Inverse tangent → radians
Expression
Yes
Any real number, field, or nested math
$radiansToDegrees
No
Convert output when you want degrees
Pseudocode
Pseudocode
for each document:
x = evaluate(expression)
if x is null or missing:
result = null
else if x is NaN:
result = NaN
else:
result = atan(x) // radians, any real x
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while writing inverse-tangent expressions.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $atan: <expression> }
Domain
All real numbers
Range
About -π/2 to π/2 radians
Degrees pattern
{ $radiansToDegrees: { $atan: <x> } }
Triangle pattern
$atan({ $divide: [opposite, adjacent] })
Sample check
3-4-5 triangle: atan(3/4) ≈ 36.87°
Try it
Live Preview
Watch $atan turn a tangent value into radians (and degrees). Negatives and zero are valid.
Simulates $atan then $radiansToDegrees (same idea as the mongosh examples below).
Result
x = 0.75
$atan(x) → 0.643501 rad
$radiansToDegrees → 36.869898 °
{ angle_rad: 0.643501, angle_deg: 36.869898 }
Trace
Worked Walkthrough — 3-4-5 Triangle
Right triangle with sides 3, 4, and 5. Angle A is opposite side_a (3), so tangent of A = opposite / adjacent = 3 / 4.
Right triangle (easy 3-4-5):
|\
| \
3 | \ 5 (hypotenuse)
(side_a)| \
| \
|_____\
4
(side_b)
We will find angle A (at the bottom-left corner):
tan(A) = side opposite A / side next to A
= side_a / side_b
= 3 / 4
= 0.75
How It Works
Insert once.insertOne adds a single triangle document to trigonometry.
MongoDB stores fields as written.side_a, side_b, and hypotenuse are just numbers: 3, 4, and 5.
find() shows the same shape. What you inserted is what you get back—ready for $atan in the next examples.
Example 2 — Angle in Radians
Goal: compute angle A in radians using tan(A) = side_a / side_b.
Easy check. In a 3-4-5 triangle, the smaller acute angle is about 37°—so 36.87° looks right.
Edge Cases & Pitfalls
Check these before using $atan in production pipelines.
units
Output is radians
Do not treat the raw result as degrees. Convert with $radiansToDegrees when your report expects °.
quad
Need all four quadrants?
A single slope loses quadrant info. Prefer $atan2 when you have separate x and y (especially if x can be zero).
null
Null and missing become null
Missing fields return null, not an error. Handle them before trig if nulls are invalid in your data.
div
Avoid divide-by-zero in slopes
Triangle or slope ratios need a non-zero adjacent/x. Guard with $cond or switch to $atan2.
Analysis
Performance Notes
Approach
Cost
Best for
$atan alone
Per-document math
Angles already stored as tangents / slopes
$divide + $atan
Still O(docs)
Right-triangle angles from sides
+ $radiansToDegrees
One extra conversion
Human-readable degree reports
Trig expressions are cheap compared with large sorts or joins. Filter early with $match when only some documents need an angle.
Remember
Key Takeaways
Role: inverse tangent → angle in radians.
Domain: any real number (no [-1, 1] clamp).
Degrees: wrap with $radiansToDegrees.
Triangles:$atan(opposite / adjacent).
One line:$atan answers “which angle has this tangent?”—in radians, for any real slope.
Frequently Asked Questions
$atan returns the inverse tangent (arc tangent) of a number—the angle whose tangent is that number. Results are in radians, roughly from -π/2 to π/2. Use it inside aggregation expression stages such as $project and $addFields.
Any real number—positive, negative, or zero. Unlike $asin or $acos, there is no [-1, 1] domain clamp.
$atan returns radians. Convert with $radiansToDegrees, or multiply by 180/π using $multiply and $divide.
$atan returns null when the input is null or the field is missing. If the argument is NaN, $atan returns NaN.
Use $atan when you already have a single slope (or y/x). Use $atan2 when you have separate x and y and need the correct quadrant, including when x is zero.
Yes for the math. Think of $atan as MongoDB’s aggregation version of Math.atan—run it in the pipeline, not as a standalone find() filter.
