The $ln operator calculates the natural logarithm of a number in an aggregation expression. It uses base e (Euler’s number, about 2.71828) — the same as Math.log() in JavaScript.
Logarithm base e.
{ $ln: expr }.
Values must be > 0.
ln(1)=0, ln(e)=1.
Growth, science, stats.
Base e vs custom base.
In MongoDB’s aggregation framework, the $ln operator computes the natural logarithm of a numeric expression. For example, ln(1) = 0 and ln(e) ≈ 1. This is useful when working with exponential growth, concentration scales, entropy calculations, or any formula that uses base-e logarithms.
Think of $ln as MongoDB’s pipeline version of JavaScript’s Math.log() — not Math.log10(), which uses base 10.
Natural logarithm answers the question: “To what power must e be raised to get this number?” For example, because e¹ ≈ 2.718, we know ln(2.718) ≈ 1.
The $ln operator takes one numeric expression:
{ $ln: <expression> }// Field reference
{ $ln: "$concentration" }
// Literal number
{ $ln: 10 }
// Nested expression
{ $ln: { $add: [ "$value", 1 ] } }$ln — returns the natural logarithm (base e) of the expression.<expression> — must evaluate to a positive number for a valid result.ln(1) = 0 — the logarithm of 1 is always zero, in any base.null input — returns null.$project, $addFields, or $set.$log instead.ln(1) → 0ln(e) → 1 (where e ≈ 2.71828)ln(10) → ≈ 2.302585$cond if needed| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (math) |
| Syntax | { $ln: <expression> } |
| Base | e (natural logarithm) |
| Valid input | Positive numbers (and null → null) |
| Common stages | $project, $addFields, $set |
{
$ln: 1
}Returns 0
{
$ln: "$value"
}Log of field
{
$ln: 10
}≈ 2.302585
{
$ln: null
}Returns null
Walk through a sample measurements collection and apply $ln to transform positive numeric values step by step.
Start with a measurements collection and compute natural logarithms with $project.
Suppose you have a measurements collection with positive concentration values:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "sample": "A", "concentration": 1 },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "sample": "B", "concentration": 2.718281828 },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "sample": "C", "concentration": 10 }
]Add a logConcentration field using $ln:
db.measurements.aggregate([
{
$project: {
sample: 1,
concentration: 1,
logConcentration: { $ln: "$concentration" }
}
}
])concentration is 1, so ln(1) = 0.concentration is approximately e, so ln(e) ≈ 1.concentration is 10, so ln(10) ≈ 2.302585.Combine $ln with other operators for growth analysis and safe transformations.
When comparing a current value to a baseline, the natural log of the ratio measures proportional change:
db.measurements.aggregate([
{
$project: {
sample: 1,
current: "$concentration",
baseline: 2,
logGrowth: {
$ln: {
$divide: [ "$concentration", 2 ]
}
}
}
}
])ln(current / baseline) expresses relative change on a log scale. Positive values mean growth above the baseline; negative values mean decline. This pattern is common in economics and biology.
Compute natural logarithms for fixed constants in a projection:
db.measurements.aggregate([
{
$project: {
sample: 1,
lnOfOne: { $ln: 1 },
lnOfTen: { $ln: 10 },
lnOfE: { $ln: 2.718281828 }
}
}
])Literal arguments work the same as field references. These three values are handy reference points when learning how natural logarithms behave.
Use $cond to apply $ln only when the input is positive:
db.measurements.aggregate([
{
$project: {
sample: 1,
concentration: 1,
safeLog: {
$cond: [
{ $gt: [ "$concentration", 0 ] },
{ $ln: "$concentration" },
null
]
}
}
}
])Natural logarithm is only defined for positive numbers. If your data might include zero or negative values, check with $gt before calling $ln, and return null or a default when the input is invalid.
Compute ln(a) - ln(b), which equals ln(a/b):
db.measurements.aggregate([
{
$project: {
sample: 1,
logRatio: {
$subtract: [
{ $ln: "$concentration" },
{ $ln: 2 }
]
}
}
}
])This is equivalent to Example 2’s ln(concentration / 2) thanks to the logarithm property: ln(a) - ln(b) = ln(a/b). Choose whichever form reads clearer in your pipeline.
$ln WorksThe expression inside $ln resolves to a number from a field, literal, or nested operator.
If the input is null, $ln returns null without error.
For positive numbers, MongoDB returns logₑ(x) — the power you raise e to in order to get x.
Your pipeline gets the natural logarithm, ready for further math or reporting.
The $ln operator brings natural logarithm calculations into MongoDB aggregation pipelines. Use it when your formulas require base-e logs — the same family as JavaScript’s Math.log().
Remember the domain: input must be positive. Guard with $cond when data quality is uncertain, and reach for $log when you need a custom logarithm base.
$ln$cond to handle zero, negative, or missing valuesln(1) = 0 as a quick sanity check$log when you need base 10 or another custom base$divide for log-ratio growth calculations$ln to zero or negative numbers without guarding$ln (base e) with base-10 logarithm$ln as a pipeline stage — it is an expression operatornull input returns null$lnUse these points when working with natural logarithms in MongoDB.
Base e logarithm.
PurposeKey reference.
MathGuard invalid input.
Domainln(a/b) growth.
PatternCustom base next.
RelatedMove on to $log for logarithms with a custom base, or review $abs for absolute values.
5 people found this page helpful