UUIDv7 の生成
生成される UUID は、Unix エポックミリ秒の 48 ビットのタイムスタンプに続いて、バージョン「7」（4 ビット）、1 ミリ秒内で UUID を区別するためのカウンタ（バリアントフィールド「2」（2 ビット）を含む 42 ビット）、およびランダムフィールド（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 ビット）、それに続くマシン ID（10 ビット）、および同一ミリ秒内で ID を区別するためのカウンタ（12 ビット）が含まれます。任意のタイムスタンプ（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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
generateUUIDv4
バージョン4 の UUID を生成します。
構文
引数
expr — クエリ内で関数が複数回呼び出される場合に、共通部分式の除去を回避するために使用される任意の式。この式の値は返される UUID には影響しません。省略可能。
戻り値
UUIDv4 型の値。
例
まず、UUID 型の列を持つテーブルを作成し、その後、生成された UUIDv4 をそのテーブルに挿入します。
CREATE TABLE tab (uuid UUID) ENGINE = Memory;
INSERT INTO tab SELECT generateUUIDv4();
SELECT * FROM tab;
結果:
┌─────────────────────────────────uuid─┐
│ f4bf890f-f9dc-4332-ad5c-0c18e73f28e9 │
└──────────────────────────────────────┘
行ごとに複数の UUID を生成する例
SELECT generateUUIDv4(1), generateUUIDv4(2);
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 8abf8c13-7dea-4fdf-af3e-0e18767770e6 │
└──────────────────────────────────────┴──────────────────────────────────────┘
generateUUIDv7
バージョン 7 の UUID を生成します。
UUID の構造、カウンタの管理、および並行性に関する保証の詳細については、「UUIDv7 の生成」 セクションを参照してください。
注記
2024 年 4 月時点では、バージョン 7 UUID はドラフト段階の仕様であり、そのレイアウトは将来的に変更される可能性があります。
構文
引数
expr — クエリ内でこの関数が複数回呼び出される場合に、共通部分式除去を回避するために使用される任意の式。この式の値は、返される UUID には一切影響しません。省略可能。
戻り値
UUIDv7 型の値。
例
まず、UUID 型の列を持つテーブルを作成し、その後、生成された UUIDv7 をテーブルに挿入します。
CREATE TABLE tab (uuid UUID) ENGINE = Memory;
INSERT INTO tab SELECT generateUUIDv7();
SELECT * FROM tab;
結果:
┌─────────────────────────────────uuid─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b │
└──────────────────────────────────────┘
行ごとに複数の UUID を生成する例
SELECT generateUUIDv7(1), generateUUIDv7(2);
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(2)────────────────────┐
│ 018f05c9-4ab8-7b86-b64e-c9f03fbd45d1 │ 018f05c9-4ab8-7b86-b64e-c9f12efb7e16 │
└──────────────────────────────────────┴──────────────────────────────────────┘
dateTimeToUUIDv7
指定した時刻を表す DateTime 値を UUIDv7 に変換します。
UUID の構造、カウンター管理、および並行性の保証については、「UUIDv7 generation」セクションを参照してください。
注記
2024年4月時点では、バージョン7 UUIDはドラフト仕様であり、そのレイアウトは将来変更される可能性があります。
構文
引数
返される値
UUIDv7 型の値。
例
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 │
└─────────────────────────────────────────────────────────────────────────┘
同一のタイムスタンプに対する複数の UUID の例
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'))─┐
1. │ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
1. │ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘
この関数は、同じタイムスタンプで複数回呼び出されても、一意で単調増加する UUID を生成することを保証します。
empty
入力された UUID が空かどうかをチェックします。
構文
UUID がすべてゼロ（ゼロ UUID）で構成されている場合、それは空と見なされます。
この関数は Array および String に対しても動作します。
引数
戻り値
- 空の UUID に対しては
1 を返し、空でない UUID に対しては 0 を返します。UInt8。
例
UUID 値を生成するには、ClickHouse は generateUUIDv4 関数を提供しています。
クエリ:
SELECT empty(generateUUIDv4());
結果：
┌─empty(generateUUIDv4())─┐
│ 0 │
└─────────────────────────┘
notEmpty
入力された UUID が空でないことを確認します。
構文
UUID がすべてゼロ（ゼロ UUID）で構成されている場合、その UUID は空と見なされます。
この関数は Array 型および String 型に対しても動作します。
引数
戻り値
- 空でない UUID の場合は
1、空の UUID の場合は 0 を返します。 UInt8。
例
UUID 値を生成するには、ClickHouse は generateUUIDv4 関数を提供しています。
クエリ:
SELECT notEmpty(generateUUIDv4());
結果:
┌─notEmpty(generateUUIDv4())─┐
│ 1 │
└────────────────────────────┘
toUUID
String 型の値を UUID 型に変換します。
戻り値
UUID 型の値です。
使用例
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
結果：
┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
toUUIDOrDefault
引数
string — 36 文字の String 型または FixedString(36) 型。String。default — 最初の引数を UUID 型に変換できない場合にデフォルトとして使用される UUID。UUID。
戻り値
UUID
toUUIDOrDefault(string, default)
戻り値
UUID 型の値。
使用例
この最初の例では、変換可能であるため、最初の引数を UUID 型に変換して返します。
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', cast('59f0c404-5cb3-11e7-907b-a6006ad3dba0' AS UUID));
結果:
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', CAST('59f0c404-5cb3-11e7-907b-a6006ad3dba0', 'UUID'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
この 2 番目の例では、最初の引数を UUID 型に変換できないため、2 番目の引数（指定されたデフォルトの UUID）が返されます。
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', cast('59f0c404-5cb3-11e7-907b-a6006ad3dba0' AS UUID));
結果:
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', CAST('59f0c404-5cb3-11e7-907b-a6006ad3dba0', 'UUID'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
toUUIDOrNull
String 型の引数を受け取り、UUID 型としてパースしようとします。失敗した場合は NULL を返します。
返り値
Nullable(UUID) 型の値。
使用例
SELECT toUUIDOrNull('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
結果：
┌─uuid─┐
│ ᴺᵁᴸᴸ │
└──────┘
toUUIDOrZero
String 型の引数を受け取り、UUID としての解析を試みます。失敗した場合は、ゼロ UUID を返します。
戻り値
UUID 型の値です。
使用例
SELECT toUUIDOrZero('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
結果:
┌─────────────────────────────────uuid─┐
│ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┘
UUIDStringToNum
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx という形式の 36 文字の string を受け取り、そのバイナリ表現として FixedString(16) を返します。戻り値の形式はオプションの variant で指定でき、指定しない場合は Big-endian になります。
構文
UUIDStringToNum(string[, variant = 1])
引数
戻り値
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={) │
└──────────────────────────────────────┴──────────────────┘
UUIDNumToString
UUID のバイナリ表現を含む binary を受け取り、その形式は任意の variant 引数（デフォルトは Big-endian）で指定できます。テキスト形式の 36 文字からなる文字列を返します。
構文
UUIDNumToString(binary[, variant = 1])
引数
binary — UUID をバイナリで表現した FixedString(16)。variant — RFC4122 で規定されているバリアントを表す整数。1 = Big-endian（デフォルト）、2 = Microsoft。
戻り値
文字列。
使用例
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 │
└──────────────────┴──────────────────────────────────────┘
UUIDToNum
UUID を受け取り、そのバイナリ表現を FixedString(16) 型として返します。フォーマットはオプションの variant（デフォルトは Big-endian）で指定できます。この関数は、UUIDStringToNum(toString(uuid)) という 2 段階の呼び出しを置き換えるため、UUID からバイト列を抽出する際に UUID を文字列へ中間変換する必要がなくなります。
構文
UUIDToNum(uuid[, variant = 1])
引数
uuid — UUID。variant — 整数で、RFC4122 で規定されているバリアントを表します。1 = Big-endian（デフォルト）、2 = Microsoft。
返される値
UUID のバイナリ表現です。
使用例
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 バージョン 7 のタイムスタンプ部分を返します。
構文
UUIDv7ToDateTime(uuid[, timezone])
引数
戻り値
- ミリ秒精度のタイムスタンプ。UUID がバージョン 7 の有効な UUID でない場合は
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 08:30:29.048 │
└──────────────────────────────────────────────────────────────────────────────────────┘
serverUUID
ClickHouse サーバーの初回起動時に生成されるランダムな UUID を返します。UUID は ClickHouse サーバーのディレクトリ（例: /var/lib/clickhouse/）内の uuid ファイルに保存され、サーバーを再起動しても保持されます。
構文
戻り値
generateSnowflakeID
Snowflake ID を生成します。
この関数は、同時に実行中のスレッドおよびクエリにおけるすべての関数呼び出しにわたって、タイムスタンプに含まれるカウンターフィールドが単調増加することを保証します。
実装の詳細については、「Snowflake ID generation」 セクションを参照してください。
構文
generateSnowflakeID([expr, [machine_id]])
引数
expr — クエリ内でこの関数が複数回呼び出される場合に、共通部分式の除去を回避するために使用される任意の式。この式の値は、返される Snowflake ID には影響しません。省略可能です。machine_id — マシン ID。下位 10 ビットが使用されます。Int64。省略可能です。
戻り値
型 UInt64 の値。
例
まず、型 UInt64 の列を持つテーブルを作成し、その後、生成された Snowflake ID をテーブルに挿入します。
CREATE TABLE tab (id UInt64) ENGINE = Memory;
INSERT INTO tab SELECT generateSnowflakeID();
SELECT * FROM tab;
結果：
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
1 行ごとに複数の Snowflake ID が生成される例
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│ 7199081609652224000 │ 7199081609652224001 │
└────────────────────────┴────────────────────────┘
式とマシン ID を使用した例
SELECT generateSnowflakeID('expr', 1);
┌─generateSnowflakeID('expr', 1)─┐
│ 7201148511606784002 │
└────────────────────────────────┘
snowflakeToDateTime
Snowflake ID から DateTime 形式のタイムスタンプ部分を抽出します。
構文
snowflakeToDateTime(value[, time_zone])
引数
value — Snowflake ID。Int64。time_zone — Timezone。関数は指定されたタイムゾーンに従って time_string を解析します。省略可能。String。
戻り値
例
クエリ:
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
結果:
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
snowflakeToDateTime64
Snowflake ID のタイムスタンプ部分を DateTime64 形式で抽出します。
構文
snowflakeToDateTime64(value[, time_zone])
引数
value — Snowflake ID。Int64。time_zone — Timezone。この関数は time_string をこのタイムゾーンに基づいて解釈します。省略可能。String。
戻り値
value のタイムスタンプ成分を、スケール = 3（ミリ秒精度）の DateTime64 として返します。
例
クエリ:
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
結果：
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
dateTimeToSnowflake
DateTime の値を、その時刻に対応する最初の Snowflake ID に変換します。
構文
dateTimeToSnowflake(value)
引数
戻り値
- 入力値を、その時刻における最初の Snowflake ID を表す Int64 データ型の値に変換したもの。
例
クエリ:
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
結果：
┌─dateTimeToSnowflake(dt)─┐
│ 1426860702823350272 │
└─────────────────────────┘
dateTime64ToSnowflake
DateTime64 を、指定された時刻における最初の Snowflake ID に変換します。
構文
dateTime64ToSnowflake(value)
引数
返される値
- 入力値に対応する、その時刻における最初の Snowflake ID を表す Int64 型の値。
例
クエリ:
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
結果:
┌─dateTime64ToSnowflake(dt64)─┐
│ 1426860704886947840 │
└─────────────────────────────┘
snowflakeIDToDateTime
Snowflake ID のタイムスタンプ部分を、DateTime 型の値として返します。
構文
snowflakeIDToDateTime(value[, epoch[, time_zone]])
引数
value — Snowflake ID。UInt64。epoch - Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0（1970-01-01）です。Twitter/X のエポック（2015-01-01）の場合は 1288834974657 を指定します。省略可能。UInt*。time_zone — Timezone。関数は time_string をこのタイムゾーンに従って解釈します。省略可能。String。
返される値
value のタイムスタンプコンポーネントを DateTime 値として返します。
例
クエリ：
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
結果:
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeIDToDateTime64
Snowflake ID のタイムスタンプコンポーネントを、DateTime64 型の値として返します。
構文
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
引数
value — Snowflake ID。 UInt64。epoch - Snowflake ID のエポック（1970-01-01 からの経過ミリ秒）。デフォルトは 0（1970-01-01）。Twitter/X のエポック（2015-01-01）の場合は 1288834974657 を指定します。省略可能。 UInt*。time_zone — Timezone。関数は time_string をこのタイムゾーンに従って解釈します。省略可能。 String。
返り値
value のタイムスタンプ部分を、スケール = 3（ミリ秒精度）の DateTime64 として返します。
例
クエリ：
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
結果：
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
dateTimeToSnowflakeID
DateTime 型の値を、指定された時刻における最初の Snowflake ID に変換します。
構文
dateTimeToSnowflakeID(value[, epoch])
引数
value — 日時。DateTime。epoch - Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0 (1970-01-01)。Twitter/X のエポック (2015-01-01) を使用する場合は 1288834974657 を指定します。省略可能。UInt*。
戻り値
- 入力値を、その時刻における最初の Snowflake ID に対応する UInt64 値に変換したもの。
例
クエリ:
SELECT toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt, dateTimeToSnowflakeID(dt) AS res;
結果：
┌──────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56 │ 6832626392367104000 │
└─────────────────────┴─────────────────────┘
dateTime64ToSnowflakeID
DateTime64 を、指定された時刻に対応する最初の Snowflake ID に変換します。
構文
dateTime64ToSnowflakeID(value[, epoch])
引数
value — 時刻付きの日付。DateTime64。epoch - Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) を指定する場合は 1288834974657 を指定します。省略可能です。UInt*。
戻り値
- 入力値を、その時刻における最初の Snowflake ID を表す UInt64 値に変換したもの。
例
クエリ:
SELECT toDateTime('2021-08-15 18:57:56.493', 3, 'Asia/Shanghai') AS dt, dateTime64ToSnowflakeID(dt) AS res;
結果：
┌──────────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56.493 │ 6832626394434895872 │
└─────────────────────────┴─────────────────────┘
関連項目
UUIDNumToString
導入バージョン: v1.1
UUID のバイナリ表現を受け取り、オプションの variant 引数（省略時は Big-endian）でその形式を指定し、テキスト形式の 36 文字からなる文字列を返します。
構文
UUIDNumToString(binary[, variant])
引数
戻り値
UUID を文字列として返します。String
例
使用例
SELECT
'a/<@];!~p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16)) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
Microsoft 版
SELECT
'@</a;]~!p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
UUIDStringToNum
導入: v1.1
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={) │
└──────────────────────────────────────┴──────────────────┘
Microsoft バリアント
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid, 2) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
UUIDToNum
導入バージョン: v24.5
UUID を受け取り、そのバイナリ表現を FixedString(16) として返します。形式は variant で任意指定でき、デフォルトは Big-endian です。
この関数は、UUID からバイト列を取り出す際に必要だった、UUIDStringToNum(toString(uuid)) という 2 つの関数を組み合わせた呼び出しを置き換えるものであり、UUID を文字列に中間変換する必要がなくなります。
構文
UUIDToNum(uuid[, variant = 1])
引数
戻り値
UUID のバイナリ表現を返します。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={) │
└──────────────────────────────────────┴──────────────────┘
Microsoft 版
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
導入バージョン: v24.5
UUID バージョン 7 のタイムスタンプ部分を返します。
構文
UUIDv7ToDateTime(uuid[, timezone])
引数
戻り値
ミリ秒精度のタイムスタンプを返します。UUID が有効なバージョン 7 UUID でない場合は、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
導入バージョン: v21.10
DateTime64 を、指定した時刻における最初の Snowflake ID に変換します。
構文
dateTime64ToSnowflake(value)
引数
戻り値
指定した時刻における最初の Snowflake ID に変換した入力値を返します。Int64
例
使用例
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
┌─dateTime64ToSnowflake(dt64)─┐
│ 1426860704886947840 │
└─────────────────────────────┘
dateTime64ToSnowflakeID
導入バージョン: v24.6
DateTime64 の値を、指定時刻における最初の Snowflake ID に変換します。
実装の詳細については、セクション "Snowflake ID generation" を参照してください。
構文
dateTime64ToSnowflakeID(value[, epoch])
引数
value — 日時。DateTime または DateTime64epoch — Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0（1970-01-01）です。Twitter/X のエポック（2015-01-01）の場合は 1288834974657 を指定します。UInt*
戻り値
指定した時刻に対応する最初の Snowflake ID を返します。UInt64
例
使用例
SELECT toDateTime64('2025-08-15 18:57:56.493', 3, 'Asia/Shanghai') AS dt, dateTime64ToSnowflakeID(dt) AS res;
┌──────────────────────dt─┬─────────────────res─┐
│ 2025-08-15 18:57:56.493 │ 7362075066076495872 │
└─────────────────────────┴─────────────────────┘
dateTimeToSnowflake
導入バージョン: v21.10
DateTime の値を、指定された時刻における最初の Snowflake ID に変換します。
構文
dateTimeToSnowflake(value)
引数
返される値
入力値を、その時刻における最初の Snowflake ID として返します。Int64
例
使用例
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
┌─dateTimeToSnowflake(dt)─┐
│ 1426860702823350272 │
└─────────────────────────┘
dateTimeToSnowflakeID
導入: v24.6
DateTime 値を、その時刻に対応する最初の Snowflake ID に変換します。
構文
dateTimeToSnowflakeID(value[, epoch])
引数
value — 時刻付きの日付。DateTime または DateTime64epoch — 省略可。Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0（1970-01-01）。Twitter/X のエポック（2015-01-01）の場合は 1288834974657 を指定します。UInt*
戻り値
入力値の時刻に対応する最初の Snowflake ID を返します。UInt64
例
使用例
SELECT toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt, dateTimeToSnowflakeID(dt) AS res;
┌──────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56 │ 6832626392367104000 │
└─────────────────────┴─────────────────────┘
dateTimeToUUIDv7
導入バージョン: v25.9
指定された時刻において、DateTime 値を UUIDv7 に変換します。
UUID の構造、カウンター管理、および同時実行性の保証については、「UUIDv7 generation」 セクションを参照してください。
注記
2025 年 9 月時点では、バージョン 7 UUID はドラフト段階であり、そのレイアウトは将来的に変更される可能性があります。
構文
引数
戻り値
UUIDv7 を返します。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 │
└─────────────────────────────────────────────────────────────────────────┘
同一タイムスタンプに対応する複数の UUID
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
導入バージョン: v24.6
Snowflake ID を生成します。
関数 generateSnowflakeID は、同時に実行されているすべてのスレッドおよびクエリにおける関数呼び出し間で、タイムスタンプ内のカウンターフィールドが単調増加することを保証します。
実装の詳細については、「Snowflake ID の生成」 セクションを参照してください。
構文
generateSnowflakeID([expr, [machine_id]])
引数
expr — クエリ内で関数が複数回呼び出された場合に、共通部分式の除去 を回避するために使用される任意の 式。この式の値は、返される 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 │
└─────────────────────┘
1 行あたり複数の Snowflake ID が生成される
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│ 7199081609652224000 │ 7199081609652224001 │
└────────────────────────┴────────────────────────┘
式およびマシン ID を使用する場合
SELECT generateSnowflakeID('expr', 1);
┌─generateSnowflakeID('expr', 1)─┐
│ 7201148511606784002 │
└────────────────────────────────┘
generateUUIDv4
導入: v1.1
バージョン 4 の UUID を生成します。
構文
引数
expr — 省略可。クエリ内で関数が複数回呼び出される場合に、共通部分式除去 を回避するために使用される任意の式です。この式の値は、返される 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 │
└──────────────────────────────────────┴──────────────────────────────────────┘
generateUUIDv7
導入バージョン: v24.5
バージョン7の UUID を生成します。
UUIDv7 の構造、カウンター管理、および並行性の保証については、「UUIDv7 の生成」 セクションを参照してください。
注記
2025年9月時点では、バージョン7 UUID はドラフト段階であり、そのレイアウトは将来変更される可能性があります。
構文
引数
戻り値
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 │
└──────────────────────────────────────┴──────────────────────────────────────┘
readWKTLineString
導入バージョン: v
LineString 型ジオメトリの Well-Known Text (WKT) 表現を解析し、ClickHouse の内部形式で返します。
構文
readWKTLineString(wkt_string)
引数
wkt_string — LineString ジオメトリを表す入力 WKT 文字列。String
戻り値
この関数は、ClickHouse における LineString ジオメトリの内部表現を返します。
例
最初の呼び出し
SELECT readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)');
┌─readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)')─┐
│ [(1,1),(2,2),(3,3),(1,1)] │
└──────────────────────────────────────────────────────┘
2 回目の呼び出し
SELECT toTypeName(readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)'));
┌─toTypeName(readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)'))─┐
│ LineString │
└──────────────────────────────────────────────────────────────────┘
snowflakeIDToDateTime
導入バージョン: v24.6
Snowflake ID のタイムスタンプ部分を、DateTime 型の値として返します。
構文
snowflakeIDToDateTime(value[, epoch[, time_zone]])
引数
value — Snowflake ID。UInt64epoch — オプション。Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0（1970-01-01）です。Twitter/X のエポック（2015-01-01）の場合は 1288834974657 を指定します。UInt*time_zone — オプション。Timezone。この関数は、time_string を time_zone で指定されたタイムゾーンに従って解析します。String
戻り値
value のタイムスタンプ部分を返します。DateTime
例
使用例
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeIDToDateTime64
導入バージョン: v24.6
Snowflake ID のタイムスタンプ部分を DateTime64 型の値として返します。
構文
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
引数
value — Snowflake ID。UInt64epoch — オプション。Snowflake ID のエポックを、1970-01-01 からの経過ミリ秒で指定します。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) の場合は 1288834974657 を指定します。UInt*time_zone — オプション。Timezone。この関数は、指定されたタイムゾーンに従って time_string を解析します。String
返される値
value のタイムスタンプ部分を、スケール = 3 (ミリ秒単位の精度) の DateTime64 として返します。DateTime64
例
使用例
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
snowflakeToDateTime
導入バージョン: v21.10
Snowflake ID から DateTime 形式のタイムスタンプ部分を抽出します。
構文
snowflakeToDateTime(value[, time_zone])
引数
戻り値
value のタイムスタンプ部分を返します。DateTime
例
使用例
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
snowflakeToDateTime64
導入バージョン: v21.10
Snowflake ID のタイムスタンプ部分を DateTime64 形式で抽出します。
構文
snowflakeToDateTime64(value[, time_zone])
引数
value — Snowflake ID。Int64time_zone — 省略可能。Timezone。この関数は、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
導入バージョン: v21.1
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 が返されます
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 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
変換が失敗した場合はデフォルトの 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'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
toUUIDOrNull
導入バージョン: v20.12
入力値を UUID 型の値に変換しますが、エラーが発生した場合は NULL を返します。
toUUID と同様ですが、変換エラー時に例外をスローする代わりに NULL を返します。
サポートされる引数:
- 標準形式の UUID の文字列表現（8-4-4-4-12 桁の 16 進数）。
- ハイフンなしの UUID の文字列表現（32 桁の 16 進数）。
サポートされない引数（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 │ ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
