> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $toDecimal (expression operator)

## Definition

Converts a value to a decimal. If the value cannot be converted to a decimal, [`$toDecimal`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todecimal.md#mongodb-expression-exp.-toDecimal) errors. If the value is null or missing, [`$toDecimal`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todecimal.md#mongodb-expression-exp.-toDecimal) returns null.

[`$toDecimal`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todecimal.md#mongodb-expression-exp.-toDecimal) has the following syntax:

```javascript
{
   $toDecimal: <expression>
}
```

The [`$toDecimal`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todecimal.md#mongodb-expression-exp.-toDecimal) takes any valid [expression.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

The [`$toDecimal`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/todecimal.md#mongodb-expression-exp.-toDecimal) is a shorthand for the following [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) expression:

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

**See also:**

[`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-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. |

**See also:**

To convert strings in bases other than `10`, use [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) with the `base` option.

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: Int32(5)}` | Decimal128("5") |
| `{$toDecimal: Long(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:

```javascript
db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("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:

```javascript
// 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:

```javascript
{ _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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) instead.