- Reference >
- Operators >
- Aggregation Pipeline Operators >
- $round (aggregation)
$round (aggregation)¶
On this page
Definition¶
-
$round
¶ New in version 4.2.
$round
rounds a number to to a whole integer or to a specified decimal place.$round
has the following syntax: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
, orlong
.$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 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¶
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
becomes20
). - Rounded numbers can still end in 5 (
2.45
becomes2.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
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:
The following aggregation returns
value
rounded to the first decimal place:The operation returns the following results:
The following aggregation returns
value
rounded using the first digit to the left of the decimal:The operation returns the following results:
The following aggregation returns
value
rounded to the whole integer:The operation returns the following results: