MongoDB $atanh Operator

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
MongoDB $atanh tutorial — inverse hyperbolic tangent in aggregation pipelines
Definition

What Is $atanh?

$atanh is a MongoDB aggregation expression that returns the inverse hyperbolic tangent (arc hyperbolic tangent) of a number—the value y such that tanh(y) equals that input. The argument must be strictly between -1 and 1 (not including ±1).

Remember
$atanh = Math.atanh for aggregation

{ $atanh: <expression> }

input  → must be in (-1, 1)   // not ±1
output → real number (atanh is odd: atanh(-x) = -atanh(x))
check  → atanh(0) = 0

null / missing → null
outside (-1, 1) → pipeline error
UsePrefer
Undo a hyperbolic tangent$atanh
Forward hyperbolic tangent$tanh
Inverse tangent (trig, not hyperbolic)$atan
Approach

How to Use $atanh in MongoDB

Pass a number inside (-1, 1), then keep or round the result as needed.

  1. Choose an expression stage ($addFields or $project).
  2. Ensure the argument is strictly between -1 and 1 (not equal to ±1).
  3. Pass that expression to $atanh.
  4. Optionally wrap with $round for a shorter display value.
PieceRequired?Role
$atanhYesInverse hyperbolic tangent
ExpressionYesNumber in (-1, 1), field, or nested math
$roundNoTrim floating-point noise for reports

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 = atanh(x)
    emit { ..., field: result }
Reference

Cheat Sheet

Keep these facts handy while writing inverse-hyperbolic-tangent expressions.

TopicDetail
TypeAggregation expression (not a find filter)
Syntax{ $atanh: <expression> }
Domain-1 < x < 1 (exclusive)
Odd propertyatanh(-x) = -atanh(x)
Zero checkatanh(0) = 0
Round-trip$tanh({ $atanh: x }) ≈ x
Sample checkatanh(0.5) ≈ 0.5493
Try it

Live Preview

Watch $atanh turn a value into its inverse hyperbolic tangent. Stay inside (-1, 1).

Simulates $atanh (same idea as the mongosh examples below).

Result
x = 0.5
$atanh(x) → 0.549306

{ atanh_value: 0.549306 }
Trace

Worked Walkthrough — atanh(0.5)

Start with a single number 0.5. We want the value y where tanh(y) = 0.5.

Calculation
Document:
  { value: 0.5 }

Goal: find y such that tanh(y) = 0.5

$atanh(0.5) ≈ 0.5493061443340548

Check with hyperbolic tangent:
  tanh(0.5493061443340548) ≈ 0.5 ✓

Also remember:
  atanh(0)   = 0
  atanh(-0.5) ≈ -0.5493   // odd function
  atanh(±1)  → invalid (outside domain)
Code

MongoDB Examples

We use three small numbers inside the domain: 0, 0.5, and -0.5. First we store them, then we compute $atanh, then we round for cleaner output. Run these in mongosh after inserting the sample data once.

Example 1 — Sample Data

Imagine three readings inside (-1, 1): zero, one positive, and one negative. We save each as its own document in a collection named hyperbolic.

mongosh
db.hyperbolic.insertMany([
  { _id: 1, value: 0 },
  { _id: 2, value: 0.5 },
  { _id: 3, value: -0.5 }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps three documents in hyperbolic. Run find() to see them:

mongosh
db.hyperbolic.find().sort({ _id: 1 })

Read those documents like this:

Field in MongoDBValuePlain English
_id1, 2, 3Document id (row number for this lesson)
value0, 0.5, -0.5Number we will pass to $atanh
Picture
Three inputs (safe domain smoke tests):

  value:  0    → atanh should be  0
  value:  0.5  → atanh ≈  0.5493
  value: -0.5  → atanh ≈ -0.5493   (mirror of +0.5)

Domain reminder:
  valid:   -1 < x < 1
  invalid: x = ±1 or |x| > 1  → pipeline error

How It Works

  1. Insert once. insertMany adds three documents to hyperbolic.
  2. MongoDB stores fields as written. Each value is just a number: 0, 0.5, or -0.5.
  3. find() shows the same shape. What you inserted is what you get back—ready for $atanh in the next examples.

Example 2 — Basic $atanh

Goal: compute inverse hyperbolic tangent for every stored value.

mongosh
db.hyperbolic.aggregate([
  {
    $addFields: {
      atanh_value: { $atanh: "$value" }
    }
  },
  { $sort: { _id: 1 } }
]);

How It Works

  1. Read each stored value. MongoDB already has 0, 0.5, and -0.5 from Example 1.
  2. Apply inverse hyperbolic tangent. $atanh: "$value" runs on every document.
  3. Check the pattern. Zero stays zero; 0.5 and -0.5 are mirrors (odd function).
  4. Keep all fields. $addFields adds atanh_value next to the original value—nothing is deleted.

Example 3 — Rounded Results

Same inputs, but wrap $atanh with $round for shorter numbers in reports.

mongosh
db.hyperbolic.aggregate([
  {
    $addFields: {
      atanh_rounded: {
        $round: [ { $atanh: "$value" }, 4 ]
      }
    }
  },
  { $sort: { _id: 1 } }
]);

How It Works

  1. Same stored documents. Still using values 0, 0.5, and -0.5 from Example 1.
  2. Same $atanh first. Full precision is computed, then trimmed.
  3. Round to 4 decimals. $round keeps reports readable (0.5493 instead of a long float).
  4. Easy check. Zero stays 0; positive and negative results stay mirrors.

Edge Cases & Pitfalls

Check these before using $atanh in production pipelines.

domain

Stay inside (-1, 1)

±1 and values outside the open interval make the pipeline fail. Validate or clamp before calling $atanh.

name

Do not confuse with $atan

$atan is inverse tangent (trig). $atanh is hyperbolic and requires |x| < 1.

null

Null and missing become null

Missing fields return null, not an error. Handle them before math if nulls are invalid in your data.

ends

Results grow near ±1

As x approaches the ends of the domain, |atanh(x)| grows quickly. That is expected math, not a MongoDB bug.

Analysis

Performance Notes

ApproachCostBest for
$atanh alonePer-document mathSimple inverse hyperbolic tangent fields
$atanh + $roundStill O(docs)Readable report columns
$tanh round-trip checkTwo math opsValidating transforms in tests

Trig and hyperbolic expressions are cheap compared with large sorts or joins. Filter early with $match when only some documents need the transform.

Remember

Key Takeaways

  • Role: inverse hyperbolic tangent of a number in (-1, 1).
  • Domain: -1 < x < 1 — ±1 is invalid.
  • Pair: reverse of $tanh; not the same as $atan.
  • Smoke test: atanh(0) = 0.

One line: $atanh answers “which value has this hyperbolic tangent?”—for inputs strictly between -1 and 1.

Frequently Asked Questions

$atanh returns the inverse hyperbolic tangent (arc hyperbolic tangent) of a number—the value y such that tanh(y) equals that number. Use it inside aggregation expression stages such as $project and $addFields.
The argument must resolve to a number strictly between -1 and 1 (not including ±1). Values outside that open interval make the aggregation fail.
atanh(0) equals 0. That makes zero a handy smoke-test when checking pipeline output.
$atanh returns null when the input is null or the field is missing. If the argument is NaN, $atanh returns NaN.
$atan is inverse tangent (trig, any real input). $atanh is inverse hyperbolic tangent (domain (-1, 1)). Same naming style, different math.
Yes for the math. Think of $atanh as MongoDB’s aggregation version of Math.atanh—run it in the pipeline, not as a standalone find() filter.

Next: $binarySize

Get the size in bytes of a BinData (binary) value in aggregation.

$binarySize tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

MongoDB $atan2 Operator MongoDB $binarySize Operator