Docs Home → Develop Applications → MongoDB Manual
$round (aggregation)![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
$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
, orlong
.$round
returns an error if the expression resolves to a non-numeric data type.<place>
integerOptional Can be any valid expression that resolves to an integer between -20 and 100, exclusive. e.g.
-20 < place < 100
. Defaults to0
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 returns1234.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 returns1200
.If the absolute value of
<place>
equals or exceeds the number of digits to the left of the decimal,$round
returns0
.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 returns0
.If
<place>
resolves to0
,$round
rounds using the first digit to the right of the decimal and returns rounded integer value.For example,
$round : [1234.5678, 0]
returns1234
.
Behavior![](/docs/v5.2/assets/link.svg)
Rounding to Even Values![](/docs/v5.2/assets/link.svg)
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![](/docs/v5.2/assets/link.svg)
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
![](/docs/v5.2/assets/link.svg)
If the first argument resolves to a value of
null
or refers to a field that is missing,$round
returnsnull
.If the first argument resolves to
NaN
,$round
returnsNaN
.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![](/docs/v5.2/assets/link.svg)
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 }