$acos is a MongoDB aggregation expression that returns the inverse cosine (arc cosine) of a number—the angle whose cosine equals that value. Results are in radians. Input must be between -1 and 1 inclusive.
Remember
$acos = Math.acos for aggregation
{ $acos: <expression> }
input → must be in [-1, 1]
output → radians (0 … π)
degrees → wrap with $radiansToDegrees
null / missing → null
outside [-1, 1] → pipeline error
Ensure the argument is in [-1, 1] (often adjacent / hypotenuse via $divide).
Pass that expression to $acos to get radians.
Optionally wrap with $radiansToDegrees for a degree result.
Piece
Required?
Role
$acos
Yes
Inverse cosine → radians
Expression
Yes
Number in [-1, 1], 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 if x < -1 or x > 1:
error // aggregation fails
else:
result = acos(x) // radians
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while writing inverse-cosine expressions.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $acos: <expression> }
Domain
-1 ≤ x ≤ 1
Range
0 to π radians
Degrees pattern
{ $radiansToDegrees: { $acos: <x> } }
Triangle pattern
$acos({ $divide: [adjacent, hypotenuse] })
Sample check
3-4-5 triangle: acos(4/5) ≈ 36.87°
Try it
Live Preview
Watch $acos turn a cosine value into radians (and degrees). Try values in [-1, 1].
Simulates $acos then $radiansToDegrees (same idea as the mongosh examples below).
Result
x = 0.8
$acos(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 cosine of A = adjacent / hypotenuse = 4 / 5.
Right triangle (easy 3-4-5):
|\
| \
3 | \ 5 (hypotenuse)
(side_a)| \
| \
|_____\
4
(side_b)
We will find angle A (at the bottom-left corner):
cos(A) = side next to A / longest side
= side_b / hypotenuse
= 4 / 5
= 0.8
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 $acos in the next examples.
Example 2 — Angle in Radians
Goal: compute angle A in radians using cos(A) = side_b / hypotenuse.
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 $acos in production pipelines.
domain
Stay inside [-1, 1]
Values outside the domain make the pipeline fail. Clamp or validate ratios before calling $acos.
units
Output is radians
Do not treat the raw result as degrees. Convert with $radiansToDegrees when your report expects °.
null
Null and missing become null
Missing fields return null, not an error. Handle them before trig if nulls are invalid in your data.
hyp
Avoid divide-by-zero
Triangle ratios need a non-zero hypotenuse. Guard with $cond or filter bad rows first.
Analysis
Performance Notes
Approach
Cost
Best for
$acos alone
Per-document math
Angles already stored as cosines
$divide + $acos
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 cosine → angle in radians.
Domain: argument must be in [-1, 1].
Degrees: wrap with $radiansToDegrees.
Triangles:$acos(adjacent / hypotenuse).
One line:$acos answers “which angle has this cosine?”—in radians, for inputs between -1 and 1.
Frequently Asked Questions
$acos returns the inverse cosine (arc cosine) of a number—the angle whose cosine is that number. Results are in radians. Use it inside aggregation expression stages such as $project and $addFields.
The argument must resolve to a number between -1 and 1 inclusive. Values outside that range cause the aggregation to fail with an error.
$acos returns radians. Convert with $radiansToDegrees, or multiply by 180/π using $multiply and $divide.
$acos returns null when the input is null or the field is missing. If the argument is NaN, $acos returns NaN.
Cosine equals adjacent / hypotenuse. Divide those sides, then pass the ratio to $acos. Wrap with $radiansToDegrees if you want degrees.
Yes for the math. Think of $acos as MongoDB’s aggregation version of Math.acos—run it in the pipeline, not as a standalone find() filter.
