メインコンテンツまでスキップ
メインコンテンツまでスキップ

UUIDを扱うための関数

generateUUIDv4

バージョン4 UUIDを生成します。

構文

引数

  • expr — クエリ内で関数が複数回呼び出される場合に、共通部分式排除を回避するために使用される任意の。式の値は返されるUUIDには影響しません。オプション。

返される値

UUIDv4型の値。

まずUUID型のカラムを持つテーブルを作成し、その後生成したUUIDv4をテーブルに挿入します。

結果:

行ごとに複数のUUIDを生成した例

generateUUIDv7

バージョン7 UUIDを生成します。

生成されたUUIDには、ミリ秒単位の現在のUnixタイムスタンプ(48ビット)、バージョン「7」(4ビット)、ミリ秒内のUUIDを区別するためのカウンタ(42ビット)(バリアントフィールド「2」、2ビットを含む)、およびランダムフィールド(32ビット)が含まれます。 特定のタイムスタンプ(unix_ts_ms)に対して、カウンタはランダムな値から始まり、タイムスタンプが変わるまで新しいUUIDごとに1ずつ増加します。 カウンタがオーバーフローした場合、タイムスタンプフィールドは1ずつ増加し、カウンタはランダムな新しい開始値にリセットされます。

関数generateUUIDv7は、同時に実行されているスレッドとクエリのすべての関数呼び出しにおいて、タイムスタンプ内のカウンタフィールドが単調に増加することを保証します。

注記

2024年4月現在、バージョン7のUUIDは草案ステータスであり、そのレイアウトは将来的に変更される可能性があります。

構文

引数

  • expr — クエリ内で関数が複数回呼び出される場合に、共通部分式排除を回避するために使用される任意の。式の値は返される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またはFixedString
  • variantRFC4122で指定されたバリアントを表す整数。 1 = ビッグエンディアン(デフォルト)、2 = Microsoft

返される値

FixedString(16)

使用例

結果:

結果:

UUIDNumToString

UUIDのバイナリ表現を含むbinaryを受け取り、形式はオプションでvariant(デフォルトはビッグエンディアン)によって指定され、文字列を返します。文字列は36文字のテキスト形式です。

構文

引数

  • binary — UUIDのバイナリ表現としてのFixedString(16)
  • variantRFC4122で指定されたバリアントを表す整数。 1 = ビッグエンディアン(デフォルト)、2 = Microsoft

返される値

文字列。

使用例

結果:

結果:

UUIDToNum

UUIDを受け取り、そのバイナリ表現をFixedString(16)として返します。形式はオプションでvariant(デフォルトはビッグエンディアン)によって指定できます。この関数は、UUIDStringToNum(toString(uuid))の二つの別々の関数への呼び出しを置き換えるもので、UUIDから文字列への中間変換を必要とせずにUUIDからバイトを抽出できます。

構文

引数

  • uuidUUID
  • variantRFC4122で指定されたバリアントを表す整数。 1 = ビッグエンディアン(デフォルト)、2 = Microsoft

返される値

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

Deprecated feature
危険

この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。

Snowflake IDのタイムスタンプコンポーネントをDateTime形式で抽出します。

構文

引数

  • value — Snowflake ID。 Int64
  • time_zoneタイムゾーン。この関数は、time_stringをタイムゾーンに従って解析します。オプション。 String

返される値

  • valueのタイムスタンプコンポーネントをDateTime値として返します。

クエリ:

結果:

snowflakeToDateTime64

Deprecated feature
危険

この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。

Snowflake IDのタイムスタンプコンポーネントをDateTime64形式で抽出します。

構文

引数

  • value — Snowflake ID。 Int64
  • time_zoneタイムゾーン。この関数は、time_stringをタイムゾーンに従って解析します。オプション。 String

返される値

  • valueのタイムスタンプコンポーネントをスケール=3のDateTime64として返します。すなわち、ミリ秒精度です。

クエリ:

結果:

dateTimeToSnowflake

Deprecated feature
危険

この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。

DateTime値を指定された時刻の最初のSnowflake IDに変換します。

構文

引数

  • value — 日付と時刻。 DateTime

返される値

  • 入力値をInt64データ型に変換した値として、その時刻の最初のSnowflake IDを返します。

クエリ:

結果:

dateTime64ToSnowflake

Deprecated feature
危険

この関数は非推奨であり、設定allow_deprecated_snowflake_conversion_functionsが有効になっている場合のみ使用できます。 この関数は将来的に削除される予定です。

DateTime64を指定された時刻の最初のSnowflake IDに変換します。

構文

引数

返される値

  • 入力値を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を返します。

クエリ:

結果:

参照