The $atan2 operator returns the angle (in radians) from the positive x-axis to a point defined by (x, y) coordinates. It fixes the quadrant limitations of $atan and works even when x is zero.
Takes y and x separately.
[y, x] array form.
Full -π to π range.
Argument order matters.
Vectors, navigation, maps.
No division by zero.
In MongoDB’s aggregation framework, the $atan2 operator computes the arc tangent of y/x while using the signs of both y and x to determine the correct quadrant. For example, $atan2(1, 1) returns approximately 0.785 rad (45°), while $atan2(1, -1) returns approximately 2.356 rad (135°) — same slope, different quadrant.
Think of $atan2 as MongoDB’s version of Math.atan2(y, x). The y value comes first, then x. This order is easy to mix up, so double-check your pipeline.
The $atan2 operator takes two numeric expressions in an array:
{ $atan2: [ <y>, <x> ] }$atan2 — returns the angle in radians from the positive x-axis to the point (x, y).<y> — the y-coordinate (first argument).<x> — the x-coordinate (second argument).-π to π radians (approximately -3.14 to 3.14).x = 0 (returns ±π/2 depending on the sign of y).null, the result is null.The most common mistake is swapping the arguments. MongoDB uses the same order as JavaScript:
{ $atan2: ["$y", "$x"] }{ $atan2: ["$x", "$y"] } (swapped!)$atan2(1, 1) → 0.785 rad (45°)$atan2(1, -1) → 2.356 rad (135°)| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (trigonometry) |
| Syntax | { $atan2: [<y>, <x>] } |
| Argument order | y first, then x |
| Output unit | Radians (range -π to π) |
| Common stages | $project, $addFields, $set |
{
$atan2: [1, 1]
}≈ 0.785 rad (45°)
{
$atan2: ["$y", "$x"]
}Angle from coordinates
{
$atan2: [3, 0]
}≈ 1.571 rad (90°)
{
$atan2: [null, 1]
}Returns null
Compute full-quadrant angles from x and y coordinates using $atan2 in aggregation pipelines.
Use a vectors collection with x and y components and compute the correct quadrant angle 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) for each vector. Note that y comes first in the array:
db.vectors.aggregate([
{
$project: {
x: 1,
y: 1,
angleRadians: { $atan2: ["$y", "$x"] },
angleWithAtan: {
$atan: { $divide: ["$y", "$x"] }
}
}
}
])0.927 rad (53°).$atan2 returns 2.356 rad (135°), but $atan gives -0.785 (wrong quadrant).-0.785 rad (-45°).Handle edge cases, convert to degrees, and apply to navigation-style data.
$atan2 handles vertical vectors without division errors:
db.vectors.aggregate([
{
$project: {
x: 1,
y: 1,
angleRadians: { $atan2: ["$y", "$x"] }
}
}
])
// Sample documents:
// { x: 0, y: 3 } → atan2(3, 0) ≈ 1.571 rad (90°, straight up)
// { x: 0, y: -2 } → atan2(-2, 0) ≈ -1.571 rad (-90°, straight down)
// { x: 0, y: 0 } → atan2(0, 0) = 0 (origin point)With $atan({ $divide: ["$y", "$x"] }), dividing by zero fails or returns null. $atan2 avoids division entirely and returns the correct angle.
Convert the angle to degrees for navigation or mapping dashboards:
db.vectors.aggregate([
{
$project: {
x: 1,
y: 1,
bearingRadians: { $atan2: ["$y", "$x"] },
bearingDegrees: {
$multiply: [
{ $atan2: ["$y", "$x"] },
{ $divide: [ 180, 3.141592653589793 ] }
]
}
}
}
])The formula is degrees = radians × (180 / π). Negative degrees indicate angles below the x-axis.
Compute the bearing from one location to another by subtracting coordinates first:
db.routes.aggregate([
{
$project: {
from: 1,
to: 1,
deltaX: { $subtract: ["$to.x", "$from.x"] },
deltaY: { $subtract: ["$to.y", "$from.y"] }
}
},
{
$project: {
from: 1,
to: 1,
directionRadians: {
$atan2: ["$deltaY", "$deltaX"]
}
}
}
])Subtract the starting point from the destination to get deltaX and deltaY, then pass them to $atan2 as [deltaY, deltaX]. This pattern is common in navigation and game development pipelines.
deltaX and deltaY.$atan2 WorksThe pipeline evaluates both arguments — typically fields like "$y" and "$x" or computed deltas.
Using both signs, MongoDB computes the full angle from -π to π without dividing y by x.
The angle is written to the field you define in $project or $addFields.
Use the radians directly or convert to degrees for bearings and headings.
The $atan2 operator is the right choice when you have separate x and y values and need the correct angle in all four quadrants. It avoids division-by-zero problems and fixes the quadrant ambiguity that $atan cannot resolve on its own.
For beginners, remember: y comes first, output is in radians, and always prefer $atan2 over $atan(y/x) when both coordinates are available.
[y, x] — y first, x second$atan2 when you have separate coordinate values$multiply and $divide when needed$atan to verify quadrant behavior[x, y]$atan(y/x) when quadrant accuracy matters$atan2 with $atan (single argument)$atan2Use these points when working with two-argument angles in MongoDB.
y and x as an array.
Purpose{ $atan2: [y, x] }
Range -π to π.
DomainNo division needed.
Edge caseCorrect quadrant angles.
TipMove on to $atanh for inverse hyperbolic tangent, or review $atan for single-argument arc tangent.
5 people found this page helpful