算術関数 | ClickHouse Docs

概要

算術関数は、UInt8、UInt16、UInt32、UInt64、Int8、Int16、Int32、Int64、Float32、または Float64 型の任意の 2 つのオペランドに対して使用できます。

演算を実行する前に、両方のオペランドは結果型にキャストされます。結果型は次のように決定されます (ただし、以下の関数ドキュメントで別途指定されている場合を除きます) 。

両方のオペランドが 32 ビット以下の場合、結果型のサイズは、2 つのオペランドのうち大きい方の次に大きい型のサイズになります (整数サイズの昇格) 。たとえば、UInt8 + UInt16 = UInt32 や Float32 * Float32 = Float64 です。
いずれか一方のオペランドが 64 ビット以上の場合、結果型のサイズは 2 つのオペランドのうち大きい方と同じになります。たとえば、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 の絶対値

例

使用例

SELECT abs(-0.5)

0.5

avg2

導入バージョン: v25.11.0

指定された引数の平均値を計算して返します。数値型および時間関連の型をサポートします。

構文

avg2(x1, x2])

引数

x1, x2] — 平均を求める 2 つの値を受け取ります。

戻り値

指定された引数の平均値を返します。結果の型は、互換性のある最大の型になります。

例

数値型

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) │
└────────┴───────────────┘

Date型

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.0

整数のバイト順を反転します。つまり、エンディアンを変更します。

以下の例は、次のように考えることができます。

10進整数を、ビッグエンディアンの16進表現に変換します。つまり、3351772109 -> C7 C7 FB CD (4バイト)
バイト順を反転します。つまり、C7 C7 FB CD -> CD FB C7 C7
結果をビッグエンディアンとみなして整数に戻します。つまり、CD FB C7 C7 -> 3455829959 この関数の用途の1つは、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.0

2 つの値 a と b の商を計算します。結果型は常に Float64 です。整数除算には intDiv 関数を使用します。

構文

divide(x, y)

引数

x — 被除数 - y — 除数

戻り値

x を y で割った商

例

2 つの数値を割る

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

5	Float64

ゼロ除算

SELECT divide(25,0)

inf

divideDecimal

導入バージョン: v22.12.0

2 つの Decimal に対して除算を行います。結果の値の型は Decimal256 です。結果の scale は result_scale 引数 (範囲 [0, 76] の定数 Integer) で明示的に指定できます。指定しない場合、結果の scale は指定された引数の最大 scale になります。

構文

divideDecimal(x, y[, result_scale])

引数

x — 最初の値: Decimal. - y — 2 番目の値: Decimal. - result_scale — 結果のスケール。型は Int/UInt。

戻り値

指定したスケールでの除算結果です。Decimal256

例

例 1

SELECT 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(a, b, 1)─┬─divideDecimal(a, b, 5)─┐
│ -12 │ 2.1 │                   -5.7 │               -5.71428 │
└─────┴─────┴────────────────────────┴────────────────────────┘

divideOrNull

導入バージョン: v25.5.0

divide と同様ですが、0 で除算した場合は NULL を返します。

構文

divideOrNull(x, y)

引数

x — 被除数 - y — 除数

戻り値

x と y の商、または NULL。

例

ゼロによる除算

SELECT divideOrNull(25, 0)

\N

gcd

導入バージョン: v1.1.0

2 つの値 a と b の最大公約数を返します。

0 で除算した場合、または最小の負の数をマイナス 1 で除算した場合は、例外が送出されます。

構文

gcd(x, y)

引数

x — 最初の整数 - y — 2 つ目の整数

戻り値

x と y の最大公約数。

例

使用例

SELECT gcd(12, 18)

ifNotFinite

導入バージョン: v20.3.0

浮動小数点値が有限かどうかを判定します。

三項演算子を使っても、同様の結果を得られます: 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.0

2 つの値 x を y で整数除算します。つまり、商を切り下げて計算します。

結果のビット幅は被除数 (最初のパラメータ) と同じです。

0 で除算した場合、商が被除数の範囲に収まらない場合、または最小の負数をマイナス 1 で除算した場合は、例外が発生します。

構文

intDiv(x, y)

引数

x — 左側のオペランド。 - y — 右側のオペランド。

戻り値

x を y で整数除算した結果

例

2 つの浮動小数点数を整数除算する

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

┌──res─┬─toTypeName(res)─┐
│ 1000 │ Int64           │
└──────┴─────────────────┘

商が被除数の範囲内に収まらない

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

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 と同様ですが、0 で除算した場合、または最小の負数を -1 で除算した場合は NULL を返します。

構文

intDivOrNull(x, y)

引数

x — 左側のオペランド。(U)Int*
y — 右側のオペランド。(U)Int*

戻り値

x を y で整数除算した結果、または NULL。

例

0 による整数除算

SELECT intDivOrNull(1, 0)

\N

最小の負数を -1 で割る

SELECT intDivOrNull(-9223372036854775808, -1)

\N

intDivOrZero

導入バージョン: v1.1.0

intDiv と同様ですが、0 による除算時、または最小の負の数を -1 で除算した場合は 0 を返します。

構文

intDivOrZero(a, b)

引数

a — 左側のオペランド。(U)Int*
b — 右側のオペランド。(U)Int*

戻り値

a を b で整数除算した結果、または 0。

例

0 での整数除算

SELECT intDivOrZero(1, 0)

最小の負数を-1で割る

SELECT intDivOrZero(0.05, -1)

isFinite

導入バージョン: v1.1.0

Float32、Float64、または BFloat16 の引数が無限大でも NaN でもない場合は 1 を返し、それ以外の場合は 0 を返します。

構文

isFinite(x)

引数

x — 有限かどうかを判定する数値。Float* または BFloat16

戻り値

x が無限大でも NaN でもない場合は 1、それ以外の場合は 0 を返します。

例

数値が有限かどうかを判定する

SELECT isFinite(inf)

isInfinite

導入バージョン: v1.1.0

Float32 または Float64、あるいは BFloat16 の引数が無限大の場合は 1 を返し、それ以外の場合は 0 を返します。 NaN に対しては 0 が返される点に注意してください。

構文

isInfinite(x)

引数

x — 無限大かどうかを判定する数値。Float* または BFloat16

戻り値

x が無限大の場合は 1、それ以外の場合は 0 (NaN を含む) 。

例

数値が無限大かどうかを判定する

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

1	0	0

isNaN

導入バージョン: v1.1.0

引数の Float32 または Float64、あるいは BFloat16 が NaN の場合は 1 を返し、それ以外の場合は 0 を返します。

構文

isNaN(x)

引数

x — NaN かどうかを判定する引数。Float* または BFloat16

戻り値

NaN の場合は 1、それ以外は 0

例

使用例

SELECT isNaN(NaN)

lcm

導入バージョン: v1.1.0

2 つの値 x と y の最小公倍数を返します。

ゼロで除算した場合、または最小の負の数をマイナス 1 で除算した場合は、例外がスローされます。

構文

lcm(x, y)

引数

x — 1 つ目の整数。(U)Int*
y — 2 つ目の整数。(U)Int*

戻り値

x と y の最小公倍数を返します。(U)Int*

例

使用例

SELECT lcm(6, 8)

max2

導入バージョン: v21.11.0

2 つの数値 x と y のうち、より大きい方を返します。

構文

max2(x, y)

引数

x — 1 つ目の値 (U)Int8/16/32/64 または Float* または BFloat16 または Decimal
y — 2 つ目の値 (U)Int8/16/32/64 または Float* または BFloat16 または Decimal

戻り値

x と y のうち大きい方の値を返します。 Float64

例

使用例

SELECT max2(-1, 2)

midpoint

導入バージョン: v25.11.0

指定された引数の平均値を計算して返します。数値型および日時型をサポートします。

構文

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

引数

x1[, x2, ...] — 平均を求める対象として、単一の値または複数の値を受け取ります。

戻り値

指定された引数の平均値を返します。結果の型は、互換性のある最大の型に昇格されます。

例

数値型

SELECT midpoint(1, toUInt8(3), 0.5) AS result, toTypeName(result) AS type;
-- UInt8 は比較のために 64 ビットに昇格する必要があるため、返される型は Float64 になります。

┌─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) │
└────────┴───────────────┘

Date型

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.0

2 つの数値 x と y のうち、小さいほうの値を返します。

構文

min2(x, y)

引数

x — 1つ目の値 (U)Int8/16/32/64 または Float* または BFloat16 または Decimal
y — 2つ目の値 (U)Int8/16/32/64 または Float* または BFloat16 または Decimal

戻り値

x と y のうち、より小さい値を返します。 Float64

例

使用例

SELECT min2(-1, 2)

-1

minus

導入バージョン: v1.1.0

2 つの値 a と b の差を計算します。結果は常に符号付きとなります。 plus と同様に、日付または日時から整数を減算できます。さらに、日時同士の減算もサポートされており、その場合は両者の時間差が返されます。

構文

minus(x, y)

引数

x — 被減数。 - y — 減数。

戻り値

x から y を引いた値

例

2 つの数値の減算

SELECT minus(10, 5)

整数と日付の減算

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

2024-12-27

modulo

導入バージョン: v1.1.0

値 a を b で割った剰余を計算します。

両方の入力が整数の場合、結果の型は整数になります。入力の一方が浮動小数点数の場合、結果の型は Float64 になります。

余りは C++ と同様に計算されます。負の数に対しては、切り捨て除算が使用されます。

0 による除算、または最小の負の数をマイナス 1 で割った場合は、例外が発生します。

構文

modulo(a, b)

別名: mod

引数

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

戻り値

a % b の剰余

例

使用例

SELECT modulo(5, 2)

moduloLegacy

導入バージョン: v1.1.0

除算の剰余を計算します。これは C++ の % 演算子を使用する従来の modulo 実装で、負の引数に対しては負の結果を返すことがあります。この関数は、古いテーブルのパーティション化ロジックとの後方互換性を保つために用意されています。標準的な動作が必要な場合は、modulo または positiveModulo を使用してください。

構文

moduloLegacy(a, b)

引数

a — 被除数。(U)Int* または Float*
b — 除数。(U)Int* または Float*

戻り値

除算の剰余を返します。(U)Int* または Float*

例

基本的な使い方

SELECT moduloLegacy(10, 3)

moduloOrNull

導入バージョン: v25.5.0

a を b で割ったときの剰余を計算します。関数 modulo と似ていますが、moduloOrNull は、通常であれば浮動小数点例外が発生する場合に NULL を返します。浮動小数点の引数では、これは除数が 0 の場合にのみ発生します。整数の引数では、これに加えて最小の負の値を -1 で割った剰余も対象になります (たとえば Int8 の -128 % -1) 。

構文

moduloOrNull(x, y)

別名: modOrNull

引数

x — 被除数。(U)Int* または Float*
y — 除数 (法) 。(U)Int* または Float*

戻り値

x を y で割った剰余を返します。除数が 0 の場合、または整数引数で最小の負の値を -1 で法演算した場合など、演算によって浮動小数点例外が発生する場合は NULL を返します。

例

除数が 0 の moduloOrNull

SELECT moduloOrNull(5, 0)

\N

最小の負の整数を -1 で割った場合の moduloOrNull

SELECT moduloOrNull(toInt8(-128), toInt8(-1))

\N

moduloOrZero

導入バージョン: v20.3.0

modulo と同様ですが、除数が 0 の場合は、modulo 関数のように例外を返すのではなく、0 を返します。

構文

moduloOrZero(a, b)

引数

a — 被除数。(U)Int* または Float*
b — 除数 (法) 。(U)Int* または Float*

戻り値

a % b の剰余を返します。除数が 0 の場合は 0 を返します。

例

使用例

SELECT moduloOrZero(5, 0)

multiply

導入バージョン: v1.1.0

2 つの値 x と y の積を計算します。

構文

multiply(x, y)

引数

x — 因数。(U)Int* または Float* または Decimal
y — 因数。(U)Int* または Float* または Decimal

戻り値

x と y の積を返します

例

2 つの数値を乗算する

SELECT multiply(5,5)

multiplyDecimal

導入バージョン: v22.12.0

2 つの Decimal に対して乗算を行います。結果の値の型は Decimal256 です。結果のスケールは、result_scale 引数 (範囲 [0, 76] の定数 Integer) で明示的に指定できます。指定しない場合、結果のスケールは指定された引数のスケールの最大値になります。

構文

multiplyDecimal(a, b[, result_scale])

引数

a — 最初の値。Decimal
b — 2番目の値。Decimal
result_scale — 結果のスケール。(U)Int*

戻り値

指定したスケールでの乗算結果。型: Decimal256

例

使用例

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

25.2

通常の乗算との違い

SELECT multiply(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4));
SELECT multiplyDecimal(toDecimal64(-12.647, 3), toDecimal32(2.1239, 4));

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

multiplyDecimal ではオーバーフローしない

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

┌─────────────a─┬─────────────b─┬─multiplyDecimal(a, b)─┐
│ -12.647987876 │ 123.967645643 │       -1567.941279108 │
└───────────────┴───────────────┴───────────────────────┘

通常の乗算でのDecimalオーバーフロー

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

Received exception:
Code: 407. DB::Exception: Decimal math overflow. (DECIMAL_OVERFLOW)

negate

導入バージョン: v1.1.0

引数 x の符号を反転します。結果は常に符号付きになります。

構文

negate(x)

引数

x — 符号を反転する値。

戻り値

x の符号を反転した値を返します

例

使用例

SELECT negate(10)

-10

plus

導入バージョン: v1.1.0

2 つの値 x と y の合計を計算します。別名: x + y (演算子) 。整数と日付、または日時を加算することもできます。前者では日付に日数が加算され、後者では日時に秒数が加算されます。日付と時刻を加算することもできます。Date と Time を加算すると、DateTime が生成されます。Date と Time64、または Date32 と Time もしくは Time64 を加算すると、DateTime64 が生成されます。

構文

plus(x, y)

引数

x — 左側のオペランド。 - y — 右側のオペランド。

戻り値

x と y の和を返します

例

2つの数値を加算する

SELECT plus(5,5)

整数と日付の加算

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

2025-01-06

日付と時刻を加算する

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

2025-01-01 14:30:25

positiveModulo

導入バージョン: v22.11.0

x を y で割った剰余を計算します。関数 modulo と似ていますが、positiveModulo は常に 0 以上の数を返します。

構文

positiveModulo(x, y)

別名: positive_modulo, pmod

引数

x — 被除数。(U)Int* または Float* または Decimal
y — 除数 (法) 。(U)Int* または Float* または Decimal

戻り値

x から、y で割り切れ、x を超えない最大の整数を引いた値を返します。

例

使用例

SELECT positiveModulo(-1, 10)

positiveModuloOrNull

導入バージョン: v25.5.0

a を b で割った剰余を計算します。関数 positiveModulo と似ていますが、positiveModuloOrNull は、通常であれば浮動小数点例外が発生する演算の場合に NULL を返します。浮動小数点の引数では、これは除数が 0 の場合にのみ発生します。整数の引数では、これに加えて最小の負の値を -1 で割った剰余も含まれます (たとえば Int8 の -128 % -1) 。

構文

positiveModuloOrNull(x, y)

別名: positive_modulo_or_null, pmodOrNull

引数

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

戻り値

x から、y で割り切れ、かつ x 以下の最大の整数を引いた差を返します。演算によって浮動小数点例外が発生する場合、つまり除数が 0 の場合、または整数引数で最小の負の値を -1 で法演算する場合は、NULL を返します。

例

0 を除数とする positiveModuloOrNull

SELECT positiveModuloOrNull(5, 0)

\N

最小の負の整数を -1 で割った場合の positiveModuloOrNull

SELECT positiveModuloOrNull(toInt8(-128), toInt8(-1))

\N

sqr

導入バージョン: v26.7.0

値 x の二乗を計算します。

構文

sqr(x)

引数

x — 二乗する値。 (U)Int* または Float* または Decimal

戻り値

x に x 自身を乗じた積を返します。

例

数値を二乗する

SELECT sqr(5)