Docs Menu
Docs Home
/
MongoDB Manual
/
Aggregation Operations
/
Reference
/
Operators

$toDecimal (aggregation)

On this page

  • Definition
  • Behavior
  • Example

Definition

$toDecimal

Converts a value to a decimal. If the value cannot be converted to a decimal, $toDecimal errors. If the value is null or missing, $toDecimal returns null.

$toDecimal has the following syntax:

{
   $toDecimal: <expression>
}

The $toDecimal takes any valid expression.

The $toDecimal is a shorthand for the following $convert expression:

{ $convert: { input: <expression>, to: "decimal" } }

Tip

See also:

$convert

Behavior

The following table lists the input types that can be converted to a decimal:

Input Type
Behavior

Boolean

Returns Decimal128("0") for false.
Returns Decimal128("1") for true.

Double

Returns double value as a decimal.

Decimal

No-op. Returns the decimal.

Integer

Returns the int value as a decimal.

Long

Returns the long value as a decimal.

String

Returns the numerical value of the string as a decimal.

The string value must be of a base 10 numeric value (e.g. "-5.5", "123456").

You cannot convert a string value of a non-base 10 number (e.g. "0x6400")

Date

Returns the number of milliseconds since the epoch that corresponds to the date value.

The following table lists some conversion to decimal examples:

Example
Results

{$toDecimal: true}

Decimal128("1")

{$toDecimal: false}

Decimal128("0")

{$toDecimal: 2.5}

Decimal128("2.50000000000000")

{$toDecimal: NumberInt(5)}

Decimal128("5")

{$toDecimal: NumberLong(10000)}

Decimal128("10000")

{$toDecimal: "-5.5"}

Decimal128("-5.5")

{$toDecimal: ISODate("2018-03-27T05:04:47.890Z")}

Decimal128("1522127087890")

Example

Create a collection orders with the following documents:

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: NumberDecimal("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds",  qty: 5, price: 5 }
] )

The following aggregation operation on the orders collection converts the price to a decimal and the qty to an integer before calculating the total price:

// Define stage to add convertedPrice and convertedQty fields with the converted price and qty values
priceQtyConversionStage = {
   $addFields: {
      convertedPrice: { $toDecimal: "$price" },
      convertedQty: { $toInt: "$qty" },
   }
};
// Define stage to calculate total price by multiplying convertedPrice and convertedQty fields
totalPriceCalculationStage = {
   $project: { item: 1, totalPrice: { $multiply: [ "$convertedPrice", "$convertedQty" ] } }
};
db.orders.aggregate( [
   priceQtyConversionStage,
   totalPriceCalculationStage
] )

The operation returns the following documents:

{ _id: 1, item: 'apple', totalPrice: Decimal128("50") },
{ _id: 2, item: 'pie', totalPrice: Decimal128("200.0") },
{ _id: 3, item: 'ice cream', totalPrice: Decimal128("9.98") },
{ _id: 4, item: 'almonds', totalPrice: Decimal128("25") }

Note

If the conversion operation encounters an error, the aggregation operation stops and throws an error. To override this behavior, use $convert instead.

Back

$toDate

Next

$toDouble