算术函数

概览

算术函数适用于任意两个操作数，其类型为 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。

这些规则确保结果类型是在所有可能结果中仍然能够完整表示的最小类型。虽然这在数值范围边界附近存在发生溢出的风险，但它确保计算可以在最多 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

计算 x 的绝对值。如果 x 是无符号类型，则结果与原值相同（无变化）。如果 x 是有符号类型，则返回一个无符号数。

语法

abs(x)

参数

x — 要取绝对值的数值

返回值

x 的绝对值

示例

使用示例

SELECT abs(-0.5)

0.5

avg2

自 v25.11 起引入

计算并返回提供的参数的平均值。支持数值类型和时间类型。

语法

avg2(x1, x2])

参数

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

返回值

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

示例

数值类型

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

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

Decimal 类型

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

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

日期类型

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

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

DateTime 类型

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

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

Time64 类型

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

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

byteSwap

首次引入于：v23.10

反转整数的字节顺序，即改变其字节序。

下面的示例可以按如下方式理解：

将十进制整数转换为其在大端字节序下的十六进制表示，例如：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*

示例

用法示例

SELECT byteSwap(3351772109)

3455829959

8 位

SELECT byteSwap(54)

16 位

SELECT byteSwap(4135)

32 位

SELECT byteSwap(3351772109)

3455829959

64 位

SELECT byteSwap(123294967295)

18439412204227788800

divide

自 v1.1 版本引入

计算两个值 a 和 b 的商。结果类型始终为 Float64。整数除法由 intDiv 函数实现。

注意

除以 0 会返回 inf、-inf 或 nan。

语法

divide(x, y)

参数

x — 被除数；y — 除数

返回值

x 除以 y 的商

示例

两个数相除

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

5 Float64

除以零

SELECT divide(25,0)

inf

divideDecimal

引入版本：v22.12

对两个 Decimal 数执行除法运算。结果值类型为 Decimal256。结果小数位数可以通过 result_scale 参数显式指定（取值范围为 [0, 76] 的常量整型）。如果未指定，则结果的小数位数为给定参数中最⼤的小数位数。

注意

该函数的运行速度明显慢于常规的 divide。如果并不需要精确控制小数位数，或更需要快速计算，请考虑使用 divide。

语法

divideDecimal(x, y[, result_scale])

参数

x — 第一个值：Decimal. - y — 第二个值：Decimal. - result_scale — 结果的小数位数。类型为 Int/UInt.

返回值

按指定小数位数进行除法运算的结果。Decimal256

示例

示例 1

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

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

示例 2

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);

┌─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

与 divide 相同，但在除数为零时返回 NULL。

语法

divideOrNull(x, y)

参数

x — 被除数；y — 除数

返回值

x 除以 y 的商，或 NULL。

示例

除以零

SELECT divideOrNull(25, 0)

\N

gcd

自 v1.1 起引入

返回两个值 a 和 b 的最大公约数。

当发生除以零或将最小负数除以负一的情况时会抛出异常。

语法

gcd(x, y)

参数

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

返回值

x 和 y 的最大公约数。

示例

使用示例

SELECT gcd(12, 18)

ifNotFinite

引入于：v20.3

用于检查浮点数值是否为有限值。

你也可以使用三元运算符实现类似的结果：isFinite(x) ? x : y。

语法

ifNotFinite(x,y)

参数

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

返回值

当 x 为有限值时，返回 x。
当 x 为非有限值时，返回 y。

示例

用法示例

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

inf  42

intDiv

引入于：v1.1

对两个值 x 和 y 执行整数除法 x / y。换句话说，它计算向下取整到不大于真实结果的最大整数的商。

结果与被除数（第一个参数）具有相同的位宽。

当除数为零、商超出被除数类型的取值范围，或将最小负数除以 -1 时，会抛出异常。

语法

intDiv(x, y)

参数

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

返回值

x 除以 y 的整数除法结果

示例

两个浮点数之间的整数除法

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

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

商超出被除数的取值范围

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

服务器返回异常(版本 23.2.1):
代码: 153. DB::Exception: 来自 localhost:9000。DB::Exception:
无法执行整数除法,因为会产生无穷大或过大的数值:
处理 intDiv(1, 0.001) AS res, toTypeName(res) 时发生错误。
(ILLEGAL_DIVISION)

intDivOrNull

引入于：v25.5

与 intDiv 相同，但在除数为零或将最小负整数除以负一时返回 NULL。

语法

intDivOrNull(x, y)

参数

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

返回值

x 除以 y 的整数除法结果，或 NULL。

示例

整数除以零

SELECT intDivOrNull(1, 0)

\N

最小负数除以 -1

SELECT intDivOrNull(-9223372036854775808, -1)

\N

intDivOrZero

引入版本：v1.1

与 intDiv 相同，但在除数为零或将最小负整数除以负一时返回零。

语法

intDivOrZero(a, b)

参数

a — 左侧运算数。(U)Int*
b — 右侧运算数。(U)Int*

返回值

a 和 b 的整数除法结果，或零。

示例

整数除以零

SELECT intDivOrZero(1, 0)

将最小负数除以 −1

SELECT intDivOrZero(0.05, -1)

isFinite

自 v1.1 起引入

如果 Float32 或 Float64 参数既不是无穷大也不是 NaN，则返回 1，否则返回 0。

语法

isFinite(x)

参数

x — 要检查其是否为有限数的数字。Float*

返回值

如果 x 既不是无穷大也不是 NaN，则返回 1，否则返回 0。

示例

测试一个数是否为有限数

SELECT isFinite(inf)

isInfinite

在 v1.1 中引入

如果 Float32 或 Float64 参数为无穷大，则返回 1，否则函数返回 0。请注意，对于 NaN 会返回 0。

语法

isInfinite(x)

参数

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

返回值

如果 x 是无穷大则为 1，否则为 0（包括 NaN 在内）。

示例

测试一个数是否为无穷大

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

1 0 0

isNaN

引入版本：v1.1

如果 Float32 或 Float64 类型的参数为 NaN，则返回 1，否则返回 0。

语法

isNaN(x)

参数

x — 要判断是否为 NaN 的参数。Float*

返回值

若为 NaN，则返回 1，否则返回 0

示例

使用示例

SELECT isNaN(NaN)

lcm

引入版本：v1.1

返回两个值 x 和 y 的最小公倍数。

在发生除以零或将最小负值除以负一时会抛出异常。

语法

lcm(x, y)

参数

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

返回值

返回 x 和 y 的最小公倍数。(U)Int*

示例

使用示例

SELECT lcm(6, 8)

max2

在 v21.11 版本中引入

返回两个数值 x 和 y 中较大的一个。

语法

max2(x, y)

参数

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

返回值

返回 x 和 y 中较大的值。Float64

示例

用法示例

SELECT max2(-1, 2)

midpoint

引入版本：v25.11

计算并返回所提供参数的平均值。支持数值类型和时间类型。

语法

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

参数

x1[, x2, ...] — 接受一个或多个用于求平均值的值。

返回值

返回所提供参数的平均值，并将类型提升为兼容的最高等级类型。

示例

数值类型

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

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

Decimal 类型

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

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

日期类型

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

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

DateTime 类型

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

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

Time64 类型

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

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

min2

引入于：v21.11

返回两个数值 x 和 y 中较小的一个。

语法

min2(x, y)

参数

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

返回值

返回 x 和 y 中较小的值，类型为 Float64。

示例

使用示例

SELECT min2(-1, 2)

-1

minus

引入自：v1.1

计算两个值 a 和 b 的差。结果始终为有符号数。与 plus 类似，可以从日期或日期时间值中减去一个整数。此外，支持日期时间值之间的减法运算，结果为它们之间的时间差。

语法

minus(x, y)

参数

x — 被减数。
y — 减数。

返回值

x 减 y

示例

两数相减

SELECT minus(10, 5)

整数与日期相减

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

2024-12-27

modulo

引入版本：v1.1

计算两个值 a 被 b 相除所得的余数。

如果两个输入都是整数，结果类型为整数。如果其中一个输入是浮点数，结果类型为 Float64。

余数的计算方式与 C++ 相同。对负数使用截断除法。

当除以零或将最小可表示的负数除以负一时，会抛出异常。

语法

modulo(a, b)

别名: mod

参数

a — 被除数；b — 除数（模数）

返回值

a % b 的余数

示例

用法示例

SELECT modulo(5, 2)

moduloOrNull

引入版本：v25.5

计算 a 除以 b 时的余数。与函数 modulo 类似，不同之处在于当右侧参数为 0 时，moduloOrNull 将返回 NULL。

语法

moduloOrNull(x, y)

别名: modOrNull

参数

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

返回值

返回 x 除以 y 的余数；如果除数为零，则返回 null。

示例

除数为零时的 moduloOrNull

SELECT moduloOrNull(5, 0)

\N

moduloOrZero

自 v20.3 起引入

与 modulo 类似，但当除数为零时返回零，而不是像 modulo 函数那样抛出异常。

语法

moduloOrZero(a, b)

参数

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

返回值

返回 a % b 的余数，当除数为 0 时返回 0。

示例

用法示例

SELECT moduloOrZero(5, 0)

multiply

自 v1.1 起提供

计算两个值 x 和 y 的乘积。

语法

multiply(x, y)

参数

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

返回值

返回 x 和 y 的乘积。

示例

两个数相乘

SELECT multiply(5,5)

multiplyDecimal

引入于：v22.12

对两个十进制数执行乘法运算。结果值的类型为 Decimal256。可以通过 result_scale 参数（取值范围为 [0, 76] 的常量整数）显式指定结果的小数位（scale）。如果未指定，结果的小数位将采用传入参数中较大的那个小数位。

注意

这些函数的运行速度明显慢于常规的 multiply。如果你并不真正需要严格控制精度且/或需要快速计算，请考虑使用 multiply

语法

multiplyDecimal(a, b[, result_scale])

参数

a — 第一个值。Decimal
b — 第二个值。Decimal
result_scale — 结果的小数位数。(U)Int*

返回值

按指定小数位数进行乘法运算的结果。类型：Decimal256

示例

用法示例

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

25.2

与普通乘法的区别

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

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

Decimal 类型溢出

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;

┌─────────────a─┬─────────────b─┬─multiplyDecimal(toDecimal64(-12.647987876, 9), toDecimal64(123.967645643, 9))─┐
│ -12.647987876 │ 123.967645643 │                                                               -1567.941279108 │
└───────────────┴───────────────┴───────────────────────────────────────────────────────────────────────────────┘
服务器返回异常(版本 22.11.1):
代码: 407. DB::Exception: 来自 localhost:9000。DB::Exception: 十进制运算溢出:
处理 toDecimal64(-12.647987876, 9) AS a, toDecimal64(123.967645643, 9) AS b, a * b 时发生错误。(DECIMAL_OVERFLOW)

negate

自 v1.1 起引入

对参数 x 取相反数。结果始终为带符号数。

语法

negate(x)

参数

x — 要取相反数的值。

返回值

返回 -x

示例

使用示例

SELECT negate(10)

-10

plus

引入于：v1.1

计算两个值 x 和 y 的和。别名：x + y（运算符）。可以将整数与日期或日期时间相加。前一种运算会增加日期中的天数，后一种运算会增加日期时间中的秒数。

语法

plus(x, y)

参数

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

返回值

返回 x 和 y 相加的结果。

示例

两数相加

SELECT plus(5,5)

将整数与日期相加

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

2025-01-06

positiveModulo

引入版本：v22.11

计算 x 除以 y 的余数。与函数 modulo 类似，但 positiveModulo 始终返回非负数。

语法

positiveModulo(x, y)

别名: positive_modulo, pmod

参数

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

返回值

返回 x 与不大于 x 且能被 y 整除的最近整数之差。

示例

用法示例

SELECT positiveModulo(-1, 10)

positiveModuloOrNull

引入于：v25.5

计算 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

SELECT positiveModuloOrNull(5, 0)

\N

概览​

abs​

avg2​

byteSwap​

divide​

divideDecimal​

divideOrNull​

gcd​

ifNotFinite​

intDiv​

intDivOrNull​

intDivOrZero​

isFinite​

isInfinite​

isNaN​

lcm​

max2​

midpoint​

min2​

minus​

modulo​

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

moduloOrNull

moduloOrZero

multiply

multiplyDecimal

negate

plus

positiveModulo

positiveModuloOrNull