UUID 함수

UUID 함수 (UUID functions)

UUID(식별자)와 Snowflake ID를 생성·변환하고, 그 타임스탬프 성분을 추출하는 함수들이에요. UUIDv7과 Snowflake ID는 시간순 정렬이 가능한 식별자를 만들 수 있어요.

출처: 문서

본문

아래 내용은 UUID 및 Snowflake ID 관련 함수를 다룹니다.

UUIDv7 생성

생성된 UUID는 Unix 밀리초 단위의 48비트 타임스탬프, 버전 "7"(4비트), 밀리초 내에서 UUID를 구분하는 카운터(42비트, 변형 필드 "2" 2비트 포함), 그리고 무작위 필드(32비트)로 구성됩니다.

주어진 타임스탬프(unix_ts_ms)에 대해 카운터는 무작위 값에서 시작해 타임스탬프가 바뀔 때까지 새 UUID마다 1씩 증가합니다. 카운터가 오버플로되면 타임스탬프 필드가 1 증가하고 카운터는 새 무작위 시작 값으로 재설정됩니다.

UUID 생성 함수는 타임스탬프 내의 카운터 필드가 동시에 실행되는 스레드와 쿼리의 모든 함수 호출에 걸쳐 단조 증가함을 보장합니다.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                           unix_ts_ms                          |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|          unix_ts_ms           |  ver  |   counter_high_bits   |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|var|                   counter_low_bits                        |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                            rand_b                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Snowflake ID 생성

생성된 Snowflake ID는 Unix 밀리초 단위의 현재 타임스탬프(41 + 1 최상위 0비트), 머신 ID(10비트), 그리고 밀리초 내에서 ID를 구분하는 카운터(12비트)로 구성됩니다. 주어진 타임스탬프(unix_ts_ms)에 대해 카운터는 0에서 시작해 타임스탬프가 바뀔 때까지 새 Snowflake ID마다 1씩 증가합니다. 카운터가 오버플로되면 타임스탬프 필드가 1 증가하고 카운터는 0으로 재설정됩니다.

생성된 Snowflake ID는 UNIX epoch 1970-01-01을 기준으로 합니다. Snowflake ID의 epoch에 대한 표준·권장 사항은 없지만, 다른 시스템의 구현은 다른 epoch를 사용할 수 있습니다. 예: Twitter/X(2010-11-04) 또는 Mastodon(2015-01-01).

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|0|                         timestamp                           |
├─┼                 ┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                   |     machine_id    |    machine_seq_num    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

UUIDNumToString

도입 버전: v1.1.0

UUID의 이진 표현을 받아(variant로 포맷 선택 가능, 기본값 Big-endian), 텍스트 형식의 36문자 문자열을 반환합니다.

구문

UUIDNumToString(binary[, variant])

인자

반환 값

UUID를 문자열로 반환합니다. String

예제 — 사용 예시

Query

SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid

Response

┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

Microsoft 변형

Query

SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid

Response

┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

UUIDStringToNum

도입 버전: v1.1.0

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 형식의 36문자 문자열을 받아, 그 이진 표현인 FixedString(16)을 반환합니다(variant로 포맷 선택 가능, 기본값 Big-endian).

구문

UUIDStringToNum(string[, variant = 1])

인자

  • string — 36문자의 문자열 또는 고정 문자열. String 또는 FixedString(36)
  • variant — RFC4122가 지정한 변형. 1 = Big-endian(기본값), 2 = Microsoft. (U)Int*

반환 값

string의 이진 표현을 반환합니다. FixedString(16)

예제 — 사용 예시

Query

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes

Response

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

Microsoft 변형

Query

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes

Response

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

UUIDToNum

도입 버전: v24.5.0

UUID를 받아 그 이진 표현인 FixedString(16)을 반환합니다(variant로 포맷 선택 가능, 기본값 Big-endian). 이 함수는 UUIDStringToNum(toString(uuid)) 두 함수 호출을 대체하므로, UUID에서 바이트를 추출할 때 UUID에서 문자열로의 중간 변환이 필요 없습니다.

구문

UUIDToNum(uuid[, variant = 1])

인자

반환 값

UUID의 이진 표현을 반환합니다. FixedString(16)

예제 — 사용 예시

Query

SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes

Response

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

Microsoft 변형

Query

SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid, 2) AS bytes

Response

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

UUIDv7ToDateTime

도입 버전: v24.5.0

버전 7 UUID의 타임스탬프 성분을 반환합니다.

구문

UUIDv7ToDateTime(uuid[, timezone])

인자

반환 값

밀리초 정밀도의 타임스탬프를 반환합니다. UUID가 유효한 버전 7이 아니면 1970-01-01 00:00:00.000을 반환합니다. DateTime64(3)

예제 — 사용 예시

Query

SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))

Response

┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 12:30:29.048 │
└──────────────────────────────────────────────────────────────────┘

타임존 포함

Query

SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')

Response

┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                              2024-04-22 08:30:29.048 │
└──────────────────────────────────────────────────────────────────────────────────────┘

dateTime64ToSnowflakeID

도입 버전: v24.6.0

DateTime64 값을 해당 시각의 첫 번째 Snowflake ID로 변환합니다.

구문

dateTime64ToSnowflakeID(value[, epoch])

인자

  • value — 날짜와 시간. DateTime64
  • epoch — 1970-01-01 이후 밀리초 단위의 Snowflake ID epoch. 기본값 0(1970-01-01). Twitter/X epoch(2015-01-01)는 1288834974657을 제공합니다. UInt*

반환 값

UInt64로 변환된 입력 값.

예제 — 단순

Query

SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))

Response

6832626392367104000

dateTimeToSnowflakeID

도입 버전: v24.6.0

DateTime 값을 해당 시각의 첫 번째 Snowflake ID로 변환합니다.

구문

dateTimeToSnowflakeID(value[, epoch])

인자

  • value — 날짜와 시간. DateTime
  • epoch — 1970-01-01 이후 밀리초 단위의 Snowflake ID epoch. 기본값 0(1970-01-01). Twitter/X epoch(2015-01-01)는 1288834974657을 제공합니다. UInt*

반환 값

UInt64로 변환된 입력 값.

예제 — 단순

Query

SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))

Response

6832626392367104000

dateTimeToUUIDv7

도입 버전: v25.8.0

DateTime 값을 주어진 시각의 UUIDv7로 변환합니다(RFC 9562 정의). UUID 구조, 카운터 관리, 동시성 보장은 "UUIDv7 생성" 섹션을 참고해요.

이 함수는 비결정적입니다. 같은 인자로도 결과가 달라질 수 있어요.

구문

dateTimeToUUIDv7(value)

인자

반환 값

UUIDv7을 반환합니다. UUID

예제 — 사용 예시

Query

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));

Response

┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                 │
└──────────────────────────────────────────────────────────────────────┘

같은 타임스탬프의 여러 UUID

Query

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));

Response

┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘

generateSnowflakeID

도입 버전: v24.6.0

Snowflake ID를 생성합니다. generateSnowflakeID 함수는 타임스탬프 내의 카운터 필드가 동시에 실행되는 스레드와 쿼리의 모든 함수 호출에 걸쳐 단조 증가함을 보장합니다. 구현 세부 사항은 "Snowflake ID 생성" 섹션을 참고해요.

이 함수는 비결정적입니다.

구문

generateSnowflakeID([expr, [machine_id]])

인자

  • expr — 쿼리에서 함수를 여러 번 호출할 때 공통 부분식 제거를 우회하는 데 사용하는 임의 표현식. 표현식 값은 반환된 Snowflake ID에 영향을 주지 않습니다. 선택 사항.
  • machine_id — 머신 ID. 하위 10비트가 사용됩니다. Int64. 선택 사항.

반환 값

Snowflake ID를 반환합니다. UInt64

예제 — 사용 예시

Query

CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;

Response

┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘

행당 여러 Snowflake ID 생성

Query

SELECT generateSnowflakeID(1), generateSnowflakeID(2);

Response

┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘

표현식과 머신 ID 포함

Query

SELECT generateSnowflakeID('expr', 1);

Response

┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘

generateUUIDv4

도입 버전: v1.1.0

버전 4 UUID를 생성합니다.

이 함수는 비결정적입니다.

구문

generateUUIDv4([expr])

인자

  • expr — 선택 사항. 쿼리에서 함수를 여러 번 호출할 때 공통 부분식 제거를 우회하는 데 사용하는 임의 표현식. 표현식 값은 반환된 UUID에 영향을 주지 않습니다.

반환 값

UUIDv4를 반환합니다. UUID

예제 — 사용 예시

Query

SELECT generateUUIDv4(number) FROM numbers(3);

Response

┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘

공통 부분식 제거

Query

SELECT generateUUIDv4(1), generateUUIDv4(1);

Response

┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7

도입 버전: v24.5.0

RFC 9562가 정의한 버전 7 UUID를 생성합니다. UUID 구조, 카운터 관리, 동시성 보장은 "UUIDv7 생성" 섹션을 참고해요.

이 함수는 비결정적입니다.

구문

generateUUIDv7([expr])

인자

  • expr — 선택 사항. 쿼리에서 함수를 여러 번 호출할 때 공통 부분식 제거를 우회하는 데 사용하는 임의 표현식. 표현식 값은 반환된 UUID에 영향을 주지 않습니다. Any

반환 값

UUIDv7을 반환합니다. UUID

예제 — 사용 예시

Query

SELECT generateUUIDv7(number) FROM numbers(3);

Response

┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘

공통 부분식 제거

Query

SELECT generateUUIDv7(1), generateUUIDv7(1);

Response

┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

snowflakeIDToDateTime

도입 버전: v24.6.0

Snowflake ID의 타임스탬프 성분을 DateTime 타입의 값으로 반환합니다.

구문

snowflakeIDToDateTime(value[, epoch[, time_zone]])

인자

  • value — Snowflake ID. UInt64
  • epoch — 선택 사항. 1970-01-01 이후 밀리초 단위의 Snowflake ID epoch. 기본값 0(1970-01-01). Twitter/X epoch(2015-01-01)는 1288834974657을 제공합니다. UInt*
  • time_zone — 선택 사항. 타임존. 함수가 time_string을 타임존에 따라 파싱합니다. String

반환 값

value의 타임스탬프 성분을 반환합니다. DateTime

예제 — 사용 예시

Query

SELECT snowflakeIDToDateTime(7204436857747984384) AS res

Response

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeIDToDateTime64

도입 버전: v24.6.0

Snowflake ID의 타임스탬프 성분을 DateTime64 타입의 값으로 반환합니다.

구문

snowflakeIDToDateTime64(value[, epoch[, time_zone]])

인자

  • value — Snowflake ID. UInt64
  • epoch — 선택 사항. 1970-01-01 이후 밀리초 단위의 Snowflake ID epoch. 기본값 0(1970-01-01). Twitter/X epoch(2015-01-01)는 1288834974657을 제공합니다. UInt*
  • time_zone — 선택 사항. 타임존. 함수가 time_string을 타임존에 따라 파싱합니다. String

반환 값

value의 타임스탬프 성분을 scale = 3, 즉 밀리초 정밀도의 DateTime64로 반환합니다. DateTime64

예제 — 사용 예시

Query

SELECT snowflakeIDToDateTime64(7204436857747984384) AS res

Response

┌─────────────────────res─┐
│ 2024-06-06 10:59:58.851 │
└─────────────────────────┘

toUUIDOrDefault

도입 버전: v21.1.0

String 값을 UUID 타입으로 변환합니다. 변환이 실패하면 오류를 던지는 대신 기본 UUID 값을 반환합니다. 이 함수는 표준 UUID 형식(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)의 36문자 문자열을 파싱하려 시도합니다. 문자열을 유효한 UUID로 변환할 수 없으면 제공된 기본 UUID 값을 반환합니다.

구문

toUUIDOrDefault(string, default)

인자

  • string — UUID로 변환할 36문자 문자열 또는 FixedString(36).
  • default — 첫 번째 인자를 UUID 타입으로 변환할 수 없을 때 반환할 UUID 값.

반환 값

성공하면 변환된 UUID를, 실패하면 기본 UUID를 반환합니다. UUID

예제 — 성공 시 파싱된 UUID 반환

Query

SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

Response

┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                    │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

예제 — 실패 시 기본 UUID 반환

Query

SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

Response

┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                         │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

toUUIDOrNull

도입 버전: v20.12.0

입력 값을 UUID 타입으로 변환하지만 오류가 나면 NULL을 반환합니다. toUUID와 같지만 변환 오류 시 예외를 던지는 대신 NULL을 반환합니다.

지원 인자:

  • 표준 형식(8-4-4-4-12 16진수 숫자)의 UUID 문자열 표현.
  • 하이픈 없는 UUID 문자열 표현(32 16진수 숫자).

지원되지 않는 인자(NULL 반환):

  • 잘못된 문자열 형식.
  • 문자열이 아닌 타입.
  • 잘못된 UUID.

구문

toUUIDOrNull(x)

인자

  • x — UUID의 문자열 표현. String

반환 값

성공하면 UUID 값을, 그 외에는 NULL을 반환합니다. UUID 또는 NULL

예제 — 사용 예시

Query

SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │ ᴺᵁᴸᴸ         │
└──────────────────────────────────────┴──────────────┘

더 알아보기 (Learn more)