$toDecimal (aggregation)

Definition

  • $toDecimal

New in version 4.0.

Converts a value to a decimal. If the value cannot be convertedto a decimal, $toDecimal errors. If the value is null ormissing, $toDecimal returns null.

$toDecimal has the following syntax:

  1. {
  2.    $toDecimal: <expression>
  3. }

The $toDecimal takes any valid expression.

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

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

See also

$convert

Behavior

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

Input TypeBehavior
BooleanReturns NumberDecimal("0") for false.Returns NumberDecimal("1") for true.
DoubleReturns double value as a decimal.
DecimalNo-op. Returns the decimal.
IntegerReturns the int value as a decimal.
LongReturns the long value as a decimal.
StringReturns the numerical value of the string as a decimal.The string value must be of a base10 numeric value (e.g."-5.5", "123456").You cannot convert a string value of a non-base10number (e.g. "0x6400")
DateReturns the number of milliseconds since the epoch thatcorresponds to the date value.

The following table lists some conversion to decimal examples:

ExampleResults
{$toDecimal: true}NumberDecimal(“1”)
{$toDecimal: false}NumberDecimal(“0”)
{$toDecimal: 2.5}NumberDecimal(“2.50000000000000”)
{$toDecimal: NumberInt(5)}NumberDecimal(“5”)
{$toDecimal: NumberLong(10000)}NumberDecimal(“10000”)
{$toDecimal: "-5.5"}NumberDecimal(“-5.5”)
{$toDecimal: ISODate("2018-03-27T05:04:47.890Z")}NumberDecimal(“1522127087890”)

Example

Create a collection orders with the following documents:

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

The following aggregation operation on the orders collectionconverts the price to a decimal and the qty to an integerbefore calculating the total price:

  1. // Define stage to add convertedPrice and convertedQty fields with the converted price and qty values
  2.  
  3. priceQtyConversionStage = {
  4.    $addFields: {
  5.       convertedPrice: { $toDecimal: "$price" },
  6.       convertedQty: { $toInt: "$qty" },
  7.    }
  8. };
  9.  
  10. // Define stage to calculate total price by multiplying convertedPrice and convertedQty fields
  11.  
  12.  
  13. totalPriceCalculationStage = {
  14.    $project: { item: 1, totalPrice: { $multiply: [ "$convertedPrice", "$convertedQty" ] } }
  15. };
  16.  
  17. db.orders.aggregate( [
  18.    priceQtyConversionStage,
  19.    totalPriceCalculationStage
  20. ])

The operation returns the following documents:

  1. { "_id" : 1, "item" : "apple", "totalPrice" : NumberDecimal("50.0000000000000") }
  2. { "_id" : 2, "item" : "pie", "totalPrice" : NumberDecimal("200.0") }
  3. { "_id" : 3, "item" : "ice cream", "totalPrice" : NumberDecimal("9.98") }
  4. { "_id" : 4, "item" : "almonds", "totalPrice" : NumberDecimal("25.00000000000000") }

Note

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