The $atan operator returns the arc tangent (inverse tangent) of a number in MongoDB aggregation pipelines. If you know a slope or tangent ratio, $atan tells you the angle in radians.
Slope → angle.
One expression inside $atan.
Output is always in radians.
No -1 to 1 limit.
Geometry, vectors, engineering.
Full quadrant angles.
In MongoDB’s aggregation framework, the $atan operator computes the arc tangent of a numeric expression. For example, if tan(45°) = 1, then $atan(1) returns approximately 0.785 radians (which is 45°). The input is a tangent ratio (slope), not an angle — and the output is the angle in radians.
Think of $atan as the reverse of $tan. A common pattern is { $atan: { $divide: ["$y", "$x"] } } to get an angle from vector components — but for full quadrant accuracy, use $atan2 instead.
The $atan operator takes one numeric expression:
{ $atan: <expression> }$atan — returns the arc tangent of the expression in radians.<expression> — can be any real number (tangent ratio or slope).$project, $addFields, or $set.null, the result is null.-π/2 to π/2 radians.$atan(y/x) works for simple slopes but has two limitations:
$atan cannot distinguish all four quadrantsatan(2/-2) and atan(-1/1) both ≈ -0.79 rad$atan2 when you need the correct angle from separate x and y values| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (trigonometry) |
| Syntax | { $atan: <expression> } |
| Input range | Any real number |
| Output unit | Radians (range -π/2 to π/2) |
| Common stages | $project, $addFields, $set |
{
$atan: 1
}≈ 0.785 rad (45°)
{
$atan: "$slope"
}Angle from slope field
{
$atan: 0
}Returns 0 radians
{
$atan: null
}Returns null
Compute angles from slopes and vector components using $atan in aggregation pipelines.
Use a vectors collection with x and y components and compute the angle relative to the x-axis with $project.
Suppose you have a vectors collection with x and y components:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "x": 3, "y": 4 },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "x": -2, "y": 2 },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "x": 1, "y": -1 }
]Calculate the angle (in radians) of each vector relative to the x-axis by dividing y by x and applying $atan:
db.vectors.aggregate([
{
$project: {
x: 1,
y: 1,
angleRadians: {
$atan: { $divide: ["$y", "$x"] }
}
}
}
])atan(4/3) ≈ 0.927 rad (53°).atan(2/-2) ≈ -0.785 rad (-45°).atan(-1/1) ≈ -0.785 rad (-45°).$atan only sees the slope ratio, not the quadrant.Convert radians to degrees, use slope fields, and validate common tangent values.
MongoDB returns radians by default. Multiply by 180 / π to get degrees:
db.vectors.aggregate([
{
$project: {
x: 1,
y: 1,
angleRadians: {
$atan: { $divide: ["$y", "$x"] }
},
angleDegrees: {
$multiply: [
{ $atan: { $divide: ["$y", "$x"] } },
{ $divide: [ 180, 3.141592653589793 ] }
]
}
}
}
])The formula is degrees = radians × (180 / π). Use $multiply and $divide to apply it inside the pipeline.
When your documents already store a slope (rise over run), apply $atan directly:
db.terrain.aggregate([
{
$project: {
location: 1,
slope: 1,
inclineRadians: { $atan: "$slope" },
inclineDegrees: {
$multiply: [
{ $atan: "$slope" },
{ $divide: [ 180, 3.141592653589793 ] }
]
}
}
}
])
// slope: 0 → 0° (flat)
// slope: 1 → 45°
// slope: 0.5 → ≈ 26.6°A slope of 1 means a 45° incline. $atan converts any stored slope ratio into the corresponding angle in radians.
Common boundary values every beginner should know:
db.samples.aggregate([
{
$project: {
atanZero: { $atan: 0 }, // 0 rad (0°)
atanOne: { $atan: 1 }, // ≈ 0.785 rad (45°)
atanNeg: { $atan: -1 }, // ≈ -0.785 rad (-45°)
atanLarge: { $atan: 10 } // ≈ 1.471 rad (84.3°)
}
}
])$atan(0) = 0, $atan(1) = π/4 (45°), and large inputs approach but never reach 90°. For full quadrant angles from (x, y), see the $atan2 operator next.
$atan WorksThe pipeline evaluates the input — a field like "$slope" or an expression like { $divide: ["$y", "$x"] }.
MongoDB applies the arc tangent function and returns the angle in radians ( -π/2 to π/2 ).
The angle is written to the field you define in $project or $addFields.
Use the radians directly or convert to degrees for reports and dashboards.
The $atan operator is a practical trigonometry tool in MongoDB aggregation pipelines. It converts tangent ratios and slopes back into angles, which is essential for geometry, engineering, and any dataset that stores rise-over-run values instead of raw angles.
For beginners, remember three things: input is a slope (not an angle), output is in radians, and use $atan2 when you need the correct quadrant from separate x and y values.
$atan when you have a single slope or tangent ratio$round when displaying angle results$cond when x may be 0$atan2 for full quadrant accuracy$atan — it expects a tangent ratio$atan(y/x) when x can be zero without handling it$atan gives unique angles for all quadrants$atan (inverse tangent) with $tan (tangent)$atan as a query filter outside expressions$atanUse these points when working with trigonometric data in MongoDB.
Slope ratio → angle in radians.
Purpose{ $atan: expr }
No -1 to 1 limit.
DomainConvert to degrees if needed.
UnitsFor full quadrant angles.
TipMove on to $atan2 for correct quadrant angles, or review $asin for arc sine calculations.
5 people found this page helpful