Docs Home → MongoDB Manual

$round (aggregation)

On this page本页内容

Definition定义

$round

New in version 4.2. 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>numberCan 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. 如果表达式解析为非数字数据类型，则返回错误。
<place>integerOptional. 可选的。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. 可以是解析为介于-20和100之间的整数的任何有效表达式。例如-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>解析为负整数，则$round使用小数点左侧的数字<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. 例如，$round : [ 1234.5678, -4]指定小数点左侧的第四位。This equals the number of digits left of the decimal and returns 0.这等于小数点的剩余位数，并返回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. 当值为5时，$round四舍五入到最接近的偶数。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. 值10.5最接近于偶数值10，而值11.5和12.5最接近于偶值12。Rounding to the nearest even value supports more even distribution of rounded data than 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 or value.如果四舍五入到特定的小数点，则$round返回的数据类型与输入表达式或值的数据类型匹配。

If rounding to a whole integer value, $round returns the value as an integer.如果四舍五入为整数值，$round会将该值作为整数返回。

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 }