인코딩 함수

인코딩 함수 (Encoding functions)

데이터를 다양한 형식(이진, 16진수, Bech32, Hilbert/Morton 곡선, sqid 등)으로 인코딩·디코딩하는 함수 모음이에요.

출처: 문서

본문

bech32Decode

Bech32 또는 Bech32m 알고리즘으로 생성된 Bech32 주소 문자열을 디코딩해요. encode 함수와 달리, bech32Decode는 패딩된 FixedStrings를 자동으로 처리해요.

구문 (Syntax)

bech32Decode(address[, 'raw'])

인자 (Arguments)

• address — 디코딩할 Bech32 문자열. String 또는 FixedString
• mode — 선택 사항. 첫 번째 바이트를 witness 버전으로 떼어내지 않고 디코딩하려면 'raw'를 전달해요. 비-SegWit 주소(예: Cosmos SDK)에 사용해요. String

반환 값 (Returned value)

문자열을 인코딩하는 데 사용된 (hrp, data) 튜플을 반환해요. data는 이진 형식이에요. Tuple(String, String)

예제 (Examples)

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4') AS tup)

응답: {hrp: "bc", data: "751E76E8199196D454941C45D1B3A323F1433BD6"}

bech32Encode

Bech32 또는 Bech32m 알고리즘을 사용해 이진 데이터 문자열과 사람이 읽을 수 있는 부분(HRP)을 인코딩해요.

FixedString 데이터 타입을 사용할 때 값이 행을 완전히 채우지 않으면 null 문자로 패딩돼요. bech32Encode 함수는 hrp 인자에서는 이를 자동으로 처리하지만, data 인자에서는 값이 패딩되지 않아야 해요. 그래서 데이터 값에 FixedString 타입을 사용하는 것은 값이 모두 같은 길이이고 FixedString 컬럼이 그 길이로 설정되도록 보장하지 않는 한 권장하지 않아요.

구문 (Syntax)

bech32Encode(hrp, data[, witver | 'bech32' | 'bech32m'])

인자 (Arguments)

• hrp — 코드의 "사람이 읽을 수 있는 부분"을 지정하는 1 - 83 소문자로 된 문자열. 보통 'bc' 또는 'tb'. String 또는 FixedString
• data — 인코딩할 이진 데이터 문자열. String 또는 FixedString
• witver_or_variant — 선택 사항. UInt* witness 버전(기본값 = 1, Bech32는 0, Bech32m은 1+) 또는 문자열 인코딩 변형: 'bech32'(BIP173) 또는 'bech32m'(BIP350). 문자열 변형을 사용하면 witness 버전 바이트가 붙지 않아요 — Cosmos SDK 같은 비-SegWit 주소에 필요해요. UInt* 또는 String

반환 값 (Returned value)

사람이 읽을 수 있는 부분, 항상 '1'인 구분 문자, 데이터 부분으로 구성된 Bech32 주소 문자열을 반환해요. 문자열 길이는 90자를 넘지 않아요. 알고리즘이 입력에서 유효한 주소를 생성할 수 없으면 빈 문자열을 반환해요. String

예제 (Examples)

-- When no witness version is supplied, the default is 1, the updated Bech32m algorithm.
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'))

응답: bc1pw508d6qejxtdg4y5r3zarvary0c5xw7kj9wkru

bin

인자에 따라 다른 논리로 이진 표현을 담은 문자열을 반환해요:

타입	설명
(U)Int*	가장 중요한(큰 자리) 비트부터 가장 작은 비트까지 이진 숫자를 출력해요(빅엔디안 또는 "사람이 읽을 수 있는" 순서). 가장 중요한 0이 아닌 바이트에서 시작하지만(앞의 0 바이트는 생략), 앞자리가 0이면 항상 각 바이트의 8자리를 출력해요.
Date와 DateTime	해당 정수로 포맷돼요(Date는 epoch 이후 일수, DateTime은 unix 타임스탬프 값).
String과 FixedString	모든 바이트가 8개의 이진 숫자로 인코딩돼요. 0 바이트는 생략되지 않아요.
Float*와 Decimal	메모리 표현대로 인코딩돼요. 리틀엔디언 아키텍처를 지원하므로 리틀엔디언으로 인코딩돼요. 앞/뒤 0 바이트는 생략되지 않아요.
UUID	빅엔디언 순서 문자열로 인코딩돼요.

구문 (Syntax)

bin(arg)

인자 (Arguments)

• arg — 이진으로 변환할 값. String, FixedString, (U)Int*, Float*, Decimal, Date 또는 DateTime

반환 값 (Returned value)

인자의 이진 표현을 담은 문자열. String

예제 (Examples)

SELECT bin(14)

응답: 00001110

bitPositionsToArray

부호 없는 정수의 이진 표현에서 1 비트의 위치를(오름차순으로) 반환해요. 부호 있는 입력 정수는 먼저 부호 없는 정수로 캐스팅돼요.

구문 (Syntax)

bitPositionsToArray(arg)

인자 (Arguments)

• arg — 정수 값. (U)Int*

반환 값 (Returned value)

입력의 이진 표현에서 1 비트의 위치를 오름차순으로 담은 배열. Array(UInt64)

예제 (Examples)

SELECT bitPositionsToArray(toInt8(1)) AS bit_positions;  -- [0]
SELECT bitPositionsToArray(toInt8(-1)) AS bit_positions;  -- [0,1,2,3,4,5,6,7]

bitmaskToArray

정수를 2의 거듭제곱의 합으로 분해해요. 2의 거듭제곱은 오름차순으로 정렬된 배열로 반환돼요.

구문 (Syntax)

bitmaskToArray(num)

인자 (Arguments)

• num — 정수 값. (U)Int*

반환 값 (Returned value)

입력 숫자에 합해지는 2의 거듭제곱을 오름차순으로 담은 배열. Array(UInt64)

예제 (Examples)

SELECT bitmaskToArray(50) AS powers_of_two;  -- [2,16,32]
SELECT bitmaskToArray(8) AS powers_of_two;   -- [8]

bitmaskToList

bitmaskToArray와 같지만 2의 거듭제곱을 쉼표로 구분된 문자열로 반환해요.

구문 (Syntax)

bitmaskToList(num)

인자 (Arguments)

• num — 정수 값. (U)Int*

반환 값 (Returned value)

쉼표로 구분된 2의 거듭제곱을 담은 문자열. String

예제 (Examples)

SELECT bitmaskToList(50) AS powers_list;  -- 2,16,32

char

전달된 인자의 개수와 같은 길이의 문자열을 반환하며, 각 바이트는 해당 인자의 값을 가져요. 숫자 타입의 여러 인자를 받아요. 인자 값이 UInt8 타입의 범위를 벗어나면 반올림과 오버플로 가능성과 함께 UInt8로 변환돼요.

구문 (Syntax)

char(num1[, num2[, ...]])

인자 (Arguments)

• num1[, num2[, num3 ...]] — 정수로 해석되는 숫자 인자. (U)Int8/16/32/64 또는 Float*

반환 값 (Returned value)

주어진 바이트의 문자열. String

예제 (Examples)

SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;  -- hello
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;  -- привет

hex

인자에 따라 다른 논리로 인자의 16진수 표현을 담은 문자열을 반환해요:

타입	설명
(U)Int*	가장 중요한(큰 자리) 것부터 가장 작은 것까지 16진수 숫자("니블")를 출력해요(빅엔디안 또는 "사람이 읽을 수 있는" 순서). 가장 중요한 0이 아닌 바이트에서 시작하지만(앞의 0 바이트는 생략), 앞자리가 0이어도 항상 각 바이트의 두 자리를 출력해요.
Date와 DateTime	해당 정수로 포맷돼요.
String과 FixedString	모든 바이트가 두 개의 16진수 숫자로 인코딩돼요. 0 바이트는 생략되지 않아요.
Float*와 Decimal	메모리 표현대로 인코딩돼요. ClickHouse는 값을 내부적으로 항상 리틀엔디언으로 표현하므로 그렇게 인코딩돼요. 앞/뒤 0 바이트는 생략되지 않아요.
UUID	빅엔디언 순서 문자열로 인코딩돼요.

함수는 대문자 A-F를 사용하며, 어떤 접두사(0x 같은)나 접미사(h 같은)도 사용하지 않아요.

구문 (Syntax)

hex(arg)

인자 (Arguments)

• arg — 16진수로 변환할 값. String, (U)Int*, Float*, Decimal, Date 또는 DateTime

반환 값 (Returned value)

인자의 16진수 표현을 담은 문자열. String

예제 (Examples)

SELECT hex(1)  -- 01
SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2)

hilbertDecode

Hilbert 곡선 인덱스를 다차원 공간의 좌표를 나타내는 부호 없는 정수의 튜플로 다시 디코딩해요. hilbertEncode 함수와 마찬가지로 두 가지 동작 모드가 있어요:

• 단순(Simple)
• 확장(Expanded)

단순 모드 최대 2개의 부호 없는 정수를 인자로 받아 UInt64 코드를 생성해요. 확장 모드 첫 번째 인자로 범위 마스크(튜플)를 받고 그 외 인자로 최대 2개의 부호 없는 정수를 받아요. 마스크의 각 숫자는 해당 인자가 왼쪽으로 이동할 비트 수를 설정해, 사실상 인자를 그 범위 내에서 확장(scaling)해요. 범위가 크게 다른(또는 카디널리티가 다른) 인자에 대해 유사한 분포가 필요할 때 유용해요. 예: 'IP 주소' (0...FFFFFFFF)와 '국가 코드' (0...FF). 인코드 함수처럼 최대 8개 숫자로 제한돼요.

구문 (Syntax)

hilbertDecode(tuple_size, code)

인자 (Arguments)

• tuple_size — 2를 넘지 않는 정수 값. UInt8/16/32/64 또는 Tuple(UInt8/16/32/64)
• code — UInt64 코드. UInt64

반환 값 (Returned value)

지정된 크기의 튜플. Tuple(UInt64)

예제 (Examples)

SELECT hilbertDecode(2, 31)  -- (3,4)
SELECT hilbertDecode(1, 1)   -- (1)
SELECT hilbertDecode(tuple(2), 32768)  -- (8192)

hilbertEncode

부호 없는 정수 목록에 대한 Hilbert Curve의 코드를 계산해요. 두 가지 동작 모드가 있어요:

• 단순(Simple)
• 확장(Expanded)

단순 모드 최대 2개의 부호 없는 정수를 인자로 받아 UInt64 코드를 생성해요. 확장 모드 첫 번째 인자로 범위 마스크(Tuple)를 받고 그 외 인자로 최대 2개의 부호 없는 정수를 받아요. 마스크의 각 숫자는 해당 인자가 왼쪽으로 이동할 비트 수를 설정해, 사실상 인자를 그 범위 내에서 확장해요.

구문 (Syntax)

-- Simplified mode
hilbertEncode(args)

-- Expanded mode
hilbertEncode(range_mask, args)

인자 (Arguments)

• args — 최대 두 개의 UInt 값 또는 UInt 타입 컬럼. UInt8/16/32/64
• range_mask — 확장 모드의 경우 최대 두 개의 UInt 값 또는 UInt 타입 컬럼. UInt8/16/32/64

반환 값 (Returned value)

UInt64 코드. UInt64

예제 (Examples)

SELECT hilbertEncode(3, 4)  -- 31
SELECT hilbertEncode((10, 6), 1024, 16)  -- 4031541586602
SELECT hilbertEncode(1)  -- 1

mortonDecode

Morton 인코딩(ZCurve)을 해당하는 부호 없는 정수 튜플로 디코딩해요. mortonEncode 함수와 마찬가지로 두 가지 동작 모드가 있어요:

• 단순(Simple)
• 확장(Expanded)

단순 모드 첫 번째 인자로 결과 튜플 크기를, 두 번째 인자로 코드를 받아요. 확장 모드 첫 번째 인자로 범위 마스크(튜플)를, 두 번째 인자로 코드를 받아요. 마스크의 각 숫자는 범위 축소(shrinking)의 양을 설정해요:

• 1 - 축소 없음
• 2 - 2배 축소
• 3 - 3배 축소 ⋮
• 최대 8배 축소.

범위가 크게 다른 인자에 대해 유사한 분포가 필요할 때 유용해요. 인코드 함수처럼 최대 8개 숫자로 제한돼요.

구문 (Syntax)

-- Simple mode
mortonDecode(tuple_size, code)

-- Expanded mode
mortonDecode(range_mask, code)

인자 (Arguments)

• tuple_size — 8을 넘지 않는 정수 값. UInt8/16/32/64
• range_mask — 확장 모드의 경우 각 인자에 대한 마스크. 부호 없는 정수의 튜플. 각 숫자는 범위 축소의 양을 설정해요. Tuple(UInt8/16/32/64)
• code — UInt64 코드. UInt64

반환 값 (Returned value)

지정된 크기의 튜플. Tuple(UInt64)

예제 (Examples)

SELECT mortonDecode(3, 53)  -- (1,2,3)
SELECT mortonDecode(1, 1)   -- (1)
SELECT mortonDecode(tuple(2), 32768)  -- (128)

mortonEncode

부호 없는 정수 목록의 Morton 인코딩(ZCurve)을 계산해요. 두 가지 동작 모드가 있어요:

• 단순(Simple)
• 확장(Expanded)

단순 모드 최대 8개의 부호 없는 정수를 인자로 받아 UInt64 코드를 생성해요. 확장 모드 첫 번째 인자로 범위 마스크(Tuple)를 받고 그 외 인자로 최대 8개의 부호 없는 정수를 받아요. 마스크의 각 숫자는 범위 확장의 양을 설정해요:

• 1 - 확장 없음
• 2 - 2배 확장
• 3 - 3배 확장 ⋮
• 최대 8배 확장.

구문 (Syntax)

-- Simplified mode
mortonEncode(args)

-- Expanded mode
mortonEncode(range_mask, args)

인자 (Arguments)

• args — 최대 8개의 부호 없는 정수 또는 해당 타입의 컬럼. UInt8/16/32/64
• range_mask — 확장 모드의 경우 각 인자에 대한 마스크. 1 - 8의 부호 없는 정수 튜플. 각 숫자는 범위 축소의 양을 설정해요. Tuple(UInt8/16/32/64)

반환 값 (Returned value)

UInt64 코드. UInt64

예제 (Examples)

SELECT mortonEncode(1, 2, 3)  -- 53
SELECT mortonEncode((1,2), 1024, 16)  -- 1572864
SELECT mortonEncode(1)  -- 1

sqidDecode

sqid를 다시 숫자 배열로 변환해요.

구문 (Syntax)

sqidDecode(sqid)

인자 (Arguments)

• sqid — 디코딩할 sqid. String

반환 값 (Returned value)

sqid에서 온 숫자 배열. Array(UInt64)

예제 (Examples)

SELECT sqidDecode('gXHfJ1C6dN');  -- [1,2,3,4,5]

sqidEncode

숫자를 sqid, 즉 YouTube처럼 생긴 ID 문자열로 변환해요.

구문 (Syntax)

sqidEncode(n1[, n2, ...])

별칭 (Aliases): sqid

인자 (Arguments)

• n1[, n2, ...] — 임의로 많은 숫자. UInt8/16/32/64

반환 값 (Returned value)

해시 ID. String

예제 (Examples)

SELECT sqidEncode(1, 2, 3, 4, 5);  -- gXHfJ1C6dN

unbin

인자의 각 이진 숫자 쌍을 숫자로 해석하고, 그 숫자가 나타내는 바이트로 변환해요. bin의 반대 연산을 수행해요. 숫자 인자에 대해 unbin()은 bin()의 역을 반환하지 않아요. 결과를 숫자로 변환하려면 reverse와 reinterpretAs<Type> 함수를 사용할 수 있어요.

unbin이 clickhouse-client 안에서 호출되면 이진 문자열은 UTF-8로 표시돼요. 이진 숫자 0과 1을 지원해요. 이진 숫자의 개수는 8의 배수일 필요가 없어요. 인자 문자열에 이진 숫자 외의 것이 포함되면 결과는 정의되지 않아요(예외는 발생하지 않아요).

구문 (Syntax)

unbin(arg)

인자 (Arguments)

• arg — 임의 개수의 이진 숫자를 담은 문자열. String

반환 값 (Returned value)

이진 문자열(BLOB). String

예제 (Examples)

SELECT UNBIN('001100000011000100110010'), UNBIN('0100110101111001010100110101000101001100')

응답: 012와 MySQL

unhex

hex의 반대 연산을 수행해요. 인자의 각 16진수 숫자 쌍을 숫자로 해석하고, 그 숫자가 나타내는 바이트로 변환해요. 반환 값은 이진 문자열(BLOB)이에요. 결과를 숫자로 변환하려면 reverse와 reinterpretAs<Type> 함수를 사용할 수 있어요.

clickhouse-client는 문자열을 UTF-8로 해석해요. 이로 인해 hex가 반환한 값이 예상치 못하게 표시될 수 있어요. 대문자와 소문자 A-F를 모두 지원해요. 16진수 숫자의 개수는 짝수일 필요가 없어요. 홀수면 마지막 숫자는 00-0F 바이트의 가장 작은 자리 절반으로 해석돼요. 인자 문자열에 16진수 숫자 외의 것이 포함되면 구현 정의된 결과가 반환돼요(예외는 발생하지 않아요). 숫자 인자에 대해 unhex()는 hex(N)의 역을 수행하지 않아요.

구문 (Syntax)

unhex(arg)

인자 (Arguments)

• arg — 임의 개수의 16진수 숫자를 담은 문자열. String 또는 FixedString

반환 값 (Returned value)

이진 문자열(BLOB). String

예제 (Examples)

SELECT unhex('303132'), UNHEX('4D7953514C')

응답: 012와 MySQL

더 알아보기 (Learn more)

• 해시 함수 (hash functions)
• 암호화 함수 (encryption functions)