/ /

/ /

$round (aggregation)

Definition

$round

$round rounds a number to a whole integer or to a specified decimal place.

$round has the following syntax:

{ $round : [ <number>, <place> ] }

Field	Type	Description
`<number>`	number	Can be any valid expression that resolves to a number. Specifically, the expression must resolve to an integer, double, `decimal`, or `long`. `$round` returns an error if the expression resolves to a non-numeric data type.
`<place>`	integer	Optional Can be any valid expression that resolves to an integer between -20 and 100, exclusive. e.g. `-20 < place < 100`. Defaults to `0` if unspecified. If `<place>` resolves to a positive integer, `$round` rounds to `<place>` decimal places. For example, `$round : [1234.5678, 2]` rounds to two decimal places and returns `1234.57`. If `<place>` resolves to a negative integer, `$round` rounds using the digit `<place>` to the left of the decimal. For example, `$round : [1234.5678, -2]` uses the 2nd digit to the left of the decimal (`3`) and returns `1200`. If the absolute value of `<place>` equals or exceeds the number of digits to the left of the decimal, `$round` returns `0`. For example, `$round : [ 1234.5678, -4]` specifies the fourth digit to the left of the decimal. This equals the number of digits left of the decimal and returns `0`. If `<place>` resolves to `0`, `$round` rounds using the first digit to the right of the decimal and returns rounded integer value. For example, `$round : [1234.5678, 0]` returns `1235`.

Behavior

Rounding to Even Values

When rounding on a value of 5, $round rounds to the nearest even value. For example, consider the following sample documents:

{_id : 1, "value" : 10.5},
{_id : 2, "value" : 11.5},
{_id : 3, "value" : 12.5},
{_id : 4, "value" : 13.5}

$round : [ "$value", 0] returns the following:

{_id : 1, "value" : 10},
{_id : 2, "value" : 12},
{_id : 3, "value" : 12},
{_id : 4, "value" : 14}

The value 10.5 is closest to the even value 10, while the values 11.5 and 12.5 are closest to the even value 12. Rounding to the nearest even value supports more even distribution of rounded data than always rounding up or down.

Rounding Precision with Floating Point Numbers

If you print a double-precision floating point number 0.05 with 20 digits after the decimal separator, you will see 0.05000000000000000278, which is slightly greater than 0.05 and is rounded to 0.1.

MongoDB uses the IEEE 754 standard for floating point computations, and the behavior is consistent with that standard.

If you need a floating point number for an application that requires high precison, consider a Decimal128 value. For details, see BSON.Decimal128.

If you need to store a currency value, consider an integer using the lowest currency denomination unit. For example, use an integer with cents or pennies instead of a floating point number.

Returned Data Type

The returned data type matches the data type of the input expression or value.

`null`, `NaN`, and `+/- Infinity`

If the first argument resolves to a value of null or refers to a field that is missing, $round returns null.
If the first argument resolves to NaN, $round returns NaN.
If the first argument resolves to negative or positive infinity, $round returns negative or positive infinity respectively.

Example	Results
`{ $round: [ NaN, 1] }`	`NaN`
`{ $round: [ null, 1] }`	`null`
`{ $round : [ Infinity, 1 ] }`	`Infinity`
`{ $round : [ -Infinity, 1 ] }`	`-Infinity`

Example

Create a collection named samples with the following documents:

db.samples.insertMany(
   [
     { _id: 1, value: 19.25 },
     { _id: 2, value: 28.73 },
     { _id: 3, value: 34.32 },
     { _id: 4, value: -45.39 }
   ]
)

The following aggregation returns value rounded to the first decimal place:
```
db.samples.aggregate([
   { $project: { roundedValue: { $round: [ "$value", 1 ] } } }
])
```
The operation returns the following results:
```
{ "_id" : 1, "roundedValue" : 19.2 }
{ "_id" : 2, "roundedValue" : 28.7 }
{ "_id" : 3, "roundedValue" : 34.3 }
{ "_id" : 4, "roundedValue" : -45.4 }
```
The following aggregation returns value rounded using the first digit to the left of the decimal:
```
db.samples.aggregate([
   { $project: { roundedValue: { $round: [ "$value", -1 ] } } }
])
```
The operation returns the following results:
```
{ "_id" : 1, "roundedValue" : 10 }
{ "_id" : 2, "roundedValue" : 20 }
{ "_id" : 3, "roundedValue" : 30 }
{ "_id" : 4, "roundedValue" : -50 }
```
The following aggregation returns value rounded to the whole integer:
```
db.samples.aggregate([
   { $project: { roundedValue: { $round: [ "$value", 0 ] } } }
])
```
The operation returns the following results:
```
{ "_id" : 1, "roundedValue" : 19 }
{ "_id" : 2, "roundedValue" : 29 }
{ "_id" : 3, "roundedValue" : 34 }
{ "_id" : 4, "roundedValue" : -45 }
```

Back

$reverseArray

$rtrim

Definition

Behavior

Rounding to Even Values

Rounding Precision with Floating Point Numbers

Returned Data Type

null, NaN, and +/- Infinity

Example

`null`, `NaN`, and `+/- Infinity`