> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 舍入函数文档

# 舍入函数

<Note>
  以下文档根据 `system.functions` 系统表生成
</Note>

{/*AUTOGENERATED_START*/}

<div id="ceil">
  ## ceil
</div>

引入版本：v1.1.0

与 [`floor`](#floor) 类似，但返回大于或等于 `x` 的最小舍入值。
如果舍入导致溢出 (例如 `ceiling(255, -1)`) ，则结果未定义。

**语法**

```sql theme={null}
ceiling(x[, N])
```

**别名**: `ceiling`

**参数**

* `x` — 要进行舍入的值。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `N` — 可选。要舍入到的小数位数。默认为 0，即舍入为整数。可以为负数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回与 `x` 类型相同的舍入结果。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT ceiling(123.45, 1) AS rounded
```

```response title=Response theme={null}
┌─rounded─┐
│   123.5 │
└─────────┘
```

**负数精度**

```sql title=Query theme={null}
SELECT ceiling(123.45, -1)
```

```response title=Response theme={null}
┌─ceiling(123.45, -1)─┐
│                 130 │
└─────────────────────┘
```

<div id="floor">
  ## floor
</div>

引入版本：v1.1.0

返回小于或等于 `x` 的最大舍入值，其中该值是 `1 / 10 * N` 的倍数；如果 `1 / 10 * N` 无法精确表示，则返回相应数据类型中最接近的数值。

对于整数参数，可使用负数 `N` 进行舍入。
当 `N` 为非负数时，函数返回 `x`。

如果舍入导致溢出 (例如 `floor(-128, -1)`) ，则结果未定义。

**语法**

```sql theme={null}
floor(x[, N])
```

**参数**

* `x` — 要进行舍入的值。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `N` — 可选。要舍入到的小数位数。默认为 0，表示舍入到整数。可以为负数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回与 `x` 类型相同的舍入结果。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT floor(123.45, 1) AS rounded
```

```response title=Response theme={null}
┌─rounded─┐
│   123.4 │
└─────────┘
```

**精度为负**

```sql title=Query theme={null}
SELECT floor(123.45, -1)
```

```response title=Response theme={null}
┌─floor(123.45, -1)─┐
│               120 │
└───────────────────┘
```

<div id="round">
  ## round
</div>

Introduced in: v1.1.0

将一个值舍入到指定的小数位数 `N`。

* 如果 `N > 0`，函数会舍入到小数点右侧。
* 如果 `N < 0`，函数会舍入到小数点左侧。
* 如果 `N = 0`，函数会舍入为最接近的整数。

该函数返回指定数量级上最接近的数值。
如果输入值与两个相邻数的距离相等，则对于 `Float*` 输入，函数使用银行家舍入法；对于其他数值类型 (`Decimal*`) ，则按远离零的方向舍入。

如果舍入导致溢出 (例如 `round(255, -1)`) ，则结果未定义。

**Syntax**

```sql theme={null}
round(x[, N])
```

**参数**

* `x` — 要进行舍入的数值。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `N` — 可选。要保留的小数位数。默认为 `0`。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回与 `x` 类型相同的舍入结果。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**示例**

**Float 类型输入**

```sql title=Query theme={null}
SELECT number / 2 AS x, round(x) FROM system.numbers LIMIT 3;
```

```response title=Response theme={null}
┌───x─┬─round(x)─┐
│   0 │        0 │
│ 0.5 │        0 │
│   1 │        1 │
└─────┴──────────┘
```

**Decimal 类型输入**

```sql title=Query theme={null}
SELECT cast(number / 2 AS  Decimal(10,4)) AS x, round(x) FROM system.numbers LIMIT 3;
```

```response title=Response theme={null}
┌───x─┬─round(x)─┐
│   0 │        0 │
│ 0.5 │        1 │
│   1 │        1 │
└─────┴──────────┘
```

<div id="roundAge">
  ## roundAge
</div>

引入版本：v1.1.0

接受一个表示人类年龄的数值，将其与标准年龄区间进行比较，并返回该数值所在区间的上限值或下限值。

* 对于 `age < 1`，返回 `0`。
* 对于 `1 ≤ age ≤ 17`，返回 `17`。
* 对于 `18 ≤ age ≤ 24`，返回 `18`。
* 对于 `25 ≤ age ≤ 34`，返回 `25`。
* 对于 `35 ≤ age ≤ 44`，返回 `35`。
* 对于 `45 ≤ age ≤ 54`，返回 `45`。
* 对于 `age ≥ 55`，返回 `55`。

**语法**

```sql theme={null}
roundAge(num)
```

**参数**

* `age` — 表示年龄 (以年为单位) 的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 `age` 所在区间的上限或下限年龄。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT *, roundAge(*) FROM system.numbers WHERE number IN (0, 5, 20, 31, 37, 54, 72);
```

```response title=Response theme={null}
┌─number─┬─roundAge(number)─┐
│      0 │                0 │
│      5 │               17 │
│     20 │               18 │
│     31 │               25 │
│     37 │               35 │
│     54 │               45 │
│     72 │               55 │
└────────┴──────────────────┘
```

<div id="roundBankers">
  ## roundBankers
</div>

引入版本：v20.1.0

将数字舍入到指定的小数位 `N`。
如果待舍入的数字恰好位于两个数的中间，函数会使用一种称为银行家舍入法 (banker's rounding) 的舍入方法，这是 IEEE 754 为浮点数定义的默认舍入方式。

* 如果 `N > 0`，函数会舍入到小数点右侧
* 如果 `N < 0`，函数会舍入到小数点左侧
* 如果 `N = 0`，函数会舍入为整数

<Info>
  **注意**

  * 当待舍入的数字恰好位于两个数的中间时，会在指定的小数位上舍入到最接近的偶数。
    例如：`3.5` 向上舍入为 `4`，`2.5` 向下舍入为 `2`。
  * `round` 函数对浮点数采用相同的舍入方式。
  * `roundBankers` 函数也会以相同方式对整数进行舍入，例如 `roundBankers(45, -1) = 40`。
  * 在其他情况下，函数会将数字舍入到最接近的整数。
</Info>

<Tip>
  **对数字求和或相减时使用银行家舍入法**

  使用银行家舍入法，可以减少数字舍入对这些数字求和或相减结果的影响。

  例如，对数字 `1.5, 2.5, 3.5, 4.5` 使用不同的舍入方式求和：

  * 不舍入：`1.5 + 2.5 + 3.5 + 4.5 = 12`。
  * 银行家舍入法：`2 + 2 + 4 + 4 = 12`。
  * 舍入到最接近的整数：`2 + 3 + 4 + 5 = 14`。
</Tip>

**语法**

```sql theme={null}
roundBankers(x[, N])
```

**参数**

* `x` — 要进行舍入的数字。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`Float*`](/zh/reference/data-types/float)
* `[, N]` — 可选。要保留的小数位数。默认为 `0`。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回按银行家舍入法处理后的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT number / 2 AS x, roundBankers(x, 0) AS b FROM system.numbers LIMIT 10
```

```response title=Response theme={null}
┌───x─┬─b─┐
│   0 │ 0 │
│ 0.5 │ 0 │
│   1 │ 1 │
│ 1.5 │ 2 │
│   2 │ 2 │
│ 2.5 │ 2 │
│   3 │ 3 │
│ 3.5 │ 4 │
│   4 │ 4 │
│ 4.5 │ 4 │
└─────┴───┘
```

<div id="roundDown">
  ## roundDown
</div>

引入版本：v20.1.0

将一个数向下舍入到指定数组中的某个元素。
如果该值小于下限，则返回下限。

**语法**

```sql theme={null}
roundDown(num, arr)
```

**参数**

* `num` — 要向下舍入的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`Float*`](/zh/reference/data-types/float)
* `arr` — 用于将 `num` 向下舍入到其中某个元素的数组。[`Array((U)Int*)`](/zh/reference/data-types/array) 或 [`Array(Float*)`](/zh/reference/data-types/array)

**返回值**

返回向下舍入到 `arr` 中某个元素的数值。如果该值小于最小界限，则返回最小界限。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT *, roundDown(*, [3, 4, 5]) FROM system.numbers WHERE number IN (0, 1, 2, 3, 4, 5)
```

```response title=Response theme={null}
┌─number─┬─roundDown(number, [3, 4, 5])─┐
│      0 │                            3 │
│      1 │                            3 │
│      2 │                            3 │
│      3 │                            3 │
│      4 │                            4 │
│      5 │                            5 │
└────────┴──────────────────────────────┘
```

<div id="roundDuration">
  ## roundDuration
</div>

引入版本：v1.1.0

将一个数向下舍入到最接近的常用耗时值之一：`1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000`。
如果该数小于 1，则返回 `0`。

**语法**

```sql theme={null}
roundDuration(num)
```

**参数**

* `num` — 要舍入到常见耗时集合中的某个数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

当 `num` \< 1 时，返回 `0`。否则，返回以下值之一：`1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000`。[`UInt16`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT *, roundDuration(*) FROM system.numbers WHERE number IN (0, 9, 19, 47, 101, 149, 205, 271, 421, 789, 1423, 2345, 4567, 9876, 24680, 42573)
```

```response title=Response theme={null}
┌─number─┬─roundDuration(number)─┐
│      0 │                     0 │
│      9 │                     1 │
│     19 │                    10 │
│     47 │                    30 │
│    101 │                    60 │
│    149 │                   120 │
│    205 │                   180 │
│    271 │                   240 │
│    421 │                   300 │
│    789 │                   600 │
│   1423 │                  1200 │
│   2345 │                  1800 │
│   4567 │                  3600 │
│   9876 │                  7200 │
│  24680 │                 18000 │
│  42573 │                 36000 │
└────────┴───────────────────────┘
```

<div id="roundToExp2">
  ## roundToExp2
</div>

引入版本：v1.1.0

将一个数向下舍入为最接近的 2 的幂 (非负整数) 。
如果该数小于 1，则返回 `0`。

**语法**

```sql theme={null}
roundToExp2(num)
```

**参数**

* `num` — 要舍入的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回将 `num` 向下舍入为最接近的二的 (非负整数) 幂后的结果；如果 `num < 1`，则返回 `0`。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT *, roundToExp2(*) FROM system.numbers WHERE number IN (0, 2, 5, 10, 19, 50)
```

```response title=Response theme={null}
┌─number─┬─roundToExp2(number)─┐
│      0 │                   0 │
│      2 │                   2 │
│      5 │                   4 │
│     10 │                   8 │
│     19 │                  16 │
│     50 │                  32 │
└────────┴─────────────────────┘
```

<div id="trunc">
  ## trunc
</div>

引入版本：v1.1.0

与 [`floor`](#floor) 类似，但返回绝对值不大于 `x` 且绝对值最大的舍入值。

**语法**

```sql theme={null}
truncate(x[, N])
```

**别名**: `truncate`

**参数**

* `x` — 要进行舍入的值。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `N` — 可选。要舍入到的小数位数。默认为 0，表示舍入到整数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回与 `x` 类型相同的舍入结果。[`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT truncate(123.499, 1) AS res;
```

```response title=Response theme={null}
┌───res─┐
│ 123.4 │
└───────┘
```