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

Обзор

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

Вычисляет абсолютное значение 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;
-- The type returned is a Float64 as the UInt8 must be promoted to 64 bit for the comparison.

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

Десятичные типы данных

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

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

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

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

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

Выполняет деление двух десятичных чисел. Результирующее значение будет типа Decimal256. Масштаб результата может быть явно задан аргументом result_scale (константа Integer в диапазоне [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)

6

ifNotFinite

Введена в версии v20.3

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

Аналогичного результата можно добиться с помощью тернарного оператора: 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

intDiv

Добавлено в: v1.1

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

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

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

Синтаксис

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)

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

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

0

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

SELECT intDivOrZero(0.05, -1)

0

isFinite

Добавлена в версии: v1.1

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

Синтаксис

isFinite(x)

Аргументы

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

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

1, если x конечно и не равно NaN, в противном случае 0.

Примеры

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

SELECT isFinite(inf)

0

isInfinite

Введена в версии: v1.1

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

Синтаксис

isInfinite(x)

Аргументы

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

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

1, если x является бесконечным числом, иначе 0 (включая случай NaN).

Примеры

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

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

1 0 0

isNaN

Введено в: v1.1

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

Синтаксис

isNaN(x)

Аргументы

• x — Аргумент, проверяемый на значение NaN. Float*

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

1, если NaN, иначе 0

Примеры

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

SELECT isNaN(NaN)

1

lcm

Добавлено в: v1.1

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

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

Синтаксис

lcm(x, y)

Аргументы

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

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

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

Примеры

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

SELECT lcm(6, 8)

24

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)

2

midpoint

Введена в версии v25.11

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

Синтаксис

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

Аргументы

• x1[, x2, ...] — Принимает одно или несколько значений для вычисления среднего.

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

Возвращает среднее значение переданных аргументов, приведённое к наибольшему совместимому типу.

Примеры

Числовые типы

SELECT midpoint(1, toUInt8(3), 0.5) AS result, toTypeName(result) AS type;
-- The type returned is a Float64 as the UInt8 must be promoted to 64 bit for the comparison.

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

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)

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)

1

moduloLegacy

Введена в версии: v1.1

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

Синтаксис

moduloLegacy(a, b)

Аргументы

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

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

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

Примеры

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

SELECT moduloLegacy(10, 3)

1

moduloOrNull

Добавлена в версии: v25.5

Вычисляет остаток от деления a на b. Аналогична функции modulo, за исключением того, что moduloOrNull возвращает NULL, если правый аргумент равен 0.

Синтаксис

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)

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)

25

multiplyDecimal

Добавлено в: v22.12

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

Примечание

Эти функции работают значительно медленнее, чем обычная 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 │
└───────────────┴───────────────┴───────────────────────────────────────────────────────────────────────────────┘
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

Изменяет знак аргумента 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)

10

Сложение целого числа с датой

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)

9

positiveModuloOrNull

Добавлена в: v25.5

Вычисляет остаток от деления a на b. Аналогична функции positiveModulo, за исключением того, что positiveModuloOrNull вернёт NULL, если правый аргумент равен 0.

Синтаксис

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