Docs Menu

$round (aggregation)

On this page

  • Definition
  • Behavior
  • Example
$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> ] }
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, 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.

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 becomes 20).
  • Rounded numbers can still end in 5 (2.45 becomes 2.5)
  • The rounded value is determined by more than one digit

For further discussion of the 'Round Half to Even' technique, see this article.

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.

  • 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

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 }
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.