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

> 算术函数文档

# 算术函数

<div id="overview">
  ## 概述
</div>

算术函数适用于任意两个类型为 `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) 作为最大整数类型的其他数据库兼容。

示例：

```sql theme={null}
SELECT toTypeName(0), toTypeName(0 + 0), toTypeName(0 + 0 + 0), toTypeName(0 + 0 + 0 + 0)
```

```text theme={null}
┌─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++ 中相同。

{/*AUTOGENERATED_START*/}

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

引入版本：v1.1.0

计算 `x` 的绝对值。如果 `x` 是无符号类型，则不会产生任何影响。如果 `x` 是有符号类型，则返回无符号数。

**语法**

```sql theme={null}
abs(x)
```

**参数**

* `x` — 需要求绝对值的值

**返回值**

`x` 的绝对值

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT abs(-0.5)
```

```response title=Response theme={null}
0.5
```

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

引入版本：v25.11.0

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

**语法**

```sql theme={null}
avg2(x1, x2])
```

**参数**

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

**返回值**

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

**示例**

**数值类型**

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

```response title=Response theme={null}
┌─result─┬─type────┐
│      2 │ Float64 │
└────────┴─────────┘
```

**Decimal 类型**

```sql title=Query theme={null}
SELECT avg2(toDecimal32(1, 2), 2) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘
```

**日期类型**

```sql title=Query theme={null}
SELECT avg2(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘
```

**DateTime 类型**

```sql title=Query theme={null}
SELECT avg2(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘
```

**Time64 类型**

```sql title=Query theme={null}
SELECT avg2(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌───result─┬─type──────┐
│ 13:00:00 │ Time64(0) │
└──────────┴───────────┘
```

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

引入版本：v23.10.0

将整数的字节顺序反转，即改变其[字节序](https://en.wikipedia.org/wiki/Endianness)。

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

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

```result theme={null}
┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
│ 199.199.251.205                                       │
└───────────────────────────────────────────────────────┘
```

**语法**

```sql theme={null}
byteSwap(x)
```

**参数**

* `x` — 整数值。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回字节顺序颠倒后的 `x`。[`(U)Int*`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT byteSwap(3351772109)
```

```response title=Response theme={null}
3455829959
```

**8 位**

```sql title=Query theme={null}
SELECT byteSwap(54)
```

```response title=Response theme={null}
54
```

**16 位**

```sql title=Query theme={null}
SELECT byteSwap(4135)
```

```response title=Response theme={null}
10000
```

**32 位**

```sql title=Query theme={null}
SELECT byteSwap(3351772109)
```

```response title=Response theme={null}
3455829959
```

**64 位**

```sql title=Query theme={null}
SELECT byteSwap(123294967295)
```

```response title=Response theme={null}
18439412204227788800
```

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

引入版本：v1.1.0

计算两个值 `a` 和 `b` 的商。结果类型始终为 [Float64](/zh/reference/data-types/float)。
整数除法请使用 `intDiv` 函数。

<Note>
  除数为 `0` 时，会返回 `inf`、`-inf` 或 `nan`。
</Note>

**语法**

```sql theme={null}
divide(x, y)
```

**参数**

* `x` — 被除数；`y` — 除数

**返回值**

x 与 y 的商

**示例**

**两个数相除**

```sql title=Query theme={null}
SELECT divide(25,5) AS quotient, toTypeName(quotient)
```

```response title=Response theme={null}
5 Float64
```

**除以零**

```sql title=Query theme={null}
SELECT divide(25,0)
```

```response title=Response theme={null}
inf
```

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

Introduced in: v22.12.0

对两个 Decimal 执行除法运算。结果值的类型为 [Decimal256](/zh/reference/data-types/decimal)。
结果标度可通过 `result_scale` 参数 (取值范围为 `[0, 76]` 的常量 Integer) 显式指定。若未指定，则结果标度为给定参数中的最大标度。

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

**语法**

```sql theme={null}
divideDecimal(x, y[, result_scale])
```

**参数**

* `x` — 第一个值：[Decimal](/zh/reference/data-types/decimal)。 - `y` — 第二个值：[Decimal](/zh/reference/data-types/decimal)。 - `result_scale` — 结果标度。类型：[Int/UInt](/zh/reference/data-types/int-uint)。

**返回值**

按给定标度得到的除法结果。[`Decimal256`](/zh/reference/data-types/decimal)

**示例**

**示例 1**

```sql title=Query theme={null}
divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)
```

```response title=Response theme={null}
┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
│                                                -5.7142857142 │
└──────────────────────────────────────────────────────────────┘
```

**示例 2**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─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 │
└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
```

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

在 v25.5.0 中引入

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

**语法**

```sql theme={null}
divideOrNull(x, y)
```

**参数**

* `x` — 被除数 - `y` — 除数

**返回值**

x 与 y 的商，或 NULL。

**示例**

**除以零**

```sql title=Query theme={null}
SELECT divideOrNull(25, 0)
```

```response title=Response theme={null}
\N
```

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

引入版本：v1.1.0

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

当除数为零，或将最小负数除以负一时，
会抛出异常。

**语法**

```sql theme={null}
gcd(x, y)
```

**参数**

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

**返回值**

`x` 和 `y` 的最大公因数。

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT gcd(12, 18)
```

```response title=Response theme={null}
6
```

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

Introduced in: v20.3.0

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

你也可以使用[三元运算符](/zh/reference/functions/regular-functions/conditional-functions#if)获得类似的结果：`isFinite(x) ? x : y`。

**语法**

```sql theme={null}
ifNotFinite(x,y)
```

**参数**

* `x` — 要检查是否为无穷大的值。[`Float*`](/zh/reference/data-types/float)
* `y` — 备用值。[`Float*`](/zh/reference/data-types/float)

**返回值**

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

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT 1/0 AS infimum, ifNotFinite(infimum,42)
```

```response title=Response theme={null}
inf  42
```

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

Introduced in: v1.1.0

对两个值 `x` 和 `y` 执行整数除法。也就是说，
计算向下取整后的商。

结果与被除数 (第一个参数) 的位宽相同。

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

**语法**

```sql theme={null}
intDiv(x, y)
```

**参数**

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

**返回值**

`x` 与 `y` 整数相除的结果

**示例**

**两个浮点数的整数除法**

```sql title=Query theme={null}
SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)
```

```response title=Response theme={null}
┌──res─┬─toTypeName(intDiv(toFloat64(1), 0.001))─┐
│ 1000 │ Int64                                   │
└──────┴─────────────────────────────────────────┘
```

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

```sql title=Query theme={null}
SELECT
intDiv(1, 0.001) AS res,
toTypeName(res)
```

```response title=Response theme={null}
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)
```

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

引入版本：v25.5.0

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

**语法**

```sql theme={null}
intDivOrNull(x, y)
```

**参数**

* `x` — 左操作数。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `y` — 右操作数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

`x` 与 `y` 做整数除法的结果，或 NULL。

**示例**

**被零除的整数除法**

```sql title=Query theme={null}
SELECT intDivOrNull(1, 0)
```

```response title=Response theme={null}
\N
```

**最小负数除以 -1**

```sql title=Query theme={null}
SELECT intDivOrNull(-9223372036854775808, -1)
```

```response title=Response theme={null}
\N
```

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

引入版本：v1.1.0

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

**语法**

```sql theme={null}
intDivOrZero(a, b)
```

**参数**

* `a` — 左操作数。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `b` — 右操作数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

`a` 与 `b` 做整数除法的结果，或为零。

**示例**

**整数除以零**

```sql title=Query theme={null}
SELECT intDivOrZero(1, 0)
```

```response title=Response theme={null}
0
```

**最小负数除以 -1**

```sql title=Query theme={null}
SELECT intDivOrZero(0.05, -1)
```

```response title=Response theme={null}
0
```

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

引入版本：v1.1.0

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

**语法**

```sql theme={null}
isFinite(x)
```

**参数**

* `x` — 要检查是否为有限值的数。[`Float*`](/zh/reference/data-types/float)

**返回值**

如果 x 不是无穷大且不是 `NaN`，则返回 `1`；否则返回 `0`。

**示例**

**测试一个数是否为有限值**

```sql title=Query theme={null}
SELECT isFinite(inf)
```

```response title=Response theme={null}
0
```

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

Introduced in: v1.1.0

如果 Float32 或 Float64 参数是无穷大，则返回 `1`；否则返回 `0`。
请注意，参数为 `NaN` 时也会返回 `0`。

**Syntax**

```sql theme={null}
isInfinite(x)
```

**参数**

* `x` — 用于检查是否为无穷大的数值。[`Float*`](/zh/reference/data-types/float)

**返回值**

若 x 为无穷大，则返回 `1`；否则返回 `0` (`NaN` 也返回 `0`) 。

**示例**

**判断一个数值是否为无穷大**

```sql title=Query theme={null}
SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10))
```

```response title=Response theme={null}
1 0 0
```

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

引入版本：v1.1.0

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

**语法**

```sql theme={null}
isNaN(x)
```

**参数**

* `x` — 要检查是否为 `NaN` 的参数。[`Float*`](/zh/reference/data-types/float)

**返回值**

如果为 `NaN`，则返回 `1`；否则返回 `0`

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT isNaN(NaN)
```

```response title=Response theme={null}
1
```

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

引入版本：v1.1.0

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

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

**语法**

```sql theme={null}
lcm(x, y)
```

**参数**

* `x` — 第一个整数。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `y` — 第二个整数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 `x` 和 `y` 的最小公倍数。[`(U)Int*`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT lcm(6, 8)
```

```response title=Response theme={null}
24
```

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

引入版本：v21.11.0

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

**语法**

```sql theme={null}
max2(x, y)
```

**参数**

* `x` — 第一个值 [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `y` — 第二个值 [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回 `x` 和 `y` 中的较大值。 [`Float64`](/zh/reference/data-types/float)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT max2(-1, 2)
```

```response title=Response theme={null}
2
```

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

引入版本：v25.11.0

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

**语法**

```sql theme={null}
midpoint(x1[, x2, ...])
```

**参数**

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

**返回值**

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

**示例**

**数值类型**

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

```response title=Response theme={null}
┌─result─┬─type────┐
│    1.5 │ Float64 │
└────────┴─────────┘
```

**Decimal 类型**

```sql title=Query theme={null}
SELECT midpoint(toDecimal32(1.5, 2), toDecimal32(1, 1), 2) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌─result─┬─type──────────┐
│    1.5 │ Decimal(9, 2) │
└────────┴───────────────┘
```

**日期类型**

```sql title=Query theme={null}
SELECT midpoint(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌─────result─┬─type─┐
│ 2025-01-03 │ Date │
└────────────┴──────┘
```

**DateTime 类型**

```sql title=Query theme={null}
SELECT midpoint(toDateTime('2025-01-01 00:00:00'), toDateTime('2025-01-03 12:00:00')) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌──────────────result─┬─type─────┐
│ 2025-01-02 06:00:00 │ DateTime │
└─────────────────────┴──────────┘
```

**Time64 类型**

```sql title=Query theme={null}
SELECT midpoint(toTime64('12:00:00', 0), toTime64('14:00:00', 0)) AS result, toTypeName(result) AS type;
```

```response title=Response theme={null}
┌───result─┬─type──────┐
│ 13:00:00 │ Time64(0) │
└──────────┴───────────┘
```

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

引入版本：v21.11.0

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

**语法**

```sql theme={null}
min2(x, y)
```

**参数**

* `x` — 第一个值 [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `y` — 第二个值 [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回 `x` 和 `y` 中较小的值。 [`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT min2(-1, 2)
```

```response title=Response theme={null}
-1
```

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

在 v1.1.0 中引入

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

**语法**

```sql theme={null}
minus(x, y)
```

**参数**

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

**返回值**

x 与 y 的差

**示例**

**两个数相减**

```sql title=Query theme={null}
SELECT minus(10, 5)
```

```response title=Response theme={null}
5
```

**整数和日期相减**

```sql title=Query theme={null}
SELECT minus(toDate('2025-01-01'),5)
```

```response title=Response theme={null}
2024-12-27
```

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

Introduced in: v1.1.0

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

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

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

当除数为零，或将最小负数除以负一时，会抛出异常。

**Syntax**

```sql theme={null}
modulo(a, b)
```

**别名**: `mod`

**参数**

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

**返回值**

a % b 的余数

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT modulo(5, 2)
```

```response title=Response theme={null}
1
```

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

引入版本：v1.1.0

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

**语法**

```sql theme={null}
moduloLegacy(a, b)
```

**参数**

* `a` — 被除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `b` — 除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回相除后的余数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT moduloLegacy(10, 3)
```

```response title=Response theme={null}
1
```

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

引入版本：v25.5.0

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

**语法**

```sql theme={null}
moduloOrNull(x, y)
```

**别名**: `modOrNull`

**参数**

* `x` — 被除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `y` — 除数 (模数) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 `x` 除以 `y` 的余数；当除数为零时，返回 NULL。

**示例**

**除数为零时的 moduloOrNull**

```sql title=Query theme={null}
SELECT moduloOrNull(5, 0)
```

```response title=Response theme={null}
\N
```

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

首次引入版本：v20.3.0

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

**语法**

```sql theme={null}
moduloOrZero(a, b)
```

**参数**

* `a` — 被除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `b` — 除数 (模数) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

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

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT moduloOrZero(5, 0)
```

```response title=Response theme={null}
0
```

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

引入于：v1.1.0

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

**语法**

```sql theme={null}
multiply(x, y)
```

**参数**

* `x` — 因子。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `y` — 因子。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

返回 x 与 y 的乘积

**示例**

**将两个数相乘**

```sql title=Query theme={null}
SELECT multiply(5,5)
```

```response title=Response theme={null}
25
```

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

引入版本：v22.12.0

对两个 Decimal 执行乘法。结果值的类型为 [Decimal256](/zh/reference/data-types/decimal)。
结果标度可以通过 `result_scale` 参数 (取值范围为 `[0, 76]` 的常量 Integer) 显式指定。若未指定，则结果标度为给定参数中的最大标度。

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

**语法**

```sql theme={null}
multiplyDecimal(a, b[, result_scale])
```

**参数**

* `a` — 第一个值。[`Decimal`](/zh/reference/data-types/decimal)
* `b` — 第二个值。[`Decimal`](/zh/reference/data-types/decimal)
* `result_scale` — 结果的标度。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

按给定标度计算出的乘法结果。类型：[`Decimal256`](/zh/reference/data-types/decimal)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
```

```response title=Response theme={null}
25.2
```

**与普通乘法的区别**

```sql title=Query theme={null}
SELECT multiplyDecimal(toDecimal256(-12, 0), toDecimal32(-2.1, 1), 1)
```

```response title=Response theme={null}
┌─multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                               -26.8609633 │
└───────────────────────────────────────────────────────────┘
┌─multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4))─┐
│                                                         -26.8609 │
└──────────────────────────────────────────────────────────────────┘
```

**Decimal 类型溢出**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─────────────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)
```

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

引入版本：v1.1.0

对参数 `x` 取反。结果始终为有符号数。

**语法**

```sql theme={null}
negate(x)
```

**参数**

* `x` — 要取负值的值。

**返回值**

返回 `x` 的相反数 `-x`。

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT negate(10)
```

```response title=Response theme={null}
-10
```

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

引入版本：v1.1.0

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

**语法**

```sql theme={null}
plus(x, y)
```

**参数**

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

**返回值**

返回 x 与 y 的和

**示例**

**两个数相加**

```sql title=Query theme={null}
SELECT plus(5,5)
```

```response title=Response theme={null}
10
```

**整数与日期相加**

```sql title=Query theme={null}
SELECT plus(toDate('2025-01-01'),5)
```

```response title=Response theme={null}
2025-01-06
```

**添加日期和时间**

```sql title=Query theme={null}
SELECT toDate('2025-01-01') + CAST('14:30:25', 'Time')
```

```response title=Response theme={null}
2025-01-01 14:30:25
```

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

引入版本：v22.11.0

计算 `x` 除以 `y` 的余数。与函数
`modulo` 类似，不同之处在于 `positiveModulo` 始终返回非负数。

**语法**

```sql theme={null}
positiveModulo(x, y)
```

**别名**: `positive_modulo`, `pmod`

**参数**

* `x` — 被除数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `y` — 除数 (模数) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)

**返回值**

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

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT positiveModulo(-1, 10)
```

```response title=Response theme={null}
9
```

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

引入版本：v25.5.0

计算 `a` 除以 `b` 的余数。与函数 `positiveModulo` 类似，不同之处在于，如果右侧参数为 0，`positiveModuloOrNull` 将返回 NULL。

**语法**

```sql theme={null}
positiveModuloOrNull(x, y)
```

**别名**: `positive_modulo_or_null`, `pmodOrNull`

**参数**

* `x` — 被除数。[`(U)Int*`](/zh/reference/data-types/int-uint)/[`Float32/64`](/zh/reference/data-types/float)。- `y` — 除数 (模数) 。[`(U)Int*`](/zh/reference/data-types/int-uint)/[`Float32/64`](/zh/reference/data-types/float)。

**返回值**

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

**示例**

**positiveModuloOrNull**

```sql title=Query theme={null}
SELECT positiveModuloOrNull(5, 0)
```

```response title=Response theme={null}
\N
```