33 KiB
| slug | sidebar_position | sidebar_label |
|---|---|---|
| /ja/sql-reference/functions/uuid-functions | 205 | UUIDs |
UUID を扱う関数
generateUUIDv4
構文
generateUUIDv4([expr])
引数
返される値
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
生成されたUUIDは、ミリ秒単位の現在のUnixタイムスタンプ（48ビット）、バージョン「7」（4ビット）、ミリ秒内でUUIDを区別するためのカウンタ（42ビット）、およびランダムフィールド（32ビット）を含みます。 特定のタイムスタンプ（unix_ts_ms）の場合、カウンタはランダムな値から始まり、新しいUUIDごとに1ずつ増加します。 カウンタがオーバーフローした場合、タイムスタンプフィールドは1増加し、カウンタはランダムな新しい開始値にリセットされます。
関数generateUUIDv7は、並行して実行されているスレッドおよびクエリ間で、タイムスタンプ内のカウンタフィールドが単調に増加することを保証します。
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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
:::note 2024年4月時点で、バージョン7のUUIDはドラフトステータスであり、将来そのレイアウトが変更される可能性があります。 :::
構文
generateUUIDv7([expr])
引数
返される値
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 │
└──────────────────────────────────────┴──────────────────────────────────────┘
empty
入力UUIDが空であるかどうかを確認します。
構文
empty(UUID)
UUIDはすべてのビットがゼロ（ゼロUUID）であるときに空と見なされます。
この関数はArraysやStringsに対しても機能します。
引数
x— UUID。 UUID。
返される値
- 空のUUIDの場合は
1、空でないUUIDの場合は0を返します。 UInt8。
例
UUID値を生成するために、ClickHouseはgenerateUUIDv4関数を提供します。
クエリ:
SELECT empty(generateUUIDv4());
結果:
┌─empty(generateUUIDv4())─┐
│ 0 │
└─────────────────────────┘
notEmpty
入力UUIDが空でないかどうかを確認します。
構文
notEmpty(UUID)
UUIDはすべてのビットがゼロ（ゼロUUID）であるときに空と見なされます。
この関数はArraysやStringsに対しても機能します。
引数
x— UUID。 UUID。
返される値
- 空でないUUIDの場合は
1、空のUUIDの場合は0を返します。 UInt8。
例
UUID値を生成するために、ClickHouseはgenerateUUIDv4関数を提供します。
クエリ:
SELECT notEmpty(generateUUIDv4());
結果:
┌─notEmpty(generateUUIDv4())─┐
│ 1 │
└────────────────────────────┘
toUUID
文字列型の値をUUIDに変換します。
toUUID(string)
返される値
UUID型の値。
使用例
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
結果:
┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
toUUIDOrDefault
引数
返される値
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
文字列型の引数を受け取り、UUIDへの変換を試みます。失敗した場合、NULLを返します。
toUUIDOrNull(string)
返される値
Nullable(UUID)型の値。
使用例
SELECT toUUIDOrNull('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
結果:
┌─uuid─┐
│ ᴺᵁᴸᴸ │
└──────┘
toUUIDOrZero
文字列型の引数を受け取り、UUIDへの変換を試みます。失敗した場合、ゼロUUIDを返します。
toUUIDOrZero(string)
返される値
UUID型の値。
使用例
SELECT toUUIDOrZero('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
結果:
┌─────────────────────────────────uuid─┐
│ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┘
UUIDStringToNum
36文字の形式xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxを含むstringを受け取り、そのバイナリ表現としてFixedString(16)を返します。形式はオプションでvariant (ビッグエンディアンがデフォルト)で指定可能です。
構文
UUIDStringToNum(string[, variant = 1])
引数
string— 36文字のStringまたはFixedString。variant— RFC4122に基づくバリアントを表す整数。1 =ビッグエンディアン(デフォルト), 2 =マイクロソフト。
返される値
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 (ビッグエンディアンがデフォルト)で指定し、テキスト形式の36文字を含む文字列を返します。
構文
UUIDNumToString(binary[, variant = 1])
引数
binary— UUIDのバイナリ表現としてのFixedString(16)。variant— RFC4122に基づくバリアントを表す整数。1 =ビッグエンディアン(デフォルト), 2 =マイクロソフト。
返される値
文字列。
使用例
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を受け取り、variant (ビッグエンディアンがデフォルトで指定可能)を指定して、そのバイナリ表現をFixedString(16)として返します。この関数はUUIDStringToNum(toString(uuid))の呼び出しを置き換え、UUIDからバイトを抽出する際にUUIDを文字列に中間変換する必要がなくなります。
構文
UUIDToNum(uuid[, variant = 1])
引数
返される値
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
バージョン7のUUIDのタイムスタンプコンポーネントを返します。
構文
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ファイルに保存され、サーバーの再起動間で保持されます。
構文
serverUUID()
返される値
- サーバーのUUID。 UUID。
generateSnowflakeID
スノーフレークIDを生成します。
生成されたスノーフレークIDは、ミリ秒単位の現在のUnixタイムスタンプ（41 + 1トップゼロビット）、マシンID（10ビット）、およびミリ秒内でIDを区別するためのカウンタ（12ビット）を含みます。 特定のタイムスタンプ（unix_ts_ms）の場合、カウンタは0から始まり、新しいスノーフレークIDごとに1ずつ増加します。 カウンタがオーバーフローした場合、タイムスタンプフィールドは1増加し、カウンタは0にリセットされます。
関数generateSnowflakeIDは、並行して実行されているスレッドおよびクエリ間で、タイムスタンプ内のカウンタフィールドが単調に増加することを保証します。
:::note 生成されたスノーフレークIDはUNIXエポック1970-01-01に基づいています。 スノーフレーク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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
構文
generateSnowflakeID([expr, [machine_id]])
引数
expr— クエリ内で関数が複数回呼ばれる場合に共通部分式の除去を回避するための任意の式。式の値は返されるスノーフレークIDに影響を与えません。省略可能。machine_id— マシンID、最下位10ビットが使用されます。 Int64。 省略可能。
返される値
UInt64型の値。
例
まず、UInt64型のカラムを持つテーブルを作成し、そのテーブルに生成されたスノーフレークIDを挿入します。
CREATE TABLE tab (id UInt64) ENGINE = Memory;
INSERT INTO tab SELECT generateSnowflakeID();
SELECT * FROM tab;
結果:
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
行ごとに複数のスノーフレークIDを生成する例
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│ 7199081609652224000 │ 7199081609652224001 │
└────────────────────────┴────────────────────────┘
式とマシンIDを使った例
SELECT generateSnowflakeID('expr', 1);
┌─generateSnowflakeID('expr', 1)─┐
│ 7201148511606784002 │
└────────────────────────────────┘
snowflakeToDateTime
:::warning この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsを有効にした場合のみ使用できます。 この関数は将来的に削除されます。 :::
スノーフレーク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
:::warning この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsを有効にした場合のみ使用できます。 この関数は将来的に削除されます。 :::
スノーフレークIDのタイムスタンプコンポーネントをDateTime64形式で抽出します。
構文
snowflakeToDateTime64(value[, time_zone])
引数
返される値
valueのタイムスタンプコンポーネントを、スケールが3、つまりミリ秒精度のDateTime64で返します。
例
クエリ:
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
結果:
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
dateTimeToSnowflake
:::warning この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsを有効にした場合のみ使用できます。 この関数は将来的に削除されます。 :::
DateTime値をその時点で最初のスノーフレークIDに変換します。
構文
dateTimeToSnowflake(value)
引数
value— 時間を含む日付。DateTime。
返される値
- 入力値を
Int64データ型のその時点での最初のスノーフレークIDに変換します。
例
クエリ:
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
結果:
┌─dateTimeToSnowflake(dt)─┐
│ 1426860702823350272 │
└─────────────────────────┘
dateTime64ToSnowflake
:::warning この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsを有効にした場合のみ使用できます。 この関数は将来的に削除されます。 :::
DateTime64をその時点で最初のスノーフレークIDに変換します。
構文
dateTime64ToSnowflake(value)
引数
value— 時間を含む日付。DateTime64。
返される値
- 入力値を
Int64データ型のその時点での最初のスノーフレークIDに変換します。
例
クエリ:
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
結果:
┌─dateTime64ToSnowflake(dt64)─┐
│ 1426860704886947840 │
└─────────────────────────────┘
snowflakeIDToDateTime
スノーフレークIDのタイムスタンプコンポーネントをDateTime型の値として返します。
構文
snowflakeIDToDateTime(value[, epoch[, time_zone]])
引数
value— スノーフレークID。 UInt64。epoch— 1970-01-01からのミリ秒単位のスノーフレーク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
スノーフレークIDのタイムスタンプコンポーネントをDateTime64型の値として返します。
構文
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
引数
value— スノーフレークID。 UInt64。epoch— 1970-01-01からのミリ秒単位のスノーフレークIDのエポック。デフォルトは0（1970-01-01）。Twitter/Xエポック（2015-01-01）の場合は1288834974657を指定します。省略可能。 UInt*。time_zone— タイムゾーン。関数はtime_stringをタイムゾーンに従って解析します。省略可能。 String。
返される値
valueのタイムスタンプコンポーネントをスケールが3、つまりミリ秒精度のDateTime64で返します。
例
クエリ:
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
結果:
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
dateTimeToSnowflakeID
DateTime値をその時点における最初のスノーフレークIDに変換します。
構文
dateTimeToSnowflakeID(value[, epoch])
引数
value— 時間を含む日付。DateTime。epoch— 1970-01-01からのミリ秒単位のスノーフレークIDのエポック。デフォルトは0（1970-01-01）。Twitter/Xエポック（2015-01-01）の場合は1288834974657を指定します。省略可能。 UInt*。
返される値
- 入力値をUInt64型のその時点の最初のスノーフレークIDに変換します。
例
クエリ:
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をその時点における最初のスノーフレークIDに変換します。
構文
dateTime64ToSnowflakeID(value[, epoch])
引数
value— 時間を含む日付。DateTime64。epoch— 1970-01-01からのミリ秒単位のスノーフレークIDのエポック。デフォルトは0（1970-01-01）。Twitter/Xエポック（2015-01-01）の場合は1288834974657を指定します。省略可能。 UInt*。
返される値
- 入力値をUInt64型のその時点の最初のスノーフレークIDに変換します。
例
クエリ:
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 │
└─────────────────────────┴─────────────────────┘