형 변환 함수
형 변환 함수 (Type conversion functions)
값을 한 데이터 타입에서 다른 타입으로 변환하는 함수들이에요. to<type> 계열, CAST, accurateCast, reinterpret 계열, 정밀도 있는 날짜/시간 파싱 함수, Unix 타임스탬프 변환 함수 등을 포함합니다. 자료 손실이 발생할 수 있는 변환에 주의가 필요해요.
출처: 문서
본문
데이터 변환 시 흔한 문제 (Common issues with data conversion)
ClickHouse는 일반적으로 C++ 프로그램과 동일한 방식을 따라요. to<type> 함수와 CAST는 어떤 경우 달라지는데, 예를 들어 LowCardinality의 경우 CAST는 LowCardinality 특성을 제거하지만 to<type> 함수는 제거하지 않아요. Nullable도 마찬가지인데, 이 동작은 SQL 표준과 호환되지 않으며 cast_keep_nullable 설정으로 바꿀 수 있어요.
값을 더 작은 데이터 타입(예: Int64 → Int32)이나 호환되지 않는 데이터 타입(예: String → Int)으로 변환하면 데이터가 손실될 수 있으니 주의해야 해요. 결과가 예상대로인지 꼭 확인하세요.
예시:
SELECT
toTypeName(toLowCardinality('') AS val) AS source_type,
toTypeName(toString(val)) AS to_type_result_type,
toTypeName(CAST(val, 'String')) AS cast_result_type
┌─source_type────────────┬─to_type_result_type────┬─cast_result_type─┐
│ LowCardinality(String) │ LowCardinality(String) │ String │
└────────────────────────┴────────────────────────┴──────────────────┘
SELECT
toTypeName(toNullable('') AS val) AS source_type,
toTypeName(toString(val)) AS to_type_result_type,
toTypeName(CAST(val, 'String')) AS cast_result_type
┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String) │ String │
└──────────────────┴─────────────────────┴──────────────────┘
SELECT
toTypeName(toNullable('') AS val) AS source_type,
toTypeName(toString(val)) AS to_type_result_type,
toTypeName(CAST(val, 'String')) AS cast_result_type
SETTINGS cast_keep_nullable = 1
┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String) │ Nullable(String) │
└──────────────────┴─────────────────────┴──────────────────┘
toString 함수에 대한 참고 (Notes on toString functions)
toString 계열 함수는 숫자, 문자열(단, 고정 문자열 제외), 날짜, 날짜와 시간 사이를 변환할 수 있어요. 이 함수들은 모두 인자를 하나 받아요.
- 문자열로/문자열로부터 변환할 때는 값이 TabSeparated 형식(그리고 거의 모든 텍스트 형식)과 동일한 규칙으로 포맷되거나 파싱돼요. 문자열을 파싱할 수 없으면 예외가 발생하고 요청이 취소돼요.
- 날짜를 숫자로 또는 그 반대로 변환할 때, 날짜는 Unix epoch 시작 이후의 일(day) 수로 대응돼요.
- 날짜와 시간을 숫자로 또는 그 반대로 변환할 때, 날짜와 시간은 Unix epoch 시작 이후의 초(second) 수로 대응돼요.
DateTime인자의toString함수는 시간대 이름을 담은 두 번째 String 인자를 받을 수 있어요(예:Europe/Amsterdam). 이 경우 시간은 지정된 시간대에 따라 포맷돼요.
toDate/toDateTime 함수에 대한 참고 (Notes on toDate/toDateTime functions)
toDate/toDateTime 함수의 날짜 및 날짜-시간 형식은 다음과 같이 정의돼요:
YYYY-MM-DD
YYYY-MM-DD hh:mm:ss
예외적으로 UInt32, Int32, UInt64, Int64 숫자 타입에서 Date로 변환할 때 숫자가 65536 이상이면, 그 숫자는 (일 수가 아니라) Unix 타임스탬프로 해석되어 날짜로 반올림돼요.
CAST
도입: v1.1.0
값을 지정된 데이터 타입으로 변환해요. reinterpret 함수와 달리, CAST는 목표 타입에서 동일한 값을 만들어 내려고 해요. 그것이 불가능하면 예외가 발생해요.
구문
CAST(x, T)
or CAST(x AS T)
or x::T
인자
반환값
목표 데이터 타입의 변환된 값을 반환해요. Any
예시 — 기본 사용
SELECT CAST(42, 'String')
┌─CAST(42, 'String')─┐
│ 42 │
└────────────────────┘
AS 구문 사용
SELECT CAST('2025-01-01' AS Date)
┌─CAST('2025-01-01', 'Date')─┐
│ 2025-01-01 │
└────────────────────────────┘
:: 구문 사용
SELECT '123'::UInt32
┌─CAST('123', 'UInt32')─┐
│ 123 │
└───────────────────────┘
DATE
도입: v21.2.0
인자를 Date 데이터 타입으로 변환해요. toDate의 MySQL 호환 별칭이며 toDate와 동일하게 동작해요.
구문
DATE(expr)
인자
반환값 — Date 값. Date
예시
SELECT DATE('2023-01-01')
-- 2023-01-01
accurateCast
도입: v1.1.0
값을 지정된 데이터 타입으로 변환해요. CAST와 달리 accurateCast는 더 엄격한 타입 검사를 수행하며, 변환으로 데이터 정밀도가 손실되거나 변환이 불가능하면 예외를 던져요. 이 함수는 정밀도 손실과 잘못된 변환을 방지하므로 일반 CAST보다 안전해요.
구문
accurateCast(x, T)
인자
반환값 — 목표 데이터 타입의 변환된 값. Any
예시
SELECT accurateCast(42, 'UInt16')
┌─accurateCast(42, 'UInt16')─┐
│ 42 │
└────────────────────────────┘
SELECT accurateCast('123.45', 'Float64')
┌─accurateCast('123.45', 'Float64')─┐
│ 123.45 │
└───────────────────────────────────┘
accurateCastOrDefault
도입: v21.1.0
값을 지정된 데이터 타입으로 변환해요. accurateCast와 같지만, 변환을 정확히 수행할 수 없을 때 예외를 던지는 대신 기본값을 반환해요. 두 번째 인자로 기본값을 주면 반드시 목표 타입이어야 해요. 기본값을 주지 않으면 목표 타입의 기본값이 사용돼요.
구문
accurateCastOrDefault(x, T[, default])
x는 변환할 값(Any), T는 목표 타입 이름(String)이에요. 반환값은 변환된 값입니다. 성공하면 목표 타입, 실패하면 전달된 기본값 또는 0이에요.
accurateCastOrNull
도입: v1.1.0
값을 지정된 데이터 타입으로 변환해요. accurateCast와 같지만, 변환을 정확히 수행할 수 없을 때 예외를 던지는 대신 NULL을 반환해요.
구문
accurateCastOrNull(x, T)
formatRow
도입: v20.7.0
주어진 형식을 통해 임의의 표현식을 문자열로 변환해요. 형식에 접두사/접미사가 포함되어 있으면 각 행마다 쓰여져요. 이 함수에서는 행 기반 형식만 지원돼요.
구문
formatRow(format, x, y, ...)
인자
반환값 — 포맷된 문자열(텍스트 형식에서는 보통 개행 문자로 끝나요). String
예시
SELECT formatRow('CSV', number, 'good')
FROM numbers(3)
┌─formatRow('CSV', number, 'good')─┐
│ 0,"good" ↴│
│ 1,"good" ↴│
│ 2,"good" ↴│
└──────────────────────────────────┘
formatRowNoNewline
도입: v20.7.0
formatRow와 같지만 각 행의 개행 문자를 제거해요. 결과에서 뒤따르는 개행 문자를 제거한다는 점을 제외하면 동일한 동작을 해요.
구문
formatRowNoNewline(format, x, y, ...)
fromUnixTimestamp64Micro
도입: v20.5.0
마이크로초 단위의 Unix 타임스탬프를 마이크로초 정밀도의 DateTime64 값으로 변환해요. 입력값은 마이크로초 정밀도의 Unix 타임스탬프(1970-01-01 00:00:00 UTC 이후의 마이크로초 수)로 처리돼요.
구문
fromUnixTimestamp64Micro(value[, timezone])
인자
반환값 — 마이크로초 정밀도의 DateTime64 값. DateTime64(6)
예시
SELECT fromUnixTimestamp64Micro(1640995200123456)
┌─fromUnixTimestamp64Micro(1640995200123456)─┐
│ 2022-01-01 00:00:00.123456 │
└────────────────────────────────────────────┘
fromUnixTimestamp64Milli
도입: v20.5.0
밀리초 단위의 Unix 타임스탬프를 밀리초 정밀도의 DateTime64 값으로 변환해요. 입력값은 밀리초 정밀도의 Unix 타임스탬프(1970-01-01 00:00:00 UTC 이후의 밀리초 수)로 처리돼요.
구문
fromUnixTimestamp64Milli(value[, timezone])
fromUnixTimestamp64Nano
도입: v20.5.0
나노초 단위의 Unix 타임스탬프를 나노초 정밀도의 DateTime64 값으로 변환해요. 입력값은 나노초 정밀도의 Unix 타임스탬프(1970-01-01 00:00:00 UTC 이후의 나노초 수)로 처리돼요.
구문
fromUnixTimestamp64Nano(value[, timezone])
fromUnixTimestamp64Second
도입: v20.5.0
초 단위의 Unix 타임스탬프를 초 정밀도의 DateTime64 값으로 변환해요. 입력값은 초 단위의 Unix 타임스탬프(1970-01-01 00:00:00 UTC 이후의 초 수)로 처리돼요.
구문
fromUnixTimestamp64Second(value[, timezone])
kqlParameterCast
도입: v26.8.0
값을 여러 후보 타입으로 순서대로 변환해 보는 Kusto Query Language의 parameter_cast() 스타일 기능이에요. dialect = 'kusto'의 Kusto 매개변수 캐스팅에 쓰이며, SQL에서 직접 호출하도록 만들어진 건 아니에요.
kqlToTimespan
도입: v26.8.0
값을 시간 간격(나노초 단위의 Interval)으로 변환해요. Kusto Query Language의 totimespan()과 같은 방식이에요: 시간 간격은 그대로 통과하고, 숫자는 일(day) 수로 세며, 문자열은 [-][d.]hh:mm:ss[.fffffff]로 읽어요 — 파싱에 실패하면 NULL로 변환해요. dialect = 'kusto'일 때 totimespan()을 뒷받침하며, SQL에서 직접 호출하도록 만들어진 건 아니에요.
구문
kqlToTimespan(x)
예시
SELECT kqlToTimespan('0.00:01:00')
-- 60000000000
SELECT kqlToTimespan(2)
-- 172800000000000
parseDateTime
도입: v19.4.0
문자열을 Joda-style 형식의 패턴에 따라 날짜/시간으로 파싱해요. parseDateTime32와 같은 동작을 하는 함수 계열의 기본 형태예요.
구문
parseDateTime(str, pattern[, timezone])
parseDateTime32BestEffort / parseDateTime32BestEffortOrNull / parseDateTime32BestEffortOrZero
파싱에 실패할 확률을 낮추는 best-effort 방식으로 Date/DateTime을 파싱해요. parseDateTime32BestEffort는 성공하지 못한 입력(예: 알 수 없는 형식, 일치하지 않는 문자열)에 대해 예외를 던지고, ...OrNull은 NULL을, ...OrZero는 0000-00-00 또는 1970-01-01 같은 기본값을 반환해요.
구문
parseDateTime32BestEffort(str[, timezone])
parseDateTime32BestEffortOrNull(str[, timezone])
parseDateTime32BestEffortOrZero(str[, timezone])
parseDateTime64
지정된 스케일(소수점 자릿수)과 패턴으로 문자열을 DateTime64로 파싱해요.
구문
parseDateTime64(str, scale[, timezone])
parseDateTime64BestEffort / OrNull / OrZero
DateTime64를 best-effort 방식으로 파싱하며, 파싱 실패 시 각각 예외를 던지거나 NULL 또는 기본값을 반환해요.
구문
parseDateTime64BestEffort(str[, scale[, timezone]])
parseDateTime64BestEffortOrNull(str[, scale[, timezone]])
parseDateTime64BestEffortOrZero(str[, scale[, timezone]])
parseDateTime64BestEffortUS / OrNull / OrZero
미국식 날짜 형식(월/일/년)을 우선하는 best-effort 방식의 DateTime64 파싱 함수에요.
구문
parseDateTime64BestEffortUS(str[, scale[, timezone]])
parseDateTime64BestEffortUSOrNull(str[, scale[, timezone]])
parseDateTime64BestEffortUSOrZero(str[, scale[, timezone]])
parseDateTime64InJodaSyntax / OrNull / OrZero
Joda-style 형식 패턴으로 DateTime64를 파싱해요. 성공 실패 시 각각 예외, NULL, 기본값을 반환해요.
구문
parseDateTime64InJodaSyntax(str, pattern[, timezone])
parseDateTime64InJodaSyntaxOrNull(str, pattern[, timezone])
parseDateTime64InJodaSyntaxOrZero(str, pattern[, timezone])
parseDateTime64OrNull / parseDateTime64OrZero
DateTime64 파싱에 실패하면 각각 NULL 또는 기본값을 반환해요.
구문
parseDateTime64OrNull(str[, scale[, timezone]])
parseDateTime64OrZero(str[, scale[, timezone]])
parseDateTimeBestEffort / OrNull / OrZero
Date/DateTime을 best-effort 방식으로 파싱하고, 실패 시 각각 예외를 던지거나 NULL 또는 기본값을 반환해요.
구문
parseDateTimeBestEffort(str[, timezone])
parseDateTimeBestEffortOrNull(str[, timezone])
parseDateTimeBestEffortOrZero(str[, timezone])
parseDateTimeBestEffortUS / OrNull / OrZero
미국식 날짜 형식(월/일/년)을 우선하는 best-effort 파싱 함수에요.
구문
parseDateTimeBestEffortUS(str[, timezone])
parseDateTimeBestEffortUSOrNull(str[, timezone])
parseDateTimeBestEffortUSOrZero(str[, timezone])
parseDateTimeInJodaSyntax / OrNull / OrZero
Joda-style 형식 패턴으로 파싱하고, 실패 시 각각 예외, NULL, 기본값을 반환해요.
구문
parseDateTimeInJodaSyntax(str, pattern[, timezone])
parseDateTimeInJodaSyntaxOrNull(str, pattern[, timezone])
parseDateTimeInJodaSyntaxOrZero(str, pattern[, timezone])
parseDateTimeOrNull / parseDateTimeOrZero
파싱 실패 시 각각 NULL 또는 기본값을 반환해요.
구문
parseDateTimeOrNull(str[, timezone])
parseDateTimeOrZero(str[, timezone])
reinterpret
도입: v1.1.0
제공된 값 x에 대해 동일한 소스 메모리 바이트 시퀀스를 사용해 목표 타입으로 재해석해요. 목표 타입이 String이면 소스 Array는 요소 타입이 고정 크기이고 메모리에서 연속된 경우에만 지원돼요(예: Array(UInt8) 또는 Array(FixedString(2))). 가변 길이 요소(예: Array(String))나 nullable 요소(예: Array(Nullable(Int32)))의 배열은 지원되지 않아요.
구문
reinterpret(x, type)
| 인자 | 설명 |
|---|---|
x |
재해석할 값. Any |
type |
목표 타입(배열이면 요소 타입이 고정 길이여야 함). String |
예시
SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
reinterpret(toInt8(1), 'Float32') AS int_to_float,
reinterpret('1', 'UInt32') AS string_to_int
┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│ 255 │ 1e-45 │ 49 │
└─────────────┴──────────────┴───────────────┘
SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32
┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626] │
└────────────────────────────┘
SELECT hex(reinterpret([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8), 'String')) AS array_of_UInt8_to_string
┌─array_of_UInt8_to_string─┐
│ 0102FF │
└──────────────────────────┘
reinterpretAsDate
도입: v1.1.0
입력값을 Date 값으로 재해석해요(리틀 엔디언 순서로 가정). Unix epoch(1970-01-01) 시작 이후의 일 수예요.
구문
reinterpretAsDate(x)
예시
SELECT reinterpretAsDate(65), reinterpretAsDate('A')
┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│ 1970-03-07 │ 1970-03-07 │
└───────────────────────┴────────────────────────┘
reinterpretAsDateTime
도입: v1.1.0
입력값을 DateTime 값으로 재해석해요(리틀 엔디언 순서로 가정). Unix epoch(1970-01-01) 시작 이후의 초 수예요.
구문
reinterpretAsDateTime(x)
reinterpretAsFixedString
도입: v1.1.0
입력값을 고정 길이 문자열(FixedString)로 재해석해요.
구문
reinterpretAsFixedString(x)
reinterpretAsFloat32 / reinterpretAsFloat64
각각 입력값을 Float32/Float64 값으로 재해석해요.
구문
reinterpretAsFloat32(x)
reinterpretAsFloat64(x)
reinterpretAsInt128 / reinterpretAsInt16 / reinterpretAsInt256 / reinterpretAsInt32 / reinterpretAsInt64 / reinterpretAsInt8
각각 입력값을 Int128/Int16/Int256/Int32/Int64/Int8 값으로 재해석해요.
구문
reinterpretAsInt128(x)
reinterpretAsInt16(x)
reinterpretAsInt256(x)
reinterpretAsInt32(x)
reinterpretAsInt64(x)
reinterpretAsInt8(x)
reinterpretAsString
도입: v1.1.0
입력값을 String 값으로 재해석해요. 내부의 원래 바이트가 보존돼요.
구문
reinterpretAsString(x)
reinterpretAsUInt128 / reinterpretAsUInt16 / reinterpretAsUInt256 / reinterpretAsUInt32 / reinterpretAsUInt64 / reinterpretAsUInt8
각각 입력값을 UInt128/UInt16/UInt256/UInt32/UInt64/UInt8 값으로 재해석해요.
구문
reinterpretAsUInt128(x)
reinterpretAsUInt16(x)
reinterpretAsUInt256(x)
reinterpretAsUInt32(x)
reinterpretAsUInt64(x)
reinterpretAsUInt8(x)
reinterpretAsUUID
도입: v1.1.0
입력값을 UUID로 재해석해요. 입력의 16바이트를 UUID의 바이트로 사용해요.
구문
reinterpretAsUUID(x)
toBFloat16
도입: v25.2.0
입력값을 BFloat16 값으로 변환해요.
구문
toBFloat16(expr)
toBFloat16OrNull
도입: v25.5.0
toBFloat16와 같지만 변환 오류 시 NULL을 반환해요.
구문
toBFloat16OrNull(expr)
toBFloat16OrZero
도입: v25.5.0
toBFloat16와 같지만 변환 오류 시 기본값(0)을 반환해요.
구문
toBFloat16OrZero(expr)
toBool
도입: v22.2.0
입력값을 Bool 타입으로 변환해요. 문자열의 경우 'true' 또는 'false'(대소문자 무시)를 받아요.
구문
toBool(expr)
예시
SELECT
toBool(toUInt8(1)),
toBool(toInt8(-1)),
toBool(toFloat32(1.01)),
toBool('true'),
toBool('false'),
toBool('FALSE')
FORMAT Vertical
Row 1:
──────
toBool(toUInt8(1)): true
toBool(toInt8(-1)): true
toBool(toFloat32(1.01)): true
toBool('true'): true
toBool('false'): false
toBool('FALSE'): false
toDate
도입: v1.1.0
입력값을 Date 타입으로 변환해요. String, FixedString, DateTime, 숫자 타입에서의 변환을 지원해요.
구문
toDate(x)
예시
SELECT toDate('2025-04-15')
-- 2025-04-15
toDate32
도입: v20.5.0
입력값을 Date32 타입으로 변환해요. Date보다 넓은 범위(1900-01-01 ~ 2299-12-31)를 지원해요.
구문
toDate32(x[, timezone])
toDate32OrDefault / toDate32OrNull / toDate32OrZero
toDate32와 같지만 변환 실패 시 각각 기본값, NULL, 0(또는 0000-00-00)을 반환해요.
구문
toDate32OrDefault(expr[, default])
toDate32OrNull(expr)
toDate32OrZero(expr)
toDateOrDefault / toDateOrNull / toDateOrZero
toDate와 같지만 변환 실패 시 각각 기본값, NULL, 0을 반환해요.
구문
toDateOrDefault(expr[, default])
toDateOrNull(expr)
toDateOrZero(expr)
toDateTime
도입: v1.1.0
입력값을 DateTime 타입으로 변환해요.
expr이 숫자면 Unix epoch 시작 이후의 초 수(Unix 타임스탬프)로 해석돼요. expr이 String이면 Unix 타임스탬프 또는 날짜/날짜-시간의 문자열 표현으로 해석돼요. 따라서 짧은 숫자 문자열 표현(최대 4자리)의 파싱은 모호성 때문에 명시적으로 비활성화돼요 — 예를 들어 문자열 '1999'는 연도일 수도 있고 Unix 타임스탬프일 수도 있어요. 더 긴 숫자 문자열은 허용돼요.
expr이 Time 또는 Time64 값이면 Unix epoch 시작 이후의 초 수로 해석돼요. Time64의 소수 부분은 음의 무한 방향으로 내림되고, DateTime 범위 밖의 값은 date_time_overflow_behavior 설정에 따릅니다.
구문
toDateTime(expr[, time_zone])
예시
SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT Vertical
Row 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'): 2025-01-01 00:00:00
toDateTime32
도입: v20.9.0
입력값을 DateTime 타입으로 변환해요. DateTime32는 DateTime의 별칭이며 1970-01-01 00:00:00 ~ 2106-02-07 06:28:15 범위의 날짜를 지원해요. Decimal 값은 지원되지 않으며 예외가 발생해요.
구문
toDateTime32(x[, timezone])
toDateTime64
도입: v20.1.0
입력값을 DateTime64 타입의 값으로 변환해요. 정밀도(소수점 자릿수)를 지정할 수 있어요.
구문
toDateTime64(expr, scale[, timezone])
toDateTime64OrDefault / toDateTime64OrNull / toDateTime64OrZero
toDateTime64와 같지만 변환 실패 시 각각 기본값, NULL, 기본값을 반환해요.
구문
toDateTime64OrDefault(expr, scale[, timezone, default])
toDateTime64OrNull(expr, scale[, timezone])
toDateTime64OrZero(expr, scale[, timezone])
toDateTimeOrDefault / toDateTimeOrNull / toDateTimeOrZero
toDateTime와 같지만 변환 실패 시 각각 기본값, NULL, 0을 반환해요.
구문
toDateTimeOrDefault(expr[, timezone, default])
toDateTimeOrNull(expr[, timezone])
toDateTimeOrZero(expr[, timezone])
toDecimal128 / toDecimal128OrDefault / toDecimal128OrNull / toDecimal128OrZero
Decimal(38, S) 타입으로 변환하는 함수들이에요. S는 스케일(소수점 자릿수)로 두 번째 인자로 지정해요. ...OrDefault/...OrNull/...OrZero 변형은 실패 시 각각 기본값, NULL, 0을 반환해요.
구문
toDecimal128(expr, S)
toDecimal128OrDefault(expr, S[, default])
toDecimal128OrNull(expr, S)
toDecimal128OrZero(expr, S)
toDecimal256 / toDecimal256OrDefault / toDecimal256OrNull / toDecimal256OrZero
Decimal(76, S) 타입으로 변환하는 함수들이에요.
구문
toDecimal256(expr, S)
toDecimal256OrDefault(expr, S[, default])
toDecimal256OrNull(expr, S)
toDecimal256OrZero(expr, S)
toDecimal32 / toDecimal32OrDefault / toDecimal32OrNull / toDecimal32OrZero
Decimal(9, S) 타입으로 변환하는 함수들이에요.
구문
toDecimal32(expr, S)
toDecimal32OrDefault(expr, S[, default])
toDecimal32OrNull(expr, S)
toDecimal32OrZero(expr, S)
toDecimal64 / toDecimal64OrDefault / toDecimal64OrNull / toDecimal64OrZero
Decimal(18, S) 타입으로 변환하는 함수들이에요.
구문
toDecimal64(expr, S)
toDecimal64OrDefault(expr, S[, default])
toDecimal64OrNull(expr, S)
toDecimal64OrZero(expr, S)
toDecimalString
도입: v23.3.0
숫자 값을 지정된 소수점 자릿수의 String으로 변환해요. 입력값을 지정된 소수 자리 수로 반올림하며, 요청된 수보다 소수 자리가 적으면 결과에 0을 채워 정확한 자릿수를 맞춰요.
구문
toDecimalString(number, scale)
예시
SELECT toDecimalString(2.1456, 2)
-- 2.15
SELECT toDecimalString(5, 3)
-- 5.000
toFixedString
도입: v1.1.0
String 인자를 FixedString(N) 타입으로 변환해요. 변환 중인 문자열보다 N이 작으면 오류가 발생해요.
구문
toFixedString(s, N)
toFloat32 / toFloat32OrDefault / toFloat32OrNull / toFloat32OrZero
각각 입력값을 Float32로 변환하며, ...OrDefault는 실패 시 기본값을, ...OrNull은 NULL을, ...OrZero는 0을 반환해요.
구문
toFloat32(expr)
toFloat32OrDefault(expr[, default])
toFloat32OrNull(expr)
toFloat32OrZero(expr)
toFloat64 / toFloat64OrDefault / toFloat64OrNull / toFloat64OrZero
각각 입력값을 Float64로 변환하는 함수들이에요.
구문
toFloat64(expr)
toFloat64OrDefault(expr[, default])
toFloat64OrNull(expr)
toFloat64OrZero(expr)
toInt128 / toInt128OrDefault / toInt128OrNull / toInt128OrZero
각각 입력값을 Int128로 변환하는 함수들이에요.
구문
toInt128(expr)
toInt128OrDefault(expr[, default])
toInt128OrNull(expr)
toInt128OrZero(expr)
toInt16 / toInt16OrDefault / toInt16OrNull / toInt16OrZero
각각 입력값을 Int16로 변환하는 함수들이에요.
구문
toInt16(expr)
toInt16OrDefault(expr[, default])
toInt16OrNull(expr)
toInt16OrZero(expr)
toInt256 / toInt256OrDefault / toInt256OrNull / toInt256OrZero
각각 입력값을 Int256로 변환하는 함수들이에요.
구문
toInt256(expr)
toInt256OrDefault(expr[, default])
toInt256OrNull(expr)
toInt256OrZero(expr)
toInt32 / toInt32OrDefault / toInt32OrNull / toInt32OrZero
각각 입력값을 Int32로 변환하는 함수들이에요.
구문
toInt32(expr)
toInt32OrDefault(expr[, default])
toInt32OrNull(expr)
toInt32OrZero(expr)
toInt64 / toInt64OrDefault / toInt64OrNull / toInt64OrZero
각각 입력값을 Int64로 변환하는 함수들이에요.
구문
toInt64(expr)
toInt64OrDefault(expr[, default])
toInt64OrNull(expr)
toInt64OrZero(expr)
toInt8
도입: v1.1.0
입력값을 Int8 타입의 값으로 변환해요. 오류가 있으면 예외를 던져요.
지원되는 인자:
- (U)Int* 타입의 값 또는 문자열 표현.
- Float* 타입의 값.
지원되지 않는 인자:
NaN및Inf를 포함한 Float* 값의 문자열 표현.- 이진/16진수 값의 문자열 표현 (예:
SELECT toInt8('0xc0fe');).
입력값이 Int8 범위 안에 표현될 수 없으면 결과의 오버플로/언더플로가 발생해요. 이것은 오류로 간주되지 않아요. 예: SELECT toInt8(128) == -128;.
이 함수는 숫자의 소수 자릿수를 자르는 0 방향 반올림을 사용해요.
구문
toInt8(expr)
예시
SELECT
toInt8(-8),
toInt8(-8.8),
toInt8('-8')
FORMAT Vertical
Row 1:
──────
toInt8(-8): -8
toInt8(-8.8): -8
toInt8('-8'): -8
toInt8OrDefault
도입: v21.11.0
toInt8처럼 입력값을 Int8로 변환하지만 오류 시 기본값을 반환해요. default 값을 전달하지 않으면 오류 시 0을 반환해요.
구문
toInt8OrDefault(expr[, default])
예시
SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))
-- -8
SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))
-- -1
toInt8OrNull
도입: v1.1.0
toInt8처럼 변환하지만 오류 시 NULL을 반환해요.
구문
toInt8OrNull(expr)
toInt8OrZero
도입: v1.1.0
toInt8처럼 변환하지만 오류 시 0을 반환해요.
구문
toInt8OrZero(expr)
toInterval
도입: v24.10.0
인자를 Interval 데이터 타입으로 변환해요. MySQL 호환 별칭으로, 인자와 단위로부터 간격을 만들어요.
구문
toInterval(value)
toIntervalDay
숫자를 일(day) 단위의 Interval로 변환해요.
구문
toIntervalDay(x)
toIntervalHour
숫자를 시간 단위의 Interval로 변환해요.
toIntervalHour(x)
toIntervalMicrosecond
숫자를 마이크로초 단위의 Interval로 변환해요.
toIntervalMicrosecond(x)
toIntervalMillisecond
숫자를 밀리초 단위의 Interval로 변환해요.
toIntervalMillisecond(x)
toIntervalMinute
숫자를 분 단위의 Interval로 변환해요.
toIntervalMinute(x)
toIntervalMonth
숫자를 월 단위의 Interval로 변환해요.
toIntervalMonth(x)
toIntervalNanosecond
숫자를 나노초 단위의 Interval로 변환해요.
toIntervalNanosecond(x)
toIntervalQuarter
숫자를 분기 단위의 Interval로 변환해요.
toIntervalQuarter(x)
toIntervalSecond
숫자를 초 단위의 Interval로 변환해요.
toIntervalSecond(x)
toIntervalWeek
숫자를 주 단위의 Interval로 변환해요.
toIntervalWeek(x)
toIntervalYear
숫자를 년 단위의 Interval로 변환해요.
toIntervalYear(x)
toLowCardinality
입력값을 LowCardinality 버전의 동일 데이터 타입으로 변환해요. LowCardinality 열의 처리 속도를 높이기 위해, 카디널리티가 낮은 데이터의 처리를 더 빨리 만들어줘요.
구문
toLowCardinality(value)
toString
도입: v1.1.0
값을 문자열 표현으로 변환해요. DateTime 인자의 경우 시간대 이름을 담은 두 번째 String 인자를 받을 수 있어요.
구문
toString(value[, timezone])
예시
SELECT
now() AS ts,
time_zone,
toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10
toStringCutToZero
도입: v1.1.0
String 또는 FixedString 인자를 받아 첫 번째 널 바이트에서 잘린 원본 문자열의 복사본을 포함하는 String을 반환해요. 널 바이트(\0)는 문자열 종결자로 간주돼요. 이 함수는 널 바이트가 의미 있는 내용의 끝을 표시하는 C 스타일 문자열이나 이진 데이터를 처리할 때 유용해요.
구문
toStringCutToZero(s)
예시
SELECT
toStringCutToZero('hello'),
toStringCutToZero('hello\0world')
┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\0world')─┐
│ hello │ hello │
└────────────────────────────┴───────────────────────────────────┘
toTime
도입: v25.5.0
입력값을 Time 타입으로 변환해요. String, FixedString, DateTime, DateTime64, Time64 또는 자정 이후의 초 수를 나타내는 숫자 타입에서의 변환을 지원해요.
Time 타입 범위 밖의 숫자 값(-999:59:59 ~ 999:59:59, 즉 -3599999 ~ 3599999 초)은 범위 경계로 포화(saturate)되며, NaN, inf, -inf 같은 비유한 부동소수점 값은 변환할 수 없어 예외가 발생해요.
v25.5 이전의 toTime은 날짜-시간을 고정 날짜(1970-01-02)로 변환하면서 시간 성분을 보존하는 다른 함수였어요. 그 함수는 이제 toTimeWithFixedDate라는 이름으로 여전히 사용 가능해요. use_legacy_to_time 설정을 1로 하면 toTime 이름이 레거시 함수에 바인딩돼요. 이 설정은 v26.7부터 기본값이 0이지만, v25.6~v26.6에는 기본값이 1이었기 때문에 아래 예시는 명시적으로 설정해요.
구문
toTime(x)
예시
SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime64('2025-04-15 14:30:25.123', 3))
-- 14:30:25
toTime64
도입: v25.5.0
입력값을 Time64 타입으로 변환해요(초와 마이크로초 정밀도를 갖는 시간).
구문
toTime64(x[, precision])
toTime64OrNull / toTime64OrZero
toTime처럼 변환하지만 오류 시 각각 NULL 또는 기본값을 반환해요.
구문
toTime64OrNull(x)
toTime64OrZero(x)
toTimeOrNull / toTimeOrZero
toTime처럼 변환하지만 오류 시 각각 NULL 또는 기본값(00:00:00)을 반환해요.
구문
toTimeOrNull(x[, precision])
toTimeOrZero(x[, precision])
toUInt128 / toUInt128OrDefault / toUInt128OrNull / toUInt128OrZero
각각 입력값을 UInt128로 변환하는 함수들이에요.
구문
toUInt128(expr)
toUInt128OrDefault(expr[, default])
toUInt128OrNull(expr)
toUInt128OrZero(expr)
toUInt16 / toUInt16OrDefault / toUInt16OrNull / toUInt16OrZero
각각 입력값을 UInt16로 변환하는 함수들이에요.
구문
toUInt16(expr)
toUInt16OrDefault(expr[, default])
toUInt16OrNull(expr)
toUInt16OrZero(expr)
toUInt256 / toUInt256OrDefault / toUInt256OrNull / toUInt256OrZero
각각 입력값을 UInt256로 변환하는 함수들이에요.
구문
toUInt256(expr)
toUInt256OrDefault(expr[, default])
toUInt256OrNull(expr)
toUInt256OrZero(expr)
toUInt32 / toUInt32OrDefault / toUInt32OrNull / toUInt32OrZero
각각 입력값을 UInt32로 변환하는 함수들이에요.
구문
toUInt32(expr)
toUInt32OrDefault(expr[, default])
toUInt32OrNull(expr)
toUInt32OrZero(expr)
toUInt64 / toUInt64OrDefault / toUInt64OrNull / toUInt64OrZero
각각 입력값을 UInt64로 변환하는 함수들이에요.
구문
toUInt64(expr)
toUInt64OrDefault(expr[, default])
toUInt64OrNull(expr)
toUInt64OrZero(expr)
toUInt8 / toUInt8OrDefault / toUInt8OrNull / toUInt8OrZero
각각 입력값을 UInt8로 변환하는 함수들이에요.
구문
toUInt8(expr)
toUInt8OrDefault(expr[, default])
toUInt8OrNull(expr)
toUInt8OrZero(expr)
toUUID
도입: v1.1.0
String 값을 UUID 값으로 변환해요.
구문
toUUID(string)
예시
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
┌─uuid─────────────────────────────────┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
toUUIDOrZero
도입: v20.12.0
입력값을 UUID 타입으로 변환하지만 오류 시 0 UUID를 반환해요. toUUID와 같지만 변환 오류 시 예외를 던지는 대신 0 UUID(00000000-0000-0000-0000-000000000000)를 반환해요.
구문
toUUIDOrZero(string)
toUnixTimestamp64Micro
도입: v20.5.0
DateTime64를 고정 마이크로초 정밀도의 Int64 값으로 변환해요. 입력값은 그 정밀도에 따라 적절히 확대/축소돼요. 출력값은 UTC 기준이며 입력값의 시간대 기준이 아니에요.
구문
toUnixTimestamp64Micro(value)
toUnixTimestamp64Milli
도입: v20.5.0
DateTime64를 고정 밀리초 정밀도의 Int64 값으로 변환해요. 출력값은 UTC 기준이에요.
구문
toUnixTimestamp64Milli(value)
예시
WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);
┌─toUnixTimestamp64Milli(dt64)─┐
│ 1739489491011 │
└──────────────────────────────┘
toUnixTimestamp64Nano
도입: v20.5.0
DateTime64를 고정 나노초 정밀도의 Int64 값으로 변환해요. 출력값은 UTC 기준이에요.
구문
toUnixTimestamp64Nano(value)
toUnixTimestamp64Second
도입: v20.5.0
DateTime64를 고정 초 정밀도의 Int64 값으로 변환해요. 출력값은 UTC 기준이에요.
구문
toUnixTimestamp64Second(value)