UUIDを扱うための関数
generateUUIDv4
構文
引数
返される値
UUIDv4型の値。
例
まずUUID型のカラムを持つテーブルを作成し、その後生成したUUIDv4をテーブルに挿入します。
結果:
行ごとに複数のUUIDを生成した例
generateUUIDv7
生成されたUUIDには、ミリ秒単位の現在のUnixタイムスタンプ(48ビット)、バージョン「7」(4ビット)、ミリ秒内のUUIDを区別するためのカウンタ(42ビット)(バリアントフィールド「2」、2ビットを含む)、およびランダムフィールド(32ビット)が含まれます。 特定のタイムスタンプ(unix_ts_ms)に対して、カウンタはランダムな値から始まり、タイムスタンプが変わるまで新しいUUIDごとに1ずつ増加します。 カウンタがオーバーフローした場合、タイムスタンプフィールドは1ずつ増加し、カウンタはランダムな新しい開始値にリセットされます。
関数generateUUIDv7
は、同時に実行されているスレッドとクエリのすべての関数呼び出しにおいて、タイムスタンプ内のカウンタフィールドが単調に増加することを保証します。
2024年4月現在、バージョン7のUUIDは草案ステータスであり、そのレイアウトは将来的に変更される可能性があります。
構文
引数
返される値
UUIDv7型の値。
例
まずUUID型のカラムを持つテーブルを作成し、その後生成したUUIDv7をテーブルに挿入します。
結果:
行ごとに複数のUUIDを生成した例
empty
入力UUIDが空であるかどうかをチェックします。
構文
UUIDは、すべてのゼロ(ゼロUUID)を含む場合、空であると見なされます。
引数
x
— UUID。 UUID。
返される値
- 空のUUIDの場合は
1
、非空のUUIDの場合は0
を返します。 UInt8。
例
UUID値を生成するには、ClickHouseが提供するgenerateUUIDv4関数を使用します。
クエリ:
結果:
notEmpty
入力UUIDが非空であるかどうかをチェックします。
構文
UUIDは、すべてのゼロ(ゼロUUID)を含む場合、空であると見なされます。
引数
x
— UUID。 UUID。
返される値
- 非空のUUIDの場合は
1
、空のUUIDの場合は0
を返します。 UInt8。
例
UUID値を生成するには、ClickHouseが提供するgenerateUUIDv4関数を使用します。
クエリ:
結果:
toUUID
String型の値をUUIDに変換します。
返される値
UUID型の値。
使用例
結果:
toUUIDOrDefault
引数
string
— 36文字の文字列またはFixedString(36)。 String。default
— 最初の引数をUUID型に変換できない場合のデフォルトとして使用されるUUID。 UUID。
返される値
UUID
返される値
UUID型の値。
使用例
この最初の例は、最初の引数をUUID型に変換可能なため、UUID型に変換された値を返します。
結果:
この2番目の例は、1番目の引数をUUID型に変換できないため、2番目の引数(提供されたデフォルトUUID)を返します。
結果:
toUUIDOrNull
String型の引数を受け取り、UUIDに解析しようとします。失敗した場合はNULLを返します。
返される値
Nullable(UUID)型の値。
使用例
結果:
toUUIDOrZero
String型の引数を受け取り、UUIDに解析しようとします。失敗した場合はゼロUUIDを返します。
返される値
UUID型の値。
使用例
結果:
UUIDStringToNum
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
形式の36文字を含むstring
を受け取り、そのバイナリ表現をFixedString(16)として返します。形式は、variant
(デフォルトはビッグエンディアン
)によってオプションで指定できます。
構文
引数
string
— 36文字のStringまたはFixedStringvariant
— RFC4122で指定されたバリアントを表す整数。 1 =ビッグエンディアン
(デフォルト)、2 =Microsoft
。
返される値
FixedString(16)
使用例
結果:
結果:
UUIDNumToString
UUIDのバイナリ表現を含むbinary
を受け取り、形式はオプションでvariant
(デフォルトはビッグエンディアン
)によって指定され、文字列を返します。文字列は36文字のテキスト形式です。
構文
引数
binary
— UUIDのバイナリ表現としてのFixedString(16)。variant
— RFC4122で指定されたバリアントを表す整数。 1 =ビッグエンディアン
(デフォルト)、2 =Microsoft
。
返される値
文字列。
使用例
結果:
結果:
UUIDToNum
UUIDを受け取り、そのバイナリ表現をFixedString(16)として返します。形式はオプションでvariant
(デフォルトはビッグエンディアン
)によって指定できます。この関数は、UUIDStringToNum(toString(uuid))
の二つの別々の関数への呼び出しを置き換えるもので、UUIDから文字列への中間変換を必要とせずにUUIDからバイトを抽出できます。
構文
引数
返される値
UUIDのバイナリ表現。
使用例
結果:
結果:
UUIDv7ToDateTime
UUIDバージョン7のタイムスタンプコンポーネントを返します。
構文
引数
返される値
- ミリ秒精度のタイムスタンプ。UUIDが有効なバージョン7 UUIDでない場合は、1970-01-01 00:00:00.000を返します。 DateTime64(3)。
使用例
結果:
結果:
serverUUID
ClickHouseサーバーの最初の起動時に生成されたランダムUUIDを返します。このUUIDはClickHouseサーバーディレクトリ(例: /var/lib/clickhouse/
)内のuuid
ファイルに保存され、サーバーの再起動間で保持されます。
構文
返される値
- サーバーのUUID。 UUID。
generateSnowflakeID
Snowflake IDを生成します。
生成されたSnowflake IDには、ミリ秒単位の現在のUnixタイムスタンプ(41 + 1のトップゼロビット)、機械ID(10ビット)、およびミリ秒内のIDを区別するためのカウンタ(12ビット)が含まれます。 特定のタイムスタンプ(unix_ts_ms)に対して、カウンタは0から始まり、タイムスタンプが変わるまで新しいSnowflake IDごとに1ずつ増加します。 カウンタがオーバーフローした場合、タイムスタンプフィールドは1ずつ増加し、カウンタは0にリセットされます。
関数generateSnowflakeID
は、タイムスタンプ内のカウンタフィールドが単調に増加することをすべての関数呼び出しにおいて保証します。
生成されたSnowflake IDはUNIXエポック1970-01-01に基づいています。 Snowflake IDのエポックに関する標準や推奨は存在しませんが、他のシステムでの実装では異なるエポック(例:Twitter/X(2010-11-04)やMastodon(2015-01-01))を使用している場合があります。
構文
引数
expr
— クエリ内で関数が複数回呼び出される場合に、共通部分式排除を回避するために使用される任意の式。式の値は返されるSnowflake IDには影響しません。オプション。machine_id
— マシンID、最下位10ビットが使用されます。 Int64。オプション。
返される値
UInt64型の値。
例
まずUInt64型のカラムを持つテーブルを作成し、その後生成したSnowflake IDをテーブルに挿入します。
結果:
行ごとに複数のSnowflake IDを生成した例
式とマシンIDを使用した例
snowflakeToDateTime
この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。
Snowflake IDのタイムスタンプコンポーネントをDateTime形式で抽出します。
構文
引数
返される値
value
のタイムスタンプコンポーネントをDateTime値として返します。
例
クエリ:
結果:
snowflakeToDateTime64
この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。
Snowflake IDのタイムスタンプコンポーネントをDateTime64形式で抽出します。
構文
引数
返される値
value
のタイムスタンプコンポーネントをスケール=3のDateTime64として返します。すなわち、ミリ秒精度です。
例
クエリ:
結果:
dateTimeToSnowflake
この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。
DateTime値を指定された時刻の最初のSnowflake IDに変換します。
構文
引数
value
— 日付と時刻。 DateTime。
返される値
- 入力値をInt64データ型に変換した値として、その時刻の最初のSnowflake IDを返します。
例
クエリ:
結果:
dateTime64ToSnowflake
この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。
DateTime64を指定された時刻の最初のSnowflake IDに変換します。
構文
引数
value
— 日付と時刻。 DateTime64。
返される値
- 入力値をInt64データ型に変換した値として、その時刻の最初のSnowflake IDを返します。
例
クエリ:
結果:
snowflakeIDToDateTime
Snowflake IDのタイムスタンプコンポーネントをDateTime型の値として返します。
構文
引数
value
— Snowflake ID。 UInt64。epoch
- Snowflake IDのエポック(1970-01-01からのミリ秒)。デフォルトは0(1970-01-01)。Twitter/Xのエポック(2015-01-01)の場合は1288834974657を指定します。オプション。 UInt*。time_zone
— タイムゾーン。この関数は、time_string
をタイムゾーンに従って解析します。オプション。 String。
返される値
value
のタイムスタンプコンポーネントをDateTime値として返します。
例
クエリ:
結果:
snowflakeIDToDateTime64
Snowflake IDのタイムスタンプコンポーネントをDateTime64型の値として返します。
構文
引数
value
— Snowflake ID。 UInt64。epoch
- Snowflake IDのエポック(1970-01-01からのミリ秒)。デフォルトは0(1970-01-01)。Twitter/Xのエポック(2015-01-01)の場合は1288834974657を指定します。オプション。 UInt*。time_zone
— タイムゾーン。この関数は、time_string
をタイムゾーンに従って解析します。オプション。 String。
返される値
value
のタイムスタンプコンポーネントをスケール=3のDateTime64として返します。すなわち、ミリ秒精度です。
例
クエリ:
結果:
dateTimeToSnowflakeID
DateTime値を指定された時刻の最初のSnowflake IDに変換します。
構文
引数
value
— 日付と時刻。 DateTime。epoch
- Snowflake IDのエポック(1970-01-01からのミリ秒)。デフォルトは0(1970-01-01)。Twitter/Xのエポック(2015-01-01)の場合は1288834974657を指定します。オプション。 UInt*。
返される値
- 入力値をUInt64として変換した値。その時刻の最初のSnowflake IDを返します。
例
クエリ:
結果:
dateTime64ToSnowflakeID
DateTime64を指定された時刻の最初のSnowflake IDに変換します。
構文
引数
value
— 日付と時刻。 DateTime64。epoch
- Snowflake IDのエポック(1970-01-01からのミリ秒)。デフォルトは0(1970-01-01)。Twitter/Xのエポック(2015-01-01)の場合は1288834974657を指定します。オプション。 UInt*。
返される値
- 入力値をUInt64として変換した値。その時刻の最初のSnowflake IDを返します。
例
クエリ:
結果: