Docs Home → Develop Applications → MongoDB Manual

# $round (aggregation)

On this page

## 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 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.

### 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 }