The $toDecimal operator converts values to Decimal128 in MongoDB aggregation pipelines. Use it for financial data, currency calculations, and any scenario where floating-point rounding errors are unacceptable.
High-precision type.
One expression.
No float rounding.
Parse price fields.
Finance, e-commerce.
Exact vs floating.
In MongoDB’s aggregation framework, the $toDecimal operator converts an expression to a BSON Decimal128 value. Standard doubles use binary floating point, which can produce surprising results — for example, 0.1 + 0.2 may not equal exactly 0.3. Decimal128 stores numbers as exact decimal values, making it the right choice for money, tax calculations, and accounting reports.
$toDecimal is shorthand for { $convert: { input: <expression>, to: "decimal" } }. It is part of the type-conversion family alongside $toInt, $toDouble, and $toString.
Use $toDecimal when working with currency. For general scientific or statistical math where tiny rounding differences are acceptable, $toDouble is often sufficient and slightly faster.
The $toDecimal operator takes one expression:
{ $toDecimal: <expression> }{ $toDecimal: "29.99" }
// Result: Decimal128("29.99")
{ $toDecimal: 100 }
// Result: Decimal128("100")
{ $toDecimal: "$price" }
// Convert the price field
{ $toDecimal: { $multiply: [ "$qty", "$unitPrice" ] } }
// Convert a computed expressionnull — returns null.true becomes 1, false becomes 0.$project, $addFields, $set, or $group.$toDecimal for money; use $toDouble for general numeric work| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (type conversion) |
| Syntax | { $toDecimal: <expression> } |
| Output type | Decimal128 |
| Equivalent | { $convert: { input: <expr>, to: "decimal" } } |
| Best for | Currency, tax, accounting precision |
| Common stages | $project, $addFields, $group |
{
$toDecimal: "$price"
}Parse price text
{
$toDecimal: "19.99"
}Fixed decimal
{
$sum: {
$toDecimal: "$amount"
}
}Precise totals
{
$multiply: [
{ $toDecimal: "$qty" },
{ $toDecimal: "$rate" }
]
}Exact math
Convert string prices to Decimal128, compute line totals with precision, and sum order amounts without floating-point rounding errors.
Start with an orders collection where prices are stored as strings and convert them with $toDecimal.
Suppose you have an orders collection with string prices from a CSV import:
[
{
"_id": 1,
"product": "Widget A",
"price": "29.99",
"quantity": 2
},
{
"_id": 2,
"product": "Widget B",
"price": "15.50",
"quantity": 3
},
{
"_id": 3,
"product": "Widget C",
"price": "0.10",
"quantity": 10
}
]Parse the price string into a precise decimal value:
db.orders.aggregate([
{
$project: {
product: 1,
price: 1,
unitPrice: { $toDecimal: "$price" }
}
}
])$toDecimal parses numeric strings into Decimal128. The value is stored as an exact decimal, not a binary approximation.
Compute line totals and order sums with precise decimal arithmetic.
Multiply quantity by unit price using decimal values:
db.orders.aggregate([
{
$project: {
product: 1,
quantity: 1,
lineTotal: {
$multiply: [
{ $toDecimal: "$price" },
{ $toDecimal: "$quantity" }
]
}
}
}
])
// Widget A: 29.99 × 2 = 59.98 (exact)
// Widget C: 0.10 × 10 = 1.00 (exact)Converting both operands to Decimal128 before $multiply ensures the result is exact. With doubles, small values like 0.10 can accumulate rounding errors over many calculations.
Aggregate precise decimal amounts across all orders:
db.orders.aggregate([
{
$group: {
_id: null,
grandTotal: {
$sum: {
$multiply: [
{ $toDecimal: "$price" },
{ $toDecimal: "$quantity" }
]
}
}
}
}
])
// grandTotal: Decimal128("107.48") — exact sum$sum over Decimal128 values produces an exact total. This is critical for financial reports where penny-level accuracy matters.
Calculate tax on a subtotal without floating-point drift:
db.orders.aggregate([
{
$project: {
product: 1,
subtotal: {
$multiply: [
{ $toDecimal: "$price" },
{ $toDecimal: "$quantity" }
]
}
}
},
{
$addFields: {
tax: {
$multiply: [
"$subtotal",
{ $toDecimal: "0.0825" }
]
}
}
},
{
$addFields: {
total: { $add: [ "$subtotal", "$tax" ] }
}
}
])Tax rates like 8.25% (0.0825) are stored and multiplied as exact decimals. The final total is subtotal plus tax with no rounding surprises.
Compare decimal precision with a classic floating-point example:
db.test.aggregate([
{
$project: {
asDouble: {
$add: [
{ $toDouble: "0.1" },
{ $toDouble: "0.2" }
]
},
asDecimal: {
$add: [
{ $toDecimal: "0.1" },
{ $toDecimal: "0.2" }
]
}
}
}
])
// asDouble: 0.30000000000000004 (floating-point error)
// asDecimal: Decimal128("0.3") (exact)Binary floats cannot represent some decimal fractions exactly. Decimal128 stores the value as written, which is why financial apps prefer it.
When price strings may be invalid, use $convert with onError:
db.orders.aggregate([
{
$project: {
product: 1,
unitPrice: {
$convert: {
input: "$price",
to: "decimal",
onError: { $toDecimal: "0" },
onNull: { $toDecimal: "0" }
}
}
}
}
])
// "29.99" → Decimal128("29.99")
// "N/A" → Decimal128("0") (fallback)
// null/missing → Decimal128("0")$toDecimal errors on invalid strings. $convert with onError lets the pipeline continue with a safe default.
$toDecimal WorksThe input resolves from a field path, numeric string, number, or nested expression.
Strings and numbers are converted to exact decimal representation with up to 34 significant digits.
The Decimal128 value supports exact $add, $multiply, $sum, and comparisons.
Use for totals, tax, and reports where every cent must be correct.
The $toDecimal operator converts values to Decimal128 for high-precision decimal arithmetic in MongoDB aggregation pipelines. It is the right choice for currency, tax, and any calculation where floating-point rounding errors are unacceptable.
For general numeric work where tiny rounding differences are fine, consider $toDouble instead. For conversions with error handling, use $convert. Next in the series: $toDouble.
$toDecimal for all currency and financial calculations$multiply or $add$convert with onError for messy imported price data0.10, large totals, and zero values$toDouble for money when penny accuracy is required$toDecimal$toDecimalUse these points when working with precise decimal values in MongoDB.
Exact decimals.
PurposeOne argument.
Syntax0.1 + 0.2 = 0.3.
PrecisionPrices, tax, sums.
UsageExact vs float.
CompareMove on to $toDouble for floating-point conversion, or review $convert for flexible type transforms.
5 people found this page helpful