> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> UUIDsを扱う関数のドキュメント

# UUIDsを扱う関数

export const DeprecatedBadge = () => {
  return <div className="deprecatedBadge">
            <div className="deprecatedIcon">
            <svg width="14" height="10" viewBox="0 0 14 10" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M13 0H1C0.734784 0 0.48043 0.105357 0.292893 0.292893C0.105357 0.48043 0 0.734784 0 1V2.5C0 2.76522 0.105357 3.01957 0.292893 3.20711C0.48043 3.39464 0.734784 3.5 1 3.5V9C1 9.26522 1.10536 9.51957 1.29289 9.70711C1.48043 9.89464 1.73478 10 2 10H12C12.2652 10 12.5196 9.89464 12.7071 9.70711C12.8946 9.51957 13 9.26522 13 9V3.5C13.2652 3.5 13.5196 3.39464 13.7071 3.20711C13.8946 3.01957 14 2.76522 14 2.5V1C14 0.734784 13.8946 0.48043 13.7071 0.292893C13.5196 0.105357 13.2652 0 13 0ZM12 9H2V3.5H12V9ZM13 2.5H1V1H13V2.5ZM5 5.5C5 5.36739 5.05268 5.24021 5.14645 5.14645C5.24021 5.05268 5.36739 5 5.5 5H8.5C8.63261 5 8.75979 5.05268 8.85355 5.14645C8.94732 5.24021 9 5.36739 9 5.5C9 5.63261 8.94732 5.75979 8.85355 5.85355C8.75979 5.94732 8.63261 6 8.5 6H5.5C5.36739 6 5.24021 5.94732 5.14645 5.85355C5.05268 5.75979 5 5.63261 5 5.5Z" fill="currentColor" />
            </svg>
        </div>
            Deprecated feature
        </div>;
};

<div id="uuidv7-generation">
  ## UUIDv7 の生成
</div>

生成される UUID には、Unix ミリ秒の 48 ビットのタイムスタンプが含まれ、その後にバージョン "7" (4 ビット) 、同一ミリ秒内で UUID を区別するためのカウンター (42 ビット。バリアントフィールド "2" の 2 ビットを含む) 、およびランダムフィールド (32 ビット) が続きます。
任意のタイムスタンプ (`unix_ts_ms`) について、カウンターはランダムな値から開始され、タイムスタンプが変わるまで、新しい UUID が生成されるたびに 1 ずつ増加します。カウンターがオーバーフローした場合は、タイムスタンプフィールドが 1 増加し、カウンターは新しいランダムな開始値にリセットされます。
UUID 生成関数は、あるタイムスタンプ内のカウンターフィールドが、同時実行中のすべてのスレッドおよびクエリにわたる関数呼び出し全体で単調増加することを保証します。

```text theme={null}
 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
```

<div id="snowflake-id-generation">
  ## Snowflake ID の生成
</div>

生成される Snowflake ID には、現在の Unixタイムスタンプ (ミリ秒単位、41 ビット + 最上位の 0 ビット 1 つ) 、続いてマシン ID (10 ビット) 、さらに同一ミリ秒内の ID を区別するためのカウンター (12 ビット) が含まれます。任意のタイムスタンプ (`unix_ts_ms`) に対して、カウンターは 0 から始まり、タイムスタンプが変わるまで新しい Snowflake ID が生成されるたびに 1 ずつ増加します。カウンターがオーバーフローした場合は、タイムスタンプのフィールドが 1 増やされ、カウンターは 0 にリセットされます。

<Note>
  生成される Snowflake ID は、UNIX エポック である 1970-01-01 を基準としています。Snowflake ID の エポック には標準や推奨事項はありませんが、他のシステムの実装では別の エポック が使われている場合があります。たとえば、Twitter/X (2010-11-04) や Mastodon (2015-01-01) です。
</Note>

```text theme={null}
 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    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
```

{/*AUTOGENERATED_START*/}

<div id="UUIDNumToString">
  ## UUIDNumToString
</div>

導入バージョン: v1.1.0

UUID のバイナリ表現を受け取り、`variant` でそのフォーマットを任意に指定できます (デフォルトは `Big-endian`) 。テキスト形式の 36 文字の文字列を返します。

**構文**

```sql theme={null}
UUIDNumToString(binary[, variant])
```

**引数**

* `binary` — UUID のバイナリ表現。[`FixedString(16)`](/ja/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1) で規定されたバリアント。1 = `Big-endian` (デフォルト) 、2 = `Microsoft`。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

UUID を文字列として返します。[`String`](/ja/reference/data-types/string)

**例**

**使用例**

```sql title=Query theme={null}
SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid
```

```response title=Response theme={null}
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
```

**Microsoft バリアント**

```sql title=Query theme={null}
SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
```

```response title=Response theme={null}
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
```

<div id="UUIDStringToNum">
  ## UUIDStringToNum
</div>

導入バージョン: v1.1.0

`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` 形式の36文字の文字列を受け取り、そのバイナリ表現として [FixedString(16)](/ja/reference/data-types/fixedstring) を返します。必要に応じて `variant` でフォーマットを指定でき、デフォルトは `Big-endian` です。

**構文**

```sql theme={null}
UUIDStringToNum(string[, variant = 1])
```

**引数**

* `string` — 36 文字の文字列、または固定長文字列。[`String`](/ja/reference/data-types/string) または [`FixedString(36)`](/ja/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1) で規定される バリアント。1 = `Big-endian` (デフォルト) 、2 = `Microsoft`。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

`string` のバイナリ表現を返します。[`FixedString(16)`](/ja/reference/data-types/fixedstring)

**例**

**使用例**

```sql title=Query theme={null}
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

**Microsoft バリアント**

```sql title=Query theme={null}
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

<div id="UUIDToNum">
  ## UUIDToNum
</div>

導入バージョン: v24.5.0

[UUID](/ja/reference/data-types/uuid) を受け取り、そのバイナリ表現を [FixedString(16)](/ja/reference/data-types/fixedstring) として返します。フォーマットは `variant` で指定でき、デフォルトは `Big-endian` です。
この関数は、2 つの個別の関数 `UUIDStringToNum(toString(uuid))` の呼び出しを置き換えるもので、UUID からバイトを抽出するために UUID を文字列へ中間変換する必要がありません。

**構文**

```sql theme={null}
UUIDToNum(uuid[, variant = 1])
```

**引数**

* `uuid` — UUID。[`String`](/ja/reference/data-types/string) または [`FixedString`](/ja/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1) で規定されているバリアント。1 = `Big-endian` (デフォルト) 、2 = `Microsoft`。[`(U)Int*`](/ja/reference/data-types/int-uint)

**戻り値**

UUID のバイナリ表現を返します。[`FixedString(16)`](/ja/reference/data-types/fixedstring)

**例**

**使用例**

```sql title=Query theme={null}
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

**Microsoft バリアント**

```sql title=Query theme={null}
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid, 2) AS bytes
```

```response title=Response theme={null}
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
```

<div id="UUIDv7ToDateTime">
  ## UUIDv7ToDateTime
</div>

導入バージョン: v24.5.0

UUIDバージョン7のタイムスタンプ部分を返します。

**構文**

```sql theme={null}
UUIDv7ToDateTime(uuid[, timezone])
```

**引数**

* `uuid` — UUIDバージョン7。[`String`](/ja/reference/data-types/string)
* `timezone` — 任意。戻り値に使用する[タイムゾーン名](/ja/reference/settings/server-settings/settings#timezone)。[`String`](/ja/reference/data-types/string)

**戻り値**

ミリ秒精度のタイムスタンプを返します。UUIDが有効なバージョン7 UUIDでない場合は、`1970-01-01 00:00:00.000`を返します。[`DateTime64(3)`](/ja/reference/data-types/datetime64)

**例**

**使用例**

```sql title=Query theme={null}
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
```

```response title=Response theme={null}
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
```

**タイムゾーン付き**

```sql title=Query theme={null}
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
```

```response title=Response theme={null}
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                             2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="dateTime64ToSnowflake">
  ## dateTime64ToSnowflake
</div>

導入バージョン: v21.10.0

<Warning>
  この関数は非推奨であり、設定 [`allow_deprecated_snowflake_conversion_functions`](/ja/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) が有効な場合にのみ使用できます。
  この関数は将来のいずれかの時点で削除される予定です。

  代わりに関数 [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID) を使用してください。
</Warning>

[DateTime64](/ja/reference/data-types/datetime64) を、指定した時刻に対応する最初の [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) に変換します。

**構文**

```sql theme={null}
dateTime64ToSnowflake(value)
```

**引数**

* `value` — 日時。[`DateTime64`](/ja/reference/data-types/datetime64)

**戻り値**

指定した時点における最初の Snowflake ID に変換された入力値を返します。[`Int64`](/ja/reference/data-types/int-uint)

**例**

**使用例**

```sql title=Query theme={null}
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
```

```response title=Response theme={null}
┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘
```

<div id="dateTime64ToSnowflakeID">
  ## dateTime64ToSnowflakeID
</div>

導入バージョン: v24.6.0

[DateTime64](/ja/reference/data-types/datetime64) の値を、指定した時刻に対応する最初の [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) に変換します。

**構文**

```sql theme={null}
dateTime64ToSnowflakeID(value[, epoch])
```

**引数**

* `value` — 日時。[`DateTime64`](/ja/reference/data-types/datetime64)
* `epoch` — 1970-01-01 からの経過ミリ秒で表した Snowflake ID のエポック。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) を使用する場合は、1288834974657 を指定します。[`UInt*`](/ja/reference/data-types/int-uint)

**戻り値**

[`UInt64`](/ja/reference/data-types/int-uint) に変換された入力値

**例**

**simple**

```sql title=Query theme={null}
SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
```

```response title=Response theme={null}
6832626394434895872
```

<div id="dateTimeToSnowflake">
  ## dateTimeToSnowflake
</div>

導入バージョン: v21.10.0

<Warning>
  この関数は非推奨であり、設定 [`allow_deprecated_snowflake_conversion_functions`](/ja/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) が有効な場合にのみ使用できます。
  この関数は今後削除される予定です。

  代わりに関数 [dateTimeToSnowflakeID](#dateTimeToSnowflakeID) を使用してください。
</Warning>

[DateTime](/ja/reference/data-types/datetime) の値を、指定した時刻における最初の [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) に変換します。

**構文**

```sql theme={null}
dateTimeToSnowflake(value)
```

**引数**

* `value` — 日時。[`DateTime`](/ja/reference/data-types/datetime)

**戻り値**

入力された日時における最初の Snowflake ID を返します。[`Int64`](/ja/reference/data-types/int-uint)

**例**

**使用例**

```sql title=Query theme={null}
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
```

```response title=Response theme={null}
┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘
```

<div id="dateTimeToSnowflakeID">
  ## dateTimeToSnowflakeID
</div>

導入バージョン: v24.6.0

[DateTime](/ja/reference/data-types/datetime) の値を、指定した時刻における最初の [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) に変換します。

**構文**

```sql theme={null}
dateTimeToSnowflakeID(value[, epoch])
```

**引数**

* `value` — 日時。[`DateTime`](/ja/reference/data-types/datetime)
* `epoch` — 1970-01-01 からの経過ミリ秒で表した Snowflake ID の epoch。デフォルトは 0 (1970-01-01) です。Twitter/X の epoch (2015-01-01) の場合は、1288834974657 を指定します。[`UInt*`](/ja/reference/data-types/int-uint)

**戻り値**

[`UInt64`](/ja/reference/data-types/int-uint) に変換された入力値

**例**

**simple**

```sql title=Query theme={null}
SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))
```

```response title=Response theme={null}
6832626392367104000
```

<div id="dateTimeToUUIDv7">
  ## dateTimeToUUIDv7
</div>

導入バージョン: v25.8.0

指定した時刻の [DateTime](/ja/reference/data-types/datetime) 値を [UUIDv7](https://en.wikipedia.org/wiki/UUID#Version_7) に変換します。

UUID の構造、カウンターの管理方法、および同時実行時の保証の詳細については、["UUIDv7 の生成"](#uuidv7-generation) セクションを参照してください。

<Note>
  2025年9月時点では、バージョン 7 UUID はドラフト段階にあり、今後レイアウトが変更される可能性があります。
</Note>

**構文**

```sql theme={null}
dateTimeToUUIDv7(value)
```

**引数**

* `value` — 日時。[`DateTime`](/ja/reference/data-types/datetime)

**戻り値**

UUIDv7を返します。[`UUID`](/ja/reference/data-types/uuid)

**例**

**使用例**

```sql title=Query theme={null}
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));
```

```response title=Response theme={null}
┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘
```

**同じタイムスタンプに対して複数のUUID**

```sql title=Query theme={null}
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
```

```response title=Response theme={null}
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘
```

<div id="generateSnowflakeID">
  ## generateSnowflakeID
</div>

導入バージョン: v24.6.0

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) を生成します。

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

実装の詳細については、["Snowflake ID generation"](#snowflake-id-generation) セクションを参照してください。

**構文**

```sql theme={null}
generateSnowflakeID([expr, [machine_id]])
```

**引数**

* `expr` — 関数が1つのクエリ内で複数回呼び出される場合に、[共通部分式除去](/ja/reference/functions/regular-functions/overview#common-subexpression-elimination)を回避するための任意の[式](/ja/reference/syntax#expressions)です。この式の値は、返される Snowflake ID には影響しません。省略可能です。 - `machine_id` — マシン ID。下位 10 ビットが使用されます。[Int64](/ja/reference/data-types/int-uint)。省略可能です。

**戻り値**

Snowflake ID を返します。[`UInt64`](/ja/reference/data-types/int-uint)

**例**

**使用例**

```sql title=Query theme={null}
CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;
```

```response title=Response theme={null}
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
```

**各行につき複数の Snowflake ID が生成される**

```sql title=Query theme={null}
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
```

```response title=Response theme={null}
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘
```

**式とマシン ID を使用する場合**

```sql title=Query theme={null}
SELECT generateSnowflakeID('expr', 1);
```

```response title=Response theme={null}
┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘
```

<div id="generateUUIDv4">
  ## generateUUIDv4
</div>

導入バージョン: v1.1.0

[バージョン 4](https://tools.ietf.org/html/rfc4122#section-4.4) の [UUID](/ja/reference/data-types/uuid) を生成します。

**構文**

```sql theme={null}
generateUUIDv4([expr])
```

**引数**

* `expr` — 省略可。関数が1つのクエリ内で複数回呼び出される場合に、[共通部分式除去](/ja/reference/functions/regular-functions/overview#common-subexpression-elimination)を回避するために使われる任意の式です。式の値は、返される UUID には影響しません。

**戻り値**

UUIDv4 を返します。[`UUID`](/ja/reference/data-types/uuid)

**例**

**使用例**

```sql title=Query theme={null}
SELECT generateUUIDv4(number) FROM numbers(3);
```

```response title=Response theme={null}
┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘
```

**共通部分式除去**

```sql title=Query theme={null}
SELECT generateUUIDv4(1), generateUUIDv4(1);
```

```response title=Response theme={null}
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```

<div id="generateUUIDv7">
  ## generateUUIDv7
</div>

導入バージョン: v24.5.0

[version 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04) [UUID](/ja/reference/data-types/uuid) を生成します。

UUID の構造、カウンター管理、および同時実行性の保証の詳細については、["UUIDv7 の生成"](#uuidv7-generation) セクションを参照してください。

<Note>
  2025 年 9 月時点では、バージョン 7 UUID はドラフト段階にあり、今後レイアウトが変更される可能性があります。
</Note>

**構文**

```sql theme={null}
generateUUIDv7([expr])
```

**引数**

* `expr` — オプション。関数が1つのクエリ内で複数回呼び出される場合に、[共通部分式除去](/ja/reference/functions/regular-functions/overview#common-subexpression-elimination)を回避するために使用する任意の式です。この式の値は、返される UUID に影響しません。[`Any`](/ja/reference/data-types)

**戻り値**

UUIDv7 を返します。[`UUID`](/ja/reference/data-types/uuid)

**例**

**使用例**

```sql title=Query theme={null}
SELECT generateUUIDv7(number) FROM numbers(3);
```

```response title=Response theme={null}
┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘
```

**共通部分式除去**

```sql title=Query theme={null}
SELECT generateUUIDv7(1), generateUUIDv7(1);
```

```response title=Response theme={null}
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```

<div id="snowflakeIDToDateTime">
  ## snowflakeIDToDateTime
</div>

導入バージョン: v24.6.0

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) のタイムスタンプ部分を、[DateTime](/ja/reference/data-types/datetime) 型の値として返します。

**構文**

```sql theme={null}
snowflakeIDToDateTime(value[, epoch[, time_zone]])
```

**引数**

* `value` — Snowflake ID。[`UInt64`](/ja/reference/data-types/int-uint)
* `epoch` — 省略可能。1970-01-01 からのミリ秒単位で表した Snowflake ID のエポックです。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) の場合は、1288834974657 を指定します。[`UInt*`](/ja/reference/data-types/int-uint)
* `time_zone` — 省略可能。[タイムゾーン](/ja/reference/settings/server-settings/settings#timezone)。関数は `time_string` をこのタイムゾーンに従って解析します。[`String`](/ja/reference/data-types/string)

**戻り値**

`value` のタイムスタンプ部分を返します。[`DateTime`](/ja/reference/data-types/datetime)

**例**

**使用例**

```sql title=Query theme={null}
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
```

```response title=Response theme={null}
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
```

<div id="snowflakeIDToDateTime64">
  ## snowflakeIDToDateTime64
</div>

導入バージョン: v24.6.0

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) のタイムスタンプ部分を、[DateTime64](/ja/reference/data-types/datetime64) 型の値として返します。

**構文**

```sql theme={null}
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
```

**引数**

* `value` — Snowflake ID。[`UInt64`](/ja/reference/data-types/int-uint)
* `epoch` — 省略可能。1970-01-01 からの経過ミリ秒で表される Snowflake ID のエポック。デフォルトは 0 (1970-01-01) です。Twitter/X のエポック (2015-01-01) の場合は、1288834974657 を指定します。[`UInt*`](/ja/reference/data-types/int-uint)
* `time_zone` — 省略可能。[タイムゾーン](/ja/reference/settings/server-settings/settings#timezone)。この関数は、タイムゾーンに従って `time_string` を解析します。[`String`](/ja/reference/data-types/string)

**戻り値**

`value` のタイムスタンプ部分を、scale = 3、つまりミリ秒精度の `DateTime64` として返します。[`DateTime64`](/ja/reference/data-types/datetime64)

**例**

**使用例**

```sql title=Query theme={null}
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
```

```response title=Response theme={null}
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
```

<div id="snowflakeToDateTime">
  ## snowflakeToDateTime
</div>

導入バージョン: v21.10.0

<Warning>
  この関数は非推奨であり、設定 [`allow_deprecated_snowflake_conversion_functions`](/ja/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) が有効な場合にのみ使用できます。
  この関数は今後削除される予定です。

  代わりに [`snowflakeIDToDateTime`](#snowflakeIDToDateTime) 関数を使用してください。
</Warning>

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) のタイムスタンプ部分を [DateTime](/ja/reference/data-types/datetime) フォーマットで抽出します。

**構文**

```sql theme={null}
snowflakeToDateTime(value[, time_zone])
```

**引数**

* `value` — Snowflake ID。[`Int64`](/ja/reference/data-types/int-uint)
* `time_zone` — 任意。[タイムゾーン](/ja/reference/settings/server-settings/settings#timezone)。この関数は、`time_string` をタイムゾーンに従って解析します。[`String`](/ja/reference/data-types/string)

**戻り値**

`value` のタイムスタンプ部分を返します。[`DateTime`](/ja/reference/data-types/datetime)

**例**

**使用例**

```sql title=Query theme={null}
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
```

```response title=Response theme={null}
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
```

<div id="snowflakeToDateTime64">
  ## snowflakeToDateTime64
</div>

導入バージョン: v21.10.0

<Warning>
  この関数は非推奨であり、設定 [`allow_deprecated_snowflake_conversion_functions`](/ja/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) が有効になっている場合にのみ使用できます。
  この関数は将来的に削除される予定です。

  代わりに [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64) 関数を使用してください。
</Warning>

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) の タイムスタンプ部分 を [DateTime64](/ja/reference/data-types/datetime64) 形式で抽出します。

**構文**

```sql theme={null}
snowflakeToDateTime64(value[, time_zone])
```

**引数**

* `value` — Snowflake ID。[`Int64`](/ja/reference/data-types/int-uint)
* `time_zone` — 任意。[タイムゾーン](/ja/reference/settings/server-settings/settings#timezone)。この関数は、タイムゾーンに従って `time_string` を解析します。[`String`](/ja/reference/data-types/string)

**戻り値**

`value` のタイムスタンプ部分を返します。[`DateTime64(3)`](/ja/reference/data-types/datetime64)

**例**

**使用例**

```sql title=Query theme={null}
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
```

```response title=Response theme={null}
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
```

<div id="toUUIDOrDefault">
  ## toUUIDOrDefault
</div>

導入バージョン: v21.1.0

String 型の値を UUID 型に変換します。変換に失敗した場合は、error を throw する代わりに、デフォルトの UUID 値を返します。

この関数は、標準的な UUID フォーマット (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) の 36 文字の文字列を解析します。
文字列を有効な UUID に変換できない場合、この関数は指定されたデフォルトの UUID 値を返します。

**構文**

```sql theme={null}
toUUIDOrDefault(string, default)
```

**引数**

* `string` — UUID に変換する 36 文字の文字列、または FixedString(36)。 - `default` — 最初の引数を UUID 型に変換できない場合に返される UUID 値。

**戻り値**

変換に成功した場合は変換後の UUID を返し、変換に失敗した場合はデフォルトの UUID を返します。 [`UUID`](/ja/reference/data-types/uuid)

**例**

**変換に成功した場合は、パースされた UUID が返されます**

```sql title=Query theme={null}
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
```

```response title=Response theme={null}
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

**変換に失敗した場合、デフォルトのUUIDを返します**

```sql title=Query theme={null}
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
```

```response title=Response theme={null}
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="toUUIDOrNull">
  ## toUUIDOrNull
</div>

導入バージョン: v20.12.0

入力値を `UUID` 型の値に変換します。エラーが発生した場合は `NULL` を返します。

[`toUUID`](/ja/reference/functions/regular-functions/type-conversion-functions#toUUID) と同様ですが、変換エラー時に例外をスローする代わりに `NULL` を返します。

サポートされる引数:

* 標準形式 (8-4-4-4-12 桁の16進数) の UUID の文字列表現。
* ハイフンなし (32 桁の16進数) の UUID の文字列表現。

サポートされない引数 (`NULL` を返します) :

* 無効な文字列形式。
* 文字列以外の型。
* 形式が不正な UUID。

**構文**

```sql theme={null}
toUUIDOrNull(x)
```

**引数**

* `x` — UUIDの文字列表現。[`String`](/ja/reference/data-types/string)

**戻り値**

成功した場合はUUID値を返し、失敗した場合は `NULL` を返します。[`UUID`](/ja/reference/data-types/uuid) または [`NULL`](/ja/reference/syntax#null)

**例**

**使用例**

```sql title=Query theme={null}
SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid
```

```response title=Response theme={null}
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
```