# $round (aggregation)¶

## Definition¶

`$round`

¶*New in version 4.2.*.`$round`

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

has the following syntax:{ $round : [ <number>, <place> ] } FieldTypeDescription`<number>`

numberCan 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`1234`

.

## Behavior¶

### Rounding Numbers Ending in 5¶

To minimize the skew errors that are caused by always rounding upwards, numbers ending in 5 are rounded to the nearest even value. This is the IEEE standard for floating point numbers and also works well operations across sequences.

For example, consider this chart:

Original | Rounded 1 | Rounded 0 | Rounded -1 |
---|---|---|---|

124.5 | 124.5 | 124 | 120 |

125.5 | 125.5 | 126 | 130 |

25 | 25 | 25 | 20 |

12.5 | 12.5 | 12 | 10 |

2.25 | 2.2 | 2 | 0 |

2.45 | 2.5 | 2 | 0 |

The chart highlights a few points.

- The
`$round`

function is not limited to floats. (`25`

becomes`20`

). - Rounded numbers can still end in 5 (
`2.45`

becomes`2.5`

) - The rounded value is determined by more than one digit

For further discussion of the 'Round Half to Even' technique, see this article.

### Returned Data Type¶

If rounding to a specific decimal place, the data type returned by
`$round`

matches the data type of the input expression or
value.

If rounding to a whole integer value, `$round`

returns
the value as an integer.

`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¶

A collection named `samples`

contains the following documents:

{ _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 }