生成される 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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
unix_ts_ms) に対して、カウンターは 0 から始まり、タイムスタンプが変わるまで新しい Snowflake ID が生成されるたびに 1 ずつ増加します。カウンターがオーバーフローした場合は、タイムスタンプのフィールドが 1 増やされ、カウンターは 0 にリセットされます。
生成される Snowflake ID は、UNIX エポック である 1970-01-01 を基準としています。Snowflake ID の エポック には標準や推奨事項はありませんが、他のシステムの実装では別の エポック が使われている場合があります。たとえば、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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
variant でそのフォーマットを任意に指定できます (デフォルトは Big-endian) 。テキスト形式の 36 文字の文字列を返します。
構文
UUIDNumToString(binary[, variant])
String
例
使用例
SELECT
'a/<@];!~p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16)) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
SELECT
'@</a;]~!p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 形式の36文字の文字列を受け取り、そのバイナリ表現として FixedString(16) を返します。必要に応じて variant でフォーマットを指定でき、デフォルトは Big-endian です。
構文
UUIDStringToNum(string[, variant = 1])
string のバイナリ表現を返します。FixedString(16)
例
使用例
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid, 2) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
variant で指定でき、デフォルトは Big-endian です。
この関数は、2 つの個別の関数 UUIDStringToNum(toString(uuid)) の呼び出しを置き換えるもので、UUID からバイトを抽出するために UUID を文字列へ中間変換する必要がありません。
構文
UUIDToNum(uuid[, variant = 1])
FixedString(16)
例
使用例
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid, 2) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
UUIDv7ToDateTime(uuid[, timezone])
1970-01-01 00:00:00.000を返します。DateTime64(3)
例
使用例
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│ 2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│ 2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘
dateTime64ToSnowflake(value)
Int64
例
使用例
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
┌─dateTime64ToSnowflake(dt64)─┐
│ 1426860704886947840 │
└─────────────────────────────┘
dateTime64ToSnowflakeID(value[, epoch])
value — 日時。DateTime64epoch — 1970-01-01 からの経過ミリ秒で表した Snowflake ID のエポック。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) を使用する場合は、1288834974657 を指定します。UInt*
戻り値
UInt64 に変換された入力値
例
simple
SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
dateTimeToSnowflake(value)
Int64
例
使用例
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
┌─dateTimeToSnowflake(dt)─┐
│ 1426860702823350272 │
└─────────────────────────┘
dateTimeToSnowflakeID(value[, epoch])
value — 日時。DateTimeepoch — 1970-01-01 からの経過ミリ秒で表した Snowflake ID の epoch。デフォルトは 0 (1970-01-01) です。Twitter/X の epoch (2015-01-01) の場合は、1288834974657 を指定します。UInt*
戻り値
UInt64 に変換された入力値
例
simple
SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))
2025年9月時点では、バージョン 7 UUID はドラフト段階にあり、今後レイアウトが変更される可能性があります。
UUID
例
使用例
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));
┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b │
└─────────────────────────────────────────────────────────────────────────┘
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
┌─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 は、同時実行中のスレッドおよびクエリ全体にわたるすべての関数呼び出しにおいて、タイムスタンプ内のカウンター フィールドが単調増加することを保証します。
実装の詳細については、“Snowflake ID generation” セクションを参照してください。
構文
generateSnowflakeID([expr, [machine_id]])
expr — 関数が1つのクエリ内で複数回呼び出される場合に、共通部分式除去を回避するための任意の式です。この式の値は、返される Snowflake ID には影響しません。省略可能です。 - machine_id — マシン ID。下位 10 ビットが使用されます。Int64。省略可能です。
戻り値
Snowflake ID を返します。UInt64
例
使用例
CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();
INSERT INTO tab SELECT generateSnowflakeID();
SELECT * FROM tab;
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│ 7199081609652224000 │ 7199081609652224001 │
└────────────────────────┴────────────────────────┘
SELECT generateSnowflakeID('expr', 1);
┌─generateSnowflakeID('expr', 1)─┐
│ 7201148511606784002 │
└────────────────────────────────┘
expr — 省略可。関数が1つのクエリ内で複数回呼び出される場合に、共通部分式除去を回避するために使われる任意の式です。式の値は、返される UUID には影響しません。
戻り値
UUIDv4 を返します。UUID
例
使用例
SELECT generateUUIDv4(number) FROM numbers(3);
┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘
SELECT generateUUIDv4(1), generateUUIDv4(1);
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
2025 年 9 月時点では、バージョン 7 UUID はドラフト段階にあり、今後レイアウトが変更される可能性があります。
expr — オプション。関数が1つのクエリ内で複数回呼び出される場合に、共通部分式除去を回避するために使用する任意の式です。この式の値は、返される UUID に影響しません。Any
戻り値
UUIDv7 を返します。UUID
例
使用例
SELECT generateUUIDv7(number) FROM numbers(3);
┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘
SELECT generateUUIDv7(1), generateUUIDv7(1);
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
snowflakeIDToDateTime(value[, epoch[, time_zone]])
value — Snowflake ID。UInt64epoch — 省略可能。1970-01-01 からのミリ秒単位で表した Snowflake ID のエポックです。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) の場合は、1288834974657 を指定します。UInt*time_zone — 省略可能。タイムゾーン。関数は time_string をこのタイムゾーンに従って解析します。String
戻り値
value のタイムスタンプ部分を返します。DateTime
例
使用例
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
value — Snowflake ID。UInt64epoch — 省略可能。1970-01-01 からの経過ミリ秒で表される Snowflake ID のエポック。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) の場合は、1288834974657 を指定します。UInt*time_zone — 省略可能。タイムゾーン。この関数は、タイムゾーンに従って time_string を解析します。String
戻り値
value のタイムスタンプ部分を、scale = 3、つまりミリ秒精度の DateTime64 として返します。DateTime64
例
使用例
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeToDateTime(value[, time_zone])
value — Snowflake ID。Int64time_zone — 任意。タイムゾーン。この関数は、time_string をタイムゾーンに従って解析します。String
戻り値
value のタイムスタンプ部分を返します。DateTime
例
使用例
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
snowflakeToDateTime64(value[, time_zone])
value — Snowflake ID。Int64time_zone — 任意。タイムゾーン。この関数は、タイムゾーンに従って time_string を解析します。String
戻り値
value のタイムスタンプ部分を返します。DateTime64(3)
例
使用例
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
toUUIDOrDefault(string, default)
string — UUID に変換する 36 文字の文字列、または FixedString(36)。 - default — 最初の引数を UUID 型に変換できない場合に返される UUID 値。
戻り値
変換に成功した場合は変換後の UUID を返し、変換に失敗した場合はデフォルトの UUID を返します。 UUID
例
変換に成功した場合は、パースされた UUID が返されます
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
UUID 型の値に変換します。エラーが発生した場合は NULL を返します。
toUUID と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。
サポートされる引数:
- 標準形式 (8-4-4-4-12 桁の16進数) の UUID の文字列表現。
- ハイフンなし (32 桁の16進数) の UUID の文字列表現。
サポートされない引数 (NULL を返します) :
- 無効な文字列形式。
- 文字列以外の型。
- 形式が不正な UUID。
構文
引数
戻り値
成功した場合はUUID値を返し、失敗した場合は NULL を返します。UUID または NULL
例
使用例
SELECT
toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
toUUIDOrNull('invalid-uuid') AS invalid_uuid
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │ ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
