산술 함수
산술 함수 (Arithmetic Functions)
기본적인 사칙연산과 관련 수학 연산을 수행하는 함수 모음이에요. 숫자 타입 간 연산과 타입 승격 규칙을 제공해요.
출처: 문서
본문
개요 (Overview)
산술 함수는 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
x의 절댓값을 계산해요. x가 부호 없는 타입이면 아무 효과가 없어요. x가 부호 있는 타입이면 부호 없는 숫자를 반환해요.
구문 (Syntax)
abs(x)
반환 값 (Returned value)
x의 절댓값.
예제 (Examples)
SELECT abs(-0.5) -- 0.5
avg2
제공된 인자의 평균값을 계산해 반환해요. 숫자 및 시간 타입을 지원해요.
구문 (Syntax)
avg2(x1, x2])
인자 (Arguments)
x1, x2]— 평균할 두 값을 받아요.
반환 값 (Returned value)
제공된 인자의 평균값으로, 가장 큰 호환 타입으로 승격된 값.
예제 (Examples)
SELECT avg2(toUInt8(3), 1.0) AS result, toTypeName(result) AS type; -- 2, Float64
SELECT avg2(toDate('2025-01-01'), toDate('2025-01-05')) AS result, toTypeName(result) AS type; -- 2025-01-03, Date
byteSwap
정수의 바이트를 뒤집어서 엔디안(endianness)을 바꿔요. 아래 예는 다음과 같이 풀 수 있어요:
- 10진 정수를 빅엔디안 형식의 16진수로 변환: 3351772109 -> C7 C7 FB CD (4바이트)
- 바이트를 뒤집기: C7 C7 FB CD -> CD FB C7 C7
- 결과를 빅엔디안으로 가정해 정수로 변환: CD FB C7 C7 -> 3455829959
이 함수의 사용처 중 하나는 IPv4 뒤집기예요:
┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
│ 199.199.251.205 │
└───────────────────────────────────────────────────────┘
구문 (Syntax)
byteSwap(x)
인자 (Arguments)
x— 정수 값.(U)Int*
반환 값 (Returned value)
바이트가 뒤집힌 x. (U)Int*
예제 (Examples)
SELECT byteSwap(3351772109) -- 3455829959
SELECT byteSwap(54) -- 54
SELECT byteSwap(4135) -- 10000
SELECT byteSwap(123294967295) -- 18439412204227788800
divide
두 값 a와 b의 몫을 계산해요. 결과 타입은 항상 Float64예요. 정수 나눗셈은 intDiv 함수가 제공해요.
0으로 나누면 inf, -inf 또는 nan을 반환해요.
구문 (Syntax)
divide(x, y)
반환 값 (Returned value)
x를 y로 나눈 몫.
예제 (Examples)
SELECT divide(25,5) AS quotient, toTypeName(quotient) -- 5, Float64
SELECT divide(25,0) -- inf
divideDecimal
두 소수(Decimal)에 대해 나눗셈을 수행해요. 결과 값은 Decimal256 타입이 돼요. 결과 스케일은 result_scale 인자(범위 [0, 76]의 상수 정수)로 명시적으로 지정할 수 있어요. 지정하지 않으면 결과 스케일은 주어진 인자의 최대 스케일이 돼요.
이 함수는 일반 divide보다 훨씬 느리게 동작해요. 제어된 정밀도가 꼭 필요하지 않거나 빠른 계산이 필요하다면 divide 사용을 고려하세요.
구문 (Syntax)
divideDecimal(x, y[, result_scale])
반환 값 (Returned value)
주어진 스케일로 나눗셈한 결과. Decimal256
divideOrNull
divide와 같지만 0으로 나누면 NULL을 반환해요.
구문 (Syntax)
divideOrNull(x, y)
반환 값 (Returned value)
x를 y로 나눈 몫, 또는 NULL.
예제 (Examples)
SELECT divideOrNull(25, 0) -- \N
gcd
두 값 a와 b의 최대공약수를 반환해요. 0으로 나누거나 최소 음수를 -1로 나누면 예외가 발생해요.
구문 (Syntax)
gcd(x, y)
반환 값 (Returned value)
x와 y의 최대공약수.
예제 (Examples)
SELECT gcd(12, 18) -- 6
ifNotFinite
부동 소수점 값이 유한한지 확인해요. 삼항 연산자로 비슷한 결과를 얻을 수 있어요: isFinite(x) ? x : y.
구문 (Syntax)
ifNotFinite(x,y)
인자 (Arguments)
반환 값 (Returned value)
x가 유한하면x.x가 유한하지 않으면y.
intDiv
두 값 x를 y로 정수 나눗셈을 수행해요. 즉 몫을 다음 작은 정수로 내림해 계산해요. 결과는 피제수(첫 번째 매개변수)와 같은 너비를 가져요. 0으로 나누거나, 몫이 피제수의 범위에 맞지 않거나, 최소 음수를 -1로 나누면 예외가 발생해요.
구문 (Syntax)
intDiv(x, y)
반환 값 (Returned value)
x와 y의 정수 나눗셈 결과.
예제 (Examples)
SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res) -- 1000, Int64
intDivOrNull
intDiv와 같지만 0으로 나누거나 최소 음수를 -1로 나누면 NULL을 반환해요.
구문 (Syntax)
intDivOrNull(x, y)
반환 값 (Returned value)
x와 y의 정수 나눗셈 결과, 또는 NULL.
intDivOrZero
intDiv와 같지만 0으로 나누거나 최소 음수를 -1로 나누면 0을 반환해요.
구문 (Syntax)
intDivOrZero(a, b)
반환 값 (Returned value)
a와 b의 정수 나눗셈 결과, 또는 0.
isFinite
Float32, Float64 또는 BFloat16 인자가 무한이 아니고 NaN이 아니면 1을 반환하고, 그 외에는 0을 반환해요.
구문 (Syntax)
isFinite(x)
반환 값 (Returned value)
x가 무한이 아니고 NaN이 아니면 1, 그 외에는 0.
예제 (Examples)
SELECT isFinite(inf) -- 0
isInfinite
Float32, Float64 또는 BFloat16 인자가 무한이면 1을 반환하고, 그 외에는 0을 반환해요. NaN에는 0을 반환한다는 점에 유의하세요.
구문 (Syntax)
isInfinite(x)
반환 값 (Returned value)
x가 무한이면 1, 그 외에는 0(NaN 포함).
예제 (Examples)
SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10) -- 1, 0, 0
isNaN
Float32, Float64 또는 BFloat16 인자가 NaN이면 1을 반환하고, 그 외에는 0을 반환해요.
구문 (Syntax)
isNaN(x)
반환 값 (Returned value)
NaN이면 1, 그 외에는 0.
예제 (Examples)
SELECT isNaN(NaN) -- 1
kqlBin
Kusto 쿼리 언어의 bin()처럼 값을 roundTo의 배수로 내림해요. 규칙은 인자 타입에 따라 달라져요: 숫자는 산술적으로, 타임스팬(Interval)은 타임스팬으로, 날짜시간은 타임스팬으로 반올림돼요. KQL 날짜시간은 DateTime64예요. 더 좁은 DateTime과 Date 캐리어는 KQL 날짜시간이 생성할 수 있는 모든 bin을 표현할 수 없으므로 거부돼요. 이 함수는 dialect = 'kusto'일 때 bin()을 뒷받침해요. SQL에서 직접 호출하기 위한 것이 아니에요.
구문 (Syntax)
kqlBin(value, roundTo)
반환 값 (Returned value)
roundTo의 가장 가까운 배수로 내림된 value.
kqlBinAt
Kusto 쿼리 언어의 bin_at()처럼 fixedPoint에서 세는 binSize의 배수로 값을 내림해요. bin은 고정점 앞뒤로 정렬될 수 있어요.
구문 (Syntax)
kqlBinAt(value, binSize, fixedPoint)
반환 값 (Returned value)
fixedPoint에서 세는 binSize의 가장 가까운 배수로 내림된 value.
kqlDateTimeBinAt
날짜시간을 날짜시간 고정점에서 세는 타임스팬 배수로 내림해요.
구문 (Syntax)
kqlDateTimeBinAt(value, binSize, fixedPoint)
반환 값 (Returned value)
반올림된 날짜시간.
kqlDivide
Kusto 쿼리 언어가 정의하는 나눗셈: 두 정수 피연산자는 정수로 나눠 7 / 2는 3이고, 두 타임스팬 피연산자(Interval 값)는 실수 비율로 나눠 15ms / 10ms는 1.5예요. 그 외 피연산자 타입 조합은 divide처럼 나눠요. 이 함수는 dialect = 'kusto'일 때 / 연산자를 뒷받침해요.
구문 (Syntax)
kqlDivide(x, y)
반환 값 (Returned value)
두 인자가 모두 정수면 intDiv(x, y), 둘 다 interval이면 interval 틱의 비율, 그 외에는 divide(x, y).
kqlMultiply
Kusto 쿼리 언어가 정의하는 곱셈: 타임스팬(Interval)은 양쪽 어느 쪽이든 숫자로 스케일돼요, 그래서 2 * 1h는 두 시간이에요. interval이 없는 두 인자는 multiply처럼 곱해요.
구문 (Syntax)
kqlMultiply(x, y)
반환 값 (Returned value)
곱. 어느 한쪽 인자가 interval이면 같은 종류의 interval.
kqlRangeCount
Kusto 쿼리 언어의 range 소스가 생성하는 행 수: floor((to - from) / step) + 1, 그리고 결코 0보다 작지 않아요. 경계와 step은 숫자, 타임스팬(Interval)으로 스텝하는 날짜시간, 또는 타임스팬이에요. 시간 형태는 정수 나노초로 계산되며, 이는 단일 ClickHouse 나눗셈으로 표현되지 않아요. 정수와 소수는 Float64를 통하지 않고 정확히 계산돼요.
구문 (Syntax)
kqlRangeCount(from, to, step)
반환 값 (Returned value)
범위의 값 수.
lcm
두 값 x와 y의 최소공배수를 반환해요. 0으로 나누거나 최소 음수를 -1로 나누면 예외가 발생해요.
구문 (Syntax)
lcm(x, y)
반환 값 (Returned value)
x와 y의 최소공배수. (U)Int*
예제 (Examples)
SELECT lcm(6, 8) -- 24
max2
두 숫자 값 x와 y 중 더 큰 값을 반환해요.
구문 (Syntax)
max2(x, y)
반환 값 (Returned value)
x와 y 중 더 큰 값. Float64
예제 (Examples)
SELECT max2(-1, 2) -- 2
midpoint
제공된 인자의 평균값을 계산해 반환해요. 숫자 및 시간 타입을 지원해요.
구문 (Syntax)
midpoint(x1[, x2, ...])
반환 값 (Returned value)
제공된 인자의 평균값으로, 가장 큰 호환 타입으로 승격된 값.
min2
두 숫자 값 x와 y 중 더 작은 값을 반환해요.
구문 (Syntax)
min2(x, y)
반환 값 (Returned value)
x와 y 중 더 작은 값. Float64
예제 (Examples)
SELECT min2(-1, 2) -- -1
minus
두 값 a와 b의 차를 계산해요. 결과는 항상 부호 있어요. plus와 유사하게 날짜 또는 시간 포함 날짜에서 정수를 뺄 수 있어요. 또한 시간 포함 날짜 간 뺄셈을 지원해서, 그 차이 시간을 결과로 내요. DateTime 또는 DateTime64에서 Time 또는 Time64를 뺄 수도 있어요. 시간 값은 초 단위 오프셋으로 적용돼요. DateTime 빼기 Time은 DateTime을 생성하고, DateTime64 또는 Time64가 포함된 조합은 두 인자의 최대 스케일을 가진 DateTime64를 생성해요.
구문 (Syntax)
minus(x, y)
반환 값 (Returned value)
x 빼기 y.
예제 (Examples)
SELECT minus(10, 5) -- 5
SELECT minus(toDate('2025-01-01'),5) -- 2024-12-27
modulo
두 값 a를 b로 나눈 나머지를 계산해요. 두 입력이 모두 정수면 결과 타입은 정수예요. 입력 중 하나가 부동 소수점이면 결과 타입은 Float64예요. 나머지는 C++처럼 계산돼요. 음수에는 절단 나눗셈이 사용돼요. 0으로 나누거나 최소 음수를 -1로 나누면 예외가 발생해요.
구문 (Syntax)
modulo(a, b)
별칭 (Aliases): mod
반환 값 (Returned value)
a % b의 나머지.
예제 (Examples)
SELECT modulo(5, 2) -- 1
moduloLegacy
나눗셈의 나머지를 계산해요. 이것은 C++ % 연산자를 사용하는 레거시 modulo 구현으로, 음수 인자에 대해 음수 결과를 생성할 수 있어요. 이 함수는 이전 테이블 파티셔닝 로직과의 역호환성을 위해 존재해요. 표준 동작에는 modulo 또는 positiveModulo를 사용하세요.
구문 (Syntax)
moduloLegacy(a, b)
반환 값 (Returned value)
moduloOrNull
a를 b로 나눈 나머지를 계산해요. modulo와 유사하지만, 연산이 그 외에는 부동 소수점 예외를 발생시킬 때 moduloOrNull은 NULL을 반환해요. 부동 소수점 인자의 경우 이는 제수가 0일 때만 발생해요. 정수 인자의 경우 최소 음수 값을 -1로 나눈 경우도 포함돼요(예: Int8의 -128 % -1).
구문 (Syntax)
moduloOrNull(x, y)
별칭 (Aliases): modOrNull
반환 값 (Returned value)
x를 y로 나눈 나머지, 또는 연산이 부동 소수점 예외를 발생시킬 때(제수가 0이거나, 정수 인자의 경우 최소 음수 값을 -1로 나눌 때) NULL.
moduloOrZero
modulo와 같지만 정수 결과의 경우 연산이 그 외에는 예외를 발생시킬 때 예외 대신 0을 반환해요. 부동 소수점 결과의 경우 0 제수는 NaN을 생성해요.
구문 (Syntax)
moduloOrZero(a, b)
반환 값 (Returned value)
a % b의 나머지. 정수 결과의 경우 연산이 예외를 발생시킬 때 0을 반환해요. 부동 소수점 결과의 경우 0 제수는 NaN을 생성해요.
multiply
두 값 x와 y의 곱을 계산해요.
구문 (Syntax)
multiply(x, y)
반환 값 (Returned value)
x와 y의 곱.
예제 (Examples)
SELECT multiply(5,5) -- 25
multiplyDecimal
두 소수(Decimal)에 대해 곱셈을 수행해요. 결과 값은 Decimal256 타입이 돼요. 결과 스케일은 result_scale 인자(범위 [0, 76]의 상수 정수)로 명시적으로 지정할 수 있어요. 지정하지 않으면 결과 스케일은 주어진 인자의 최대 스케일이 돼요.
이 함수들은 일반 multiply보다 훨씬 느리게 동작해요. 제어된 정밀도가 꼭 필요하지 않거나 빠른 계산이 필요하다면 multiply 사용을 고려하세요.
구문 (Syntax)
multiplyDecimal(a, b[, result_scale])
반환 값 (Returned value)
주어진 스케일로 곱셈한 결과. Decimal256
negate
인자 x를 부정해요. 결과는 항상 부호 있어요.
구문 (Syntax)
negate(x)
반환 값 (Returned value)
x에서 -x.
예제 (Examples)
SELECT negate(10) -- -10
plus
두 값 x와 y의 합을 계산해요. 별칭: x + y(연산자). 정수와 날짜 또는 시간 포함 날짜를 더할 수 있어요. 전자는 날짜의 일 수를 증가시키고, 후자는 시간 포함 날짜의 초 수를 증가시켜요. 또한 날짜와 시간을 더할 수 있어요. Date와 Time을 더하면 DateTime이 생성돼요. Date와 Time64, 또는 Date32와 Time 또는 Time64를 더하면 DateTime64가 생성돼요. Time 또는 Time64를 DateTime 또는 DateTime64에 더하면 시간 값을 초 단위 오프셋으로 적용해요. DateTime 더하기 Time은 DateTime을 생성하고, DateTime64 또는 Time64가 포함된 조합은 두 인자의 최대 스케일을 가진 DateTime64를 생성해요.
구문 (Syntax)
plus(x, y)
반환 값 (Returned value)
x와 y의 합.
예제 (Examples)
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
positiveModulo
x를 y로 나눈 나머지를 계산해요. modulo와 유사하지만 positiveModulo는 항상 음수가 아닌 숫자를 반환해요.
구문 (Syntax)
positiveModulo(x, y)
별칭 (Aliases): positive_modulo, pmod
반환 값 (Returned value)
x와 y로 나누어 떨어지는 x보다 크지 않은 가장 가까운 정수와 x의 차이.
예제 (Examples)
SELECT positiveModulo(-1, 10) -- 9
positiveModuloOrNull
a를 b로 나눈 나머지를 계산해요. positiveModulo와 유사하지만, 연산이 그 외에는 부동 소수점 예외를 발생시킬 때 positiveModuloOrNull은 NULL을 반환해요.
구문 (Syntax)
positiveModuloOrNull(x, y)
별칭 (Aliases): positive_modulo_or_null, pmodOrNull
반환 값 (Returned value)
x와 y로 나누어 떨어지는 x보다 크지 않은 가장 가까운 정수와 x의 차이, 또는 연산이 부동 소수점 예외를 발생시킬 때(제수가 0이거나, 정수 인자의 경우 최소 음수 값을 -1로 나눌 때) NULL.
sqr
값 x의 제곱을 계산해요.
구문 (Syntax)
sqr(x)
인자 (Arguments)
반환 값 (Returned value)
x에 자기 자신을 곱한 곱.
예제 (Examples)
SELECT sqr(5) -- 25