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

Обзор

Арифметические функции работают для любых двух операндов типов UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, Float32 или Float64.

Перед выполнением операции оба операнда приводятся к типу результата. Тип результата определяется следующим образом (если иное не указано в документации по функции ниже):

Если оба операнда имеют разрядность не более 32 бит, размер типа результата будет равен размеру следующего более крупного типа по сравнению с большим из двух операндов (promotion целочисленного размера). Например, 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) │
└────────┴───────────────┘

Типы данных 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).

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

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

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

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

Получено исключение от сервера (версия 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

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

Синтаксис

isFinite(x)

Аргументы

x — число, проверяемое на конечность. Float*

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

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

Примеры

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

SELECT isFinite(inf)

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)

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

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

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.

Возвращает наименьшее из двух числовых значений 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, за исключением того, что 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)

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. Масштаб результата (scale) может быть явно задан аргументом 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 │
└──────────────────────────────────────────────────────────────────┘

Переполнение десятичного типа

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: Переполнение при арифметической операции с типом Decimal:
При обработке toDecimal64(-12.647987876, 9) AS a, toDecimal64(123.967645643, 9) AS b, a * b. (DECIMAL_OVERFLOW)

negate

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

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

Синтаксис

negate(x)

Аргументы

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, за исключением того, что 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

Обзор​

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