$round (aggregation)
On this page
Definition
$round
$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]
returns1235
.
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
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
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
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 }