Database Manual / Reference / Query Language / Expressions

$round (aggregation)（聚合）

Definition定义

$round

$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.具体来说，表达式必须解析为integer、double、decimal或long。

$round returns an error if the expression resolves to a non-numeric data type.如果表达式解析为非数值数据类型，则$round返回错误。

<place>integer整数

Optional Can be any valid expression that resolves to an integer between -20 and 100, exclusive. 可选可以是解析为-20到100之间的整数的任何有效表达式，不包括-20和100在内。e.g. -20 < place < 100. Defaults to 0 if unspecified.例如-20 < place < 100。如果未指定，则默认为0。

  • If <place> resolves to a positive integer, $round rounds to <place> decimal places.如果<place>解析为正整数，则$round四舍五入到<place>小数位。

    For example, $round : [1234.5678, 2] rounds to two decimal places and returns 1234.57.例如，$round: [1234.5678, 2]四舍五入到小数点后两位，返回1234.57。

  • If <place> resolves to a negative integer, $round rounds using the digit <place> to the left of the decimal.如果<place>解析为负整数，则使用小数点左侧的数字<place>进行四舍五入。

    For example, $round : [1234.5678, -2] uses the 2nd digit to the left of the decimal (3) and returns 1200.例如，$round : [1234.5678, -2]使用小数点（3）左侧的第二位数字，返回1200。

    If the absolute value of <place> equals or exceeds the number of digits to the left of the decimal, $round returns 0.如果<place>的绝对值等于或超过小数点左侧的位数，$round将返回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.例如，$round : [ 1234.5678, -4]指定小数点左侧的第四位数字。这等于小数点后的位数，并返回0。

  • If <place> resolves to 0, $round rounds using the first digit to the right of the decimal and returns rounded integer value.如果<place>解析为0，则使用$round对小数点右侧的第一位数字进行四舍五入，并返回四舍五进的整数值。

    For example, $round : [1234.5678, 0] returns 1235.例如，$round : [1234.5678, 0]返回1235。

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:当对值5进行四舍五入时，$round四舍五入到最接近的偶数值。例如，考虑以下示例文档：

{_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.数值10.5最接近偶数10，而数值11.5和12.5最接近偶数12。四舍五入到最接近的偶数值比总是向上或向下四舍五舍五入支持更均匀的四舍五进数据分布。

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 returns null.如果第一个参数解析为null值或引用缺少的字段，$round将返回null。
  • If the first argument resolves to NaN, $round returns NaN.如果第一个参数解析为NaN，$round将返回NaN。
  • If the first argument resolves to negative or positive infinity, $round returns negative or positive infinity respectively.如果第一个参数解析为负无穷大或正无穷大，$round将分别返回负无穷大和正无穷大。
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:使用以下文档创建一个名为samples的集合：

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:以下聚合返回四舍五入到第一位小数的value：

    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:以下聚合返回使用小数点左侧第一位数字四舍五入的value：

    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:以下聚合返回四舍五入为整数的value：

    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 }