算术函数 - ClickHouse Documentation

概述

算术函数适用于任意两个类型为 UInt8、UInt16、UInt32、UInt64、Int8、Int16、Int32、Int64、Float32 或 Float64 的操作数。在执行运算之前，两个操作数都会转换为结果类型。结果类型按如下方式确定 (除非下文的函数文档中另有说明) ：

如果两个操作数都不超过 32 位宽，则结果类型的大小将取两者中较大操作数所对应类型之后的下一个更大类型 (整数类型提升) 。例如，UInt8 + UInt16 = UInt32 或 Float32 * Float32 = Float64。
如果其中一个操作数为 64 位或更宽，则结果类型的大小与两个操作数中较大的那个相同。例如，UInt32 + UInt128 = UInt128 或 Float32 * Float64 = Float64。
如果其中一个操作数是有符号类型，则结果类型也将是有符号类型；否则为无符号类型。例如，UInt32 * Int32 = Int64 或 UInt32 * UInt32 = UInt64。

这些规则可确保结果类型是能够表示所有可能结果的最小类型。虽然这会在数值范围边界附近引入溢出的风险，但也能确保计算充分利用 64 位原生整数的最大位宽，以更快的速度执行。这种行为还可保证与许多将 64 位整数 (BIGINT) 作为最大整数类型的其他数据库兼容。示例：

SELECT toTypeName(0), toTypeName(0 + 0), toTypeName(0 + 0 + 0), toTypeName(0 + 0 + 0 + 0)

┌─toTypeName(0)─┬─toTypeName(plus(0, 0))─┬─toTypeName(plus(plus(0, 0), 0))─┬─toTypeName(plus(plus(plus(0, 0), 0), 0))─┐
│ UInt8         │ UInt16                 │ UInt32                          │ UInt64                                   │
└───────────────┴────────────────────────┴─────────────────────────────────┴──────────────────────────────────────────┘

溢出的情况与 C++ 中相同。

abs

引入版本：v1.1.0 计算 x 的绝对值。如果 x 是无符号类型，则不会产生任何影响。如果 x 是有符号类型，则返回无符号数。语法

abs(x)

参数

x — 需要求绝对值的值

返回值 x 的绝对值示例 使用示例

Query

SELECT abs(-0.5)

Response

0.5

avg2

引入版本：v25.11.0 计算并返回所提供参数的平均值。支持数值类型和时间类型。语法

avg2(x1, x2])

参数

x1, x2] — 接受两个用于计算平均值的参数。

返回值 返回所提供参数的平均值，并将结果提升为兼容的最大类型。示例 数值类型

Query

SELECT avg2(toUInt8(3), 1.0) AS result, toTypeName(result) AS type;
-- 返回类型为 Float64，因为 UInt8 必须提升为 64 位才能进行比较。

Response

┌─result─┬─type────┐
│      2 │ Float64 │
└────────┴─────────┘

Decimal 类型

Query

SELECT avg2(toDecimal32(1, 2), 2) AS result, toTypeName(result) AS type;

Response

┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘

日期类型

Query

SELECT avg2(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;

Response

┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘

DateTime 类型

Query

SELECT avg2(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;

Response

┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘

Time64 类型

Query

SELECT avg2(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;

Response

┌───result─┬─type──────┐
│ 13:00:00 │ Time64(0) │
└──────────┴───────────┘

byteSwap

引入版本：v23.10.0 将整数的字节顺序反转，即改变其字节序。下面的示例可按以下方式理解：

将十进制整数转换为对应的大端十六进制格式，即 3351772109 -> C7 C7 FB CD (4 字节)
将字节顺序反转，即 C7 C7 FB CD -> CD FB C7 C7
假定结果为大端格式，将其转换回整数，即 CD FB C7 C7 -> 3455829959 该函数的一个用例是反转 IPv4：

┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
│ 199.199.251.205                                       │
└───────────────────────────────────────────────────────┘

语法

byteSwap(x)

参数

x — 整数值。(U)Int*

返回值 返回字节顺序颠倒后的 x。(U)Int* 示例 使用示例

Query

SELECT byteSwap(3351772109)

Response

3455829959

8 位

Query

SELECT byteSwap(54)

Response

16 位

Query

SELECT byteSwap(4135)

Response

32 位

Query

SELECT byteSwap(3351772109)

Response

3455829959

64 位

Query

SELECT byteSwap(123294967295)

Response

18439412204227788800

divide

引入版本：v1.1.0 计算两个值 a 和 b 的商。结果类型始终为 Float64。整数除法请使用 intDiv 函数。

除数为 0 时，会返回 inf、-inf 或 nan。

语法

divide(x, y)

参数

x — 被除数；y — 除数

返回值 x 与 y 的商示例 两个数相除

Query

SELECT divide(25,5) AS quotient, toTypeName(quotient)

Response

5 Float64

除以零

Query

SELECT divide(25,0)

Response

inf

divideDecimal

Introduced in: v22.12.0 对两个 Decimal 执行除法运算。结果值的类型为 Decimal256。结果标度可通过 result_scale 参数 (取值范围为 [0, 76] 的常量 Integer) 显式指定。若未指定，则结果标度为给定参数中的最大标度。

此函数的执行速度明显慢于常规的 divide。如果你并不需要受控精度和/或需要更快的计算速度，请考虑使用 divide。

语法

divideDecimal(x, y[, result_scale])

参数

x — 第一个值：Decimal。 - y — 第二个值：Decimal。 - result_scale — 结果标度。类型：Int/UInt。

返回值 按给定标度得到的除法结果。Decimal256 示例 示例 1

Query

divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)

Response

┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
│                                                -5.7142857142 │
└──────────────────────────────────────────────────────────────┘

示例 2

Query

SELECT toDecimal64(-12, 1) / toDecimal32(2.1, 1);
SELECT toDecimal64(-12, 1) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);

Response

┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
│                                             -5.7 │
└──────────────────────────────────────────────────┘
┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 5)─┐
│ -12 │ 2.1 │                                                       -5.7 │                                                   -5.71428 │
└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘

divideOrNull

在 v25.5.0 中引入与 divide 相同，但在除数为零时返回 NULL。语法

divideOrNull(x, y)

参数

x — 被除数 - y — 除数

返回值 x 与 y 的商，或 NULL。示例 除以零

Query

SELECT divideOrNull(25, 0)

Response

\N

gcd

引入版本：v1.1.0 返回两个值 a 和 b 的最大公约数。当除数为零，或将最小负数除以负一时，会抛出异常。语法

gcd(x, y)

参数

x — 第一个整数 - y — 第二个整数

返回值 x 和 y 的最大公因数。示例 使用示例

Query

SELECT gcd(12, 18)

Response

ifNotFinite

Introduced in: v20.3.0 检查浮点值是否为有限数。你也可以使用三元运算符获得类似的结果：isFinite(x) ? x : y。语法

ifNotFinite(x,y)

参数

x — 要检查是否为无穷大的值。Float*
y — 备用值。Float*

返回值

如果 x 是有限值，则返回 x。
如果 x 不是有限值，则返回 y。

示例 用法示例

Query

SELECT 1/0 AS infimum, ifNotFinite(infimum,42)

Response

inf  42

intDiv

Introduced in: v1.1.0 对两个值 x 和 y 执行整数除法。也就是说，计算向下取整后的商。结果与被除数 (第一个参数) 的位宽相同。当除以零、商超出被除数的取值范围，或将最小负数除以负一时，会抛出异常。语法

intDiv(x, y)

参数

x — 左操作数。- y — 右操作数。

返回值 x 与 y 整数相除的结果示例 两个浮点数的整数除法

Query

SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)

Response

┌──res─┬─toTypeName(intDiv(toFloat64(1), 0.001))─┐
│ 1000 │ Int64                                   │
└──────┴─────────────────────────────────────────┘

商不在被除数的取值范围内

Query

SELECT
intDiv(1, 0.001) AS res,
toTypeName(res)

Response

Received exception from server (version 23.2.1):
Code: 153. DB::Exception: Received from localhost:9000. DB::Exception:
Cannot perform integer division, because it will produce infinite or too
large number: While processing intDiv(1, 0.001) AS res, toTypeName(res).
(ILLEGAL_DIVISION)

intDivOrNull

引入版本：v25.5.0 与 intDiv 相同，但在除数为零或将最小负数除以负一时返回 NULL。语法

intDivOrNull(x, y)

参数

x — 左操作数。(U)Int*
y — 右操作数。(U)Int*

返回值 x 与 y 做整数除法的结果，或 NULL。示例 被零除的整数除法

Query

SELECT intDivOrNull(1, 0)

Response

\N

最小负数除以 -1

Query

SELECT intDivOrNull(-9223372036854775808, -1)

Response

\N

intDivOrZero

引入版本：v1.1.0 与 intDiv 相同，但在除数为零，或将最小负数除以负一时返回零。语法

intDivOrZero(a, b)

参数

a — 左操作数。(U)Int*
b — 右操作数。(U)Int*

返回值 a 与 b 做整数除法的结果，或为零。示例 整数除以零

Query

SELECT intDivOrZero(1, 0)

Response

最小负数除以 -1

Query

SELECT intDivOrZero(0.05, -1)

Response

isFinite

引入版本：v1.1.0 如果 Float32、Float64 或 BFloat16 参数既不是无穷大也不是 NaN，则返回 1，否则返回 0。语法

isFinite(x)

参数

x — 要检查是否为有限值的数。Float* 或 BFloat16

返回值 如果 x 不是无穷大且不是 NaN，则返回 1；否则返回 0。示例 测试一个数是否为有限值

Query

SELECT isFinite(inf)

Response

isInfinite

Introduced in: v1.1.0 如果 Float32、Float64 或 BFloat16 参数是无穷大，则返回 1；否则返回 0。请注意，参数为 NaN 时也会返回 0。语法

isInfinite(x)

参数

x — 用于检查是否为无穷大的数值。Float* 或 BFloat16

返回值 若 x 为无穷大，则返回 1；否则返回 0 (NaN 也返回 0) 。示例 判断一个数值是否为无穷大

Query

SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10))

Response

1 0 0

isNaN

引入版本：v1.1.0 如果 Float32、Float64 或 BFloat16 类型的参数为 NaN，则返回 1，否则返回 0。语法

isNaN(x)

参数

x — 要检查是否为 NaN 的参数。Float* 或 BFloat16

返回值 如果为 NaN，则返回 1；否则返回 0 示例 使用示例

Query

SELECT isNaN(NaN)

Response

lcm

引入版本：v1.1.0 返回两个值 x 和 y 的最小公倍数。当除以零，或将最小负数除以负一时，会抛出异常。语法

lcm(x, y)

参数

x — 第一个整数。(U)Int*
y — 第二个整数。(U)Int*

返回值 返回 x 和 y 的最小公倍数。(U)Int* 示例 用法示例

Query

SELECT lcm(6, 8)

Response

max2

引入版本：v21.11.0 返回两个数值 x 和 y 中较大的值。语法

max2(x, y)

参数

x — 第一个值 (U)Int8/16/32/64 或 Float* 或 Decimal
y — 第二个值 (U)Int8/16/32/64 或 Float* 或 Decimal

返回值 返回 x 和 y 中的较大值。 Float64 示例 用法示例

Query

SELECT max2(-1, 2)

Response

midpoint

引入版本：v25.11.0 计算并返回给定参数的平均值。支持数值类型和时间类型。语法

midpoint(x1[, x2, ...])

参数

x1[, x2, ...] — 接受单个值或多个值，并对其求平均值。

返回值 返回所提供参数的平均值，结果会提升为兼容的最大类型。示例 数值类型

Query

SELECT midpoint(1, toUInt8(3), 0.5) AS result, toTypeName(result) AS type;
-- 返回类型为 Float64，因为 UInt8 必须提升为 64 位才能进行比较。

Response

┌─result─┬─type────┐
│    1.5 │ Float64 │
└────────┴─────────┘

Decimal 类型

Query

SELECT midpoint(toDecimal32(1.5, 2), toDecimal32(1, 1), 2) AS result, toTypeName(result) AS type;

Response

┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘

日期类型

Query

SELECT midpoint(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;

Response

┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘

DateTime 类型

Query

SELECT midpoint(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;

Response

┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘

Time64 类型

Query

SELECT midpoint(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;

Response

┌───result─┬─type──────┐
│ 13:00:00 │ Time64(0) │
└──────────┴───────────┘

min2

引入版本：v21.11.0 返回两个数值 x 和 y 中较小的一个。语法

min2(x, y)

参数

x — 第一个值 (U)Int8/16/32/64 或 Float* 或 Decimal
y — 第二个值 (U)Int8/16/32/64 或 Float* 或 Decimal

返回值 返回 x 和 y 中较小的值。 Float64 示例 使用示例

Query

SELECT min2(-1, 2)

Response

-1

minus

在 v1.1.0 中引入计算两个值 a 和 b 的差值。结果始终为带符号数。与 plus 类似，也可以用日期或日期时间减去一个整数。此外，也支持两个日期时间相减，结果为它们之间的时间差。语法

minus(x, y)

参数

x — 被减数。 - y — 减数。

返回值 x 与 y 的差示例 两个数相减

Query

SELECT minus(10, 5)

Response

整数和日期相减

Query

SELECT minus(toDate('2025-01-01'),5)

Response

2024-12-27

modulo

Introduced in: v1.1.0 计算两个值 a 除以 b 所得的余数。如果两个输入都是整数，结果类型为整数。如果其中一个输入是浮点数，结果类型则为 Float64。余数的计算方式与 C++ 相同。对于负数，使用截断除法。当除数为零，或将最小负数除以负一时，会抛出异常。 Syntax

modulo(a, b)

别名: mod 参数

a — 被除数 - b — 除数 (模数)

返回值 a % b 的余数示例 使用示例

Query

SELECT modulo(5, 2)

Response

moduloLegacy

引入版本：v1.1.0 计算除法的余数。这是使用 C++ % 运算符的旧版取模实现，对于负参数，可能会产生负结果。保留此函数是为了兼容旧版表分区逻辑。标准行为请使用 modulo 或 positiveModulo。语法

moduloLegacy(a, b)

参数

a — 被除数。(U)Int* 或 Float*
b — 除数。(U)Int* 或 Float*

返回值 返回相除后的余数。(U)Int* 或 Float* 示例 基本用法

Query

SELECT moduloLegacy(10, 3)

Response

moduloOrNull

引入版本：v25.5.0 计算 a 除以 b 的余数。与函数 modulo 类似，不同之处在于当右侧参数为 0 时，moduloOrNull 会返回 NULL。语法

moduloOrNull(x, y)

别名: modOrNull 参数

x — 被除数。(U)Int* 或 Float*
y — 除数 (模数) 。(U)Int* 或 Float*

返回值 返回 x 除以 y 的余数；当除数为零时，返回 NULL。示例 除数为零时的 moduloOrNull

Query

SELECT moduloOrNull(5, 0)

Response

\N

moduloOrZero

首次引入版本：v20.3.0 与 modulo 类似，但当除数为零时会返回零，而不是像 modulo 函数那样抛出异常。语法

moduloOrZero(a, b)

参数

a — 被除数。(U)Int* 或 Float*
b — 除数 (模数) 。(U)Int* 或 Float*

返回值 返回 a % b 的余数；当除数为 0 时，返回 0。示例 使用示例

Query

SELECT moduloOrZero(5, 0)

Response

multiply

引入于：v1.1.0 计算两个值 x 和 y 的乘积。语法

multiply(x, y)

参数

x — 因子。(U)Int* 或 Float* 或 Decimal
y — 因子。(U)Int* 或 Float* 或 Decimal

返回值 返回 x 与 y 的乘积示例 将两个数相乘

Query

SELECT multiply(5,5)

Response

multiplyDecimal

引入版本：v22.12.0 对两个 Decimal 执行乘法。结果值的类型为 Decimal256。结果标度可以通过 result_scale 参数 (取值范围为 [0, 76] 的常量 Integer) 显式指定。若未指定，则结果标度为给定参数中的最大标度。

这些函数的运行速度明显慢于常规的 multiply。如果你并不需要受控精度和/或希望快速计算，请考虑使用 multiply

语法

multiplyDecimal(a, b[, result_scale])

参数

a — 第一个值。Decimal
b — 第二个值。Decimal
result_scale — 结果的标度。(U)Int*

返回值 按给定标度计算出的乘法结果。类型：Decimal256 示例 使用示例

Query

SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)

Response

25.2

与普通乘法的区别

Query

SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)

Response

┌─multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                               -26.8609633 │
└───────────────────────────────────────────────────────────┘
┌─multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                                         -26.8609 │
└──────────────────────────────────────────────────────────────────┘

Decimal 类型溢出

Query

SELECT
    toDecimal64(-12.647987876, 9) AS a,
    toDecimal64(123.967645643, 9) AS b,
    multiplyDecimal(a, b);
SELECT
    toDecimal64(-12.647987876, 9) AS a,
    toDecimal64(123.967645643, 9) AS b,
    a * b;

Response

┌─────────────a─┬─────────────b─┬─multiplyDecimal(toDecimal64(-12.647987876, 9), toDecimal64(123.967645643, 9))─┐
│ -12.647987876 │ 123.967645643 │                                                               -1567.941279108 │
└───────────────┴───────────────┴───────────────────────────────────────────────────────────────────────────────┘
Received exception from server (version 22.11.1):
Code: 407. DB::Exception: Received from localhost:9000. DB::Exception: Decimal math overflow:
While processing toDecimal64(-12.647987876, 9) AS a, toDecimal64(123.967645643, 9) AS b, a * b. (DECIMAL_OVERFLOW)

negate

引入版本：v1.1.0 对参数 x 取反。结果始终为有符号数。语法

negate(x)

参数

x — 要取负值的值。

返回值 返回 x 的相反数 -x。示例 使用示例

Query

SELECT negate(10)

Response

-10

plus

引入版本：v1.1.0 计算两个值 x 和 y 的和。别名：x + y (运算符) 。整数可以与日期或日期时间相加。前一种运算会增加日期中的天数，后一种运算会增加日期时间中的秒数。日期也可以与时间相加。将 Date 与 Time 相加会生成 DateTime。将 Date 与 Time64 相加，或将 Date32 与 Time 或 Time64 相加，会生成 DateTime64。语法

plus(x, y)

参数

x — 左操作数。 - y — 右操作数。

返回值 返回 x 与 y 的和示例 两个数相加

Query

SELECT plus(5,5)

Response

整数与日期相加

Query

SELECT plus(toDate('2025-01-01'),5)

Response

2025-01-06

添加日期和时间

Query

SELECT toDate('2025-01-01') + CAST('14:30:25', 'Time')

Response

2025-01-01 14:30:25

positiveModulo

引入版本：v22.11.0 计算 x 除以 y 的余数。与函数 modulo 类似，不同之处在于 positiveModulo 始终返回非负数。语法

positiveModulo(x, y)

别名: positive_modulo, pmod 参数

x — 被除数。(U)Int* 或 Float* 或 Decimal
y — 除数 (模数) 。(U)Int* 或 Float* 或 Decimal

返回值 返回 x 与不大于 x 且能被 y 整除的最大整数之间的差值。示例 用法示例

Query

SELECT positiveModulo(-1, 10)

Response

positiveModuloOrNull

引入版本：v25.5.0 计算 a 除以 b 的余数。与函数 positiveModulo 类似，不同之处在于，如果右侧参数为 0，positiveModuloOrNull 将返回 NULL。语法

positiveModuloOrNull(x, y)

别名: positive_modulo_or_null, pmodOrNull 参数

x — 被除数。(U)Int*/Float32/64。- y — 除数 (模数) 。(U)Int*/Float32/64。

返回值 返回 x 与不大于 x 且可被 y 整除的最大整数之差；当除数为零时，返回 null。示例 positiveModuloOrNull

Query

SELECT positiveModuloOrNull(5, 0)

Response

\N

​概述

​abs

​avg2

​byteSwap

​divide

​divideDecimal

​divideOrNull

​gcd

​ifNotFinite

​intDiv

​intDivOrNull

​intDivOrZero

​isFinite

​isInfinite

​isNaN

​lcm

​max2

​midpoint

​min2

​minus

​modulo

​moduloLegacy

​moduloOrNull

​moduloOrZero

​multiply

​multiplyDecimal

​negate

​plus

​positiveModulo

​positiveModuloOrNull

概述

abs

avg2

byteSwap

divide

divideDecimal

divideOrNull

gcd

ifNotFinite

intDiv

intDivOrNull

intDivOrZero

isFinite

isInfinite

isNaN

lcm

max2

midpoint

min2

minus

modulo

moduloLegacy

moduloOrNull

moduloOrZero

multiply

multiplyDecimal

negate

plus

positiveModulo

positiveModuloOrNull