$round (aggregation)

Definition

• $round

New in version 4.2..

$round rounds a number to to a whole integer or to aspecified decimal place.

$round has the following syntax:

{ $round : [ <number>, <place> ] }

FieldTypeDescription<number>numberCan be any valid expressionthat resolves to a number. Specifically, the expression mustresolve to an integer, double,decimal, orlong.

$round returns an error if the expressionresolves to a non-numeric data type.<place>integerOptional Can be any validexpression that resolves toan 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> decimalplaces.

For example, $round : [1234.5678, 2] rounds to twodecimal 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 the2nd digit to the left of the decimal (3) and returns1200.

If the absolute value of <place> equals or exceeds thenumber of digits to the left of the decimal,$round returns 0.

For example, $round : [ 1234.5678, -4] specifies thefourth digit to the left of the decimal. This equals thenumber of digits left of the decimal and returns 0.

• If <place> resolves to 0, $roundrounds using the first digit to the right of the decimal andreturns 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 thenearest even value. For example, consider the following sampledocuments:

{_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 values11.5 and 12.5 are closest to the even value 12. Rounding tothe nearest even value supports more even distribution of rounded datathan 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 orvalue.

If rounding to a whole integer value, $round returnsthe value as an integer.

null, NaN, and +/- Infinity

• If the first argument resolves to a value of null orrefers to a field that is missing, $round returnsnull.
• If the first argument resolves to NaN, $roundreturns NaN.
• If the first argument resolves to negative or positive infinity,$round returns negative or positive infinityrespectively.

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 thefirst 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 valuerounded 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 thewhole 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 }