Арифметические функции

Арифметические функции применимы к любым двум операндам типа 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++.

Добавленный в: v1.1.0

Вычисляет абсолютное значение x. Не имеет эффекта, если x имеет беззнаковый тип. Если x имеет знаковый тип, возвращает беззнаковое число.

Синтаксис

abs(x)

Аргументы

• x — Значение, для которого вычисляется абсолютное значение

Возвращаемое значение

Абсолютное значение x

Примеры

Пример использования

SELECT abs(-0.5)

0.5

Добавленный в: v25.11.0

Вычисляет и возвращает среднее значение указанных аргументов. Поддерживает числовые и временные типы.

Синтаксис

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

Добавленный в: v23.10.0

Меняет порядок байтов целого числа на обратный, то есть изменяет его порядок байтов.

Приведённый ниже пример можно разобрать следующим образом:

1. Преобразуйте целое число из десятичной системы в эквивалентное шестнадцатеричное представление в формате big-endian, то есть 3351772109 -> C7 C7 FB CD (4 байта)
2. Переставьте байты в обратном порядке, то есть C7 C7 FB CD -> CD FB C7 C7
3. Преобразуйте результат обратно в целое число, предполагая формат big-endian, то есть 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)

54

16-битный

SELECT byteSwap(4135)

10000

32-разрядный

SELECT byteSwap(3351772109)

3455829959

64-разрядная

SELECT byteSwap(123294967295)

18439412204227788800

Добавленный в: v1.1.0

Вычисляет частное двух значений a и b. Тип результата всегда — Float64. Для целочисленного деления используется функция intDiv.

Синтаксис

divide(x, y)

Аргументы

• x — Делимое - y — Делитель

Возвращаемое значение

Частное от деления x на y

Примеры

Деление двух чисел

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

5	Float64

Деление на ноль

SELECT divide(25,0)

inf

Добавленный в: v22.12.0

Выполняет деление двух десятичных чисел. Результирующее значение имеет тип Decimal256. Масштаб результата можно явно задать с помощью аргумента result_scale (константный Integer в диапазоне [0, 76]). Если он не указан, масштаб результата будет равен максимальному масштабу среди переданных аргументов.

Синтаксис

divideDecimal(x, y[, result_scale])

Аргументы

• x — Первое значение: Decimal. - y — Второе значение: 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 │
└─────┴─────┴────────────────────────┴────────────────────────┘

Добавленный в: v25.5.0

Аналогично divide, но при делении на ноль возвращает NULL.

Синтаксис

divideOrNull(x, y)

Аргументы

• x — делимое - y — делитель

Возвращаемое значение

Результат деления x на y, или NULL.

Примеры

Деление на ноль

SELECT divideOrNull(25, 0)

\N

Добавленный в: v1.1.0

Возвращает наибольший общий делитель двух значений a и b.

Исключение генерируется при делении на ноль или при делении минимального отрицательного числа на -1.

Синтаксис

gcd(x, y)

Аргументы

• x — Первое целое число - y — Второе целое число

Возвращаемое значение

Наибольший общий делитель чисел x и y.

Примеры

Пример использования

SELECT gcd(12, 18)

6

Добавленный в: v20.3.0

Проверяет, является ли число с плавающей запятой конечным.

Аналогичный результат можно получить с помощью тернарного оператора: isFinite(x) ? x : y.

Синтаксис

ifNotFinite(x,y)

Аргументы

• x — Значение, которое нужно проверить на бесконечность. Float*
• y — Резервное значение. Float*

Возвращаемое значение

• x, если x является конечным.
• y, если x не является конечным.

Примеры

Пример использования

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

inf	42

Добавленный в: v1.1.0

Выполняет целочисленное деление значения x на y. Иными словами, вычисляет частное, округлённое вниз до ближайшего меньшего целого числа.

Результат имеет ту же разрядность, что и делимое (первый параметр).

Исключение генерируется при делении на ноль, если частное не помещается в диапазон делимого, или при делении минимального отрицательного числа на минус один.

Синтаксис

intDiv(x, y)

Аргументы

• x — Левый операнд. - y — Правый операнд.

Возвращаемое значение

Результат целочисленного деления x на y

Примеры

Целочисленное деление двух чисел с плавающей точкой

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)

Добавленный в: v25.5.0

То же, что и 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

Добавленный в: v1.1.0

То же, что и intDiv, но возвращает ноль при делении на ноль или при делении наименьшего отрицательного числа на минус единицу.

Синтаксис

intDivOrZero(a, b)

Аргументы

• a — Левый операнд. (U)Int*
• b — Правый операнд. (U)Int*

Возвращаемое значение

Результат целочисленного деления a на b, либо ноль.

Примеры

Целочисленное деление на ноль

SELECT intDivOrZero(1, 0)

0

Деление минимального отрицательного числа на -1

SELECT intDivOrZero(0.05, -1)

0

Добавленный в: v1.1.0

Возвращает 1, если аргумент Float32, Float64 или BFloat16 не является бесконечным и не равен NaN, в противном случае возвращает 0.

Синтаксис

isFinite(x)

Аргументы

• x — Число для проверки на конечность. Float* или BFloat16

Возвращаемое значение

1, если x не является бесконечным и не равно NaN, иначе 0.

Примеры

Проверка, является ли число конечным

SELECT isFinite(inf)

0

Добавленный в: v1.1.0

Возвращает 1, если аргумент типа Float32, Float64 или BFloat16 является бесконечностью; в противном случае возвращает 0. Обратите внимание, что для NaN также возвращается 0.

Синтаксис

isInfinite(x)

Аргументы

• x — число, которое нужно проверить на бесконечность. Float* или BFloat16

Возвращаемое значение

1, если x бесконечно, иначе — 0 (в том числе для NaN).

Примеры

Проверка, является ли число бесконечным

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

1	0	0

Добавленный в: v1.1.0

Возвращает 1, если аргумент типа Float32, Float64 или BFloat16 имеет значение NaN, в противном случае возвращает 0.

Синтаксис

isNaN(x)

Аргументы

• x — аргумент, для которого проверяется, является ли он NaN. Float* или BFloat16

Возвращаемое значение

1, если значение равно NaN, иначе 0

Примеры

Пример использования

SELECT isNaN(NaN)

1

Добавленный в: v1.1.0

Возвращает наименьшее общее кратное двух значений x и y.

Генерируется исключение при делении на ноль или при делении минимального отрицательного числа на минус один.

Синтаксис

lcm(x, y)

Аргументы

• x — Первое целое число. (U)Int*
• y — Второе целое число. (U)Int*

Возвращаемое значение

Возвращает наименьшее общее кратное чисел x и y. (U)Int*

Примеры

Пример использования

SELECT lcm(6, 8)

24

Добавленный в: v21.11.0

Возвращает большее из двух числовых значений x и y.

Синтаксис

max2(x, y)

Аргументы

• x — Первое значение (U)Int8/16/32/64 или Float*, или BFloat16, или Decimal
• y — Второе значение (U)Int8/16/32/64 или Float*, или BFloat16, или Decimal

Возвращаемое значение

Возвращает большее из значений x и y. Float64

Примеры

Пример использования

SELECT max2(-1, 2)

2

Добавленный в: v25.11.0

Вычисляет и возвращает среднее значение переданных аргументов. Поддерживает числовые и временные типы.

Синтаксис

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

Десятичные типы

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

Добавленный в: v21.11.0

Возвращает меньшее из двух числовых значений x и y.

Синтаксис

min2(x, y)

Аргументы

• x — Первое значение (U)Int8/16/32/64 или Float*, или BFloat16, или Decimal
• y — Второе значение (U)Int8/16/32/64 или Float*, или BFloat16, или Decimal

Возвращаемое значение

Возвращает меньшее из значений x и y. Float64

Примеры

Пример использования

SELECT min2(-1, 2)

-1

Добавленный в: v1.1.0

Вычисляет разность двух значений a и b. Результат всегда знаковый. Как и в случае с plus, из значения типа дата или дата и время можно вычитать целое число. Кроме того, поддерживается вычитание между значениями типа дата и время, в результате которого получается разница во времени между ними.

Синтаксис

minus(x, y)

Аргументы

• x — Уменьшаемое. - y — Вычитаемое.

Возвращаемое значение

Разность x и y

Примеры

Вычитание двух чисел

SELECT minus(10, 5)

5

Вычитание целого числа из даты

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

2024-12-27

Добавленный в: v1.1.0

Вычисляет остаток от деления значения a на значение b.

Тип результата — целое число, если оба входных значения целые. Если одно из входных значений — число с плавающей точкой, тип результата — Float64.

Остаток вычисляется так же, как в C++. Для отрицательных чисел используется усечённое деление.

При делении на ноль или при делении минимального отрицательного числа на минус единицу генерируется исключение.

Синтаксис

modulo(a, b)

Псевдонимы: mod

Аргументы

• a — Делимое - b — Делитель (модуль)

Возвращаемое значение

Остаток от деления a на b

Примеры

Пример использования

SELECT modulo(5, 2)

1

Добавленный в: v1.1.0

Вычисляет остаток от деления. Это устаревшая реализация modulo, использующая оператор % из C++, который может возвращать отрицательные результаты для отрицательных аргументов. Эта функция существует для обратной совместимости со старой логикой партиционирования таблиц. Для стандартного поведения используйте modulo или positiveModulo.

Синтаксис

moduloLegacy(a, b)

Аргументы

• a — Делимое. (U)Int* или Float*
• b — Делитель. (U)Int* или Float*

Возвращаемое значение

Возвращает остаток от деления. (U)Int* или Float*

Примеры

Базовое использование

SELECT moduloLegacy(10, 3)

1

Добавленный в: v25.5.0

Вычисляет остаток при делении a на b. Аналогична функции modulo, но moduloOrNull возвращает NULL, если операция в противном случае привела бы к исключению с плавающей запятой. Для аргументов с плавающей точкой это происходит только в случае, если делитель равен 0; для целочисленных аргументов это также включает случай, когда минимальное отрицательное значение берется по модулю -1 (например, -128 % -1 для Int8).

Синтаксис

moduloOrNull(x, y)

Псевдонимы: modOrNull

Аргументы

• x — Делимое. (U)Int* или Float*
• y — Делитель (модуль). (U)Int* или Float*

Возвращаемое значение

Возвращает остаток от деления x на y или NULL, если операция привела бы к исключению с плавающей запятой: когда делитель равен нулю или, для целочисленных аргументов, при вычислении минимального отрицательного значения по модулю -1.

Примеры

moduloOrNull при делении на ноль

SELECT moduloOrNull(5, 0)

\N

moduloOrNull при делении минимального отрицательного целого числа на -1

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

\N

Добавленный в: v20.3.0

Как modulo, но возвращает ноль, если делитель равен нулю, вместо исключения, которое возникает в функции modulo.

Синтаксис

moduloOrZero(a, b)

Аргументы

• a — Делимое. (U)Int* или Float*
• b — Делитель (модуль). (U)Int* или Float*

Возвращаемое значение

Возвращает остаток от деления a % b или 0, если делитель равен 0.

Примеры

Пример использования

SELECT moduloOrZero(5, 0)

0

Добавленный в: v1.1.0

Вычисляет произведение двух значений x и y.

Синтаксис

multiply(x, y)

Аргументы

• x — множитель. (U)Int* или Float* или Decimal
• y — множитель. (U)Int* или Float* или Decimal

Возвращаемое значение

Возвращает произведение x и y

Примеры

Умножение двух чисел

SELECT multiply(5,5)

25

Добавленный в: v22.12.0

Выполняет умножение двух десятичных чисел. Результирующее значение будет иметь тип Decimal256. Масштаб результата можно явно задать аргументом result_scale (константный Integer в диапазоне [0, 76]). Если он не указан, масштаб результата будет равен максимальному масштабу переданных аргументов.

Синтаксис

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

Добавленный в: v1.1.0

Меняет знак аргумента x на противоположный. Результат всегда знаковый.

Синтаксис

negate(x)

Аргументы

• x — Значение, знак которого нужно изменить на противоположный.

Возвращаемое значение

Возвращает -x для значения x

Примеры

Пример использования

SELECT negate(10)

-10

Добавленный в: v1.1.0

Вычисляет сумму двух значений x и y. Псевдоним: x + y (оператор). Можно складывать целое число и дату или дату и время. В первом случае увеличивается число дней в дате, во втором — число секунд в дате и времени. Также можно складывать дату и время. При сложении Date и Time получается DateTime. При сложении Date и Time64, а также Date32 и Time или Time64, получается DateTime64.

Синтаксис

plus(x, y)

Аргументы

• x — Левый операнд. - y — Правый операнд.

Возвращаемое значение

Возвращает сумму x и y

Примеры

Сложение двух чисел

SELECT plus(5,5)

10

Прибавление целого числа к дате

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

Добавленный в: 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.

Примеры

Пример использования

SELECT positiveModulo(-1, 10)

9

Добавленный в: v25.5.0

Вычисляет остаток от деления a на b. Аналогична функции positiveModulo, но positiveModuloOrNull возвращает NULL, если операция в противном случае привела бы к исключению с плавающей запятой. Для аргументов с плавающей запятой это происходит только, когда делитель равен 0; для целочисленных аргументов сюда также относится минимальное отрицательное значение по модулю -1 (например, -128 % -1 для Int8).

Синтаксис

positiveModuloOrNull(x, y)

Псевдонимы: positive_modulo_or_null, pmodOrNull

Аргументы

• x — Делимое. (U)Int*/Float32/64. - y — Делитель (модуль). (U)Int*/Float32/64.

Возвращаемое значение

Возвращает разность между x и ближайшим целым числом, не превышающим x и кратным y, или NULL, если операция привела бы к исключению с плавающей запятой: когда делитель равен нулю или, для целочисленных аргументов, при вычислении остатка от минимального отрицательного значения по модулю -1.

Примеры

positiveModuloOrNull при делении на ноль

SELECT positiveModuloOrNull(5, 0)

\N

positiveModuloOrNull для минимального отрицательного целого числа при делении на -1

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

\N

Добавленный в: v26.7.0

Вычисляет квадрат значения x.

Синтаксис

sqr(x)

Аргументы

• x — Значение, возводимое в квадрат. (U)Int* или Float*, или Decimal

Возвращаемое значение

Возвращает произведение x на x.

Примеры

Возведение числа в квадрат

SELECT sqr(5)

25