> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.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>
            已弃用功能
        </div>;
};

<div id="functions-for-working-with-uuids">
  # UUIDs 相关函数
</div>

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

生成的 UUID 包含一个 48 位的 Unix 毫秒 timestamp，后面依次为版本 "7" (4 位) 、用于区分同一毫秒内 UUID 的计数器 (42 位，其中包含一个值为 "2" 的 Variant 字段，占 2 位) ，以及一个随机字段 (32 位) 。
对于任意给定的 timestamp (`unix_ts_ms`) ，计数器都会从一个随机值开始，并在每生成一个新的 UUID 时加 1，直到 timestamp 发生变化。如果计数器溢出，则 timestamp 字段加 1，并将计数器重置为一个新的随机起始值。
UUID 生成函数保证：对于同一个 timestamp，在并发运行的线程和 queries 中，计数器字段在所有函数调用中都会单调递增。

```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 位，加上最高位的 1 个零位) ，后面依次是机器 ID (10 位) 和计数器 (12 位) ，用于区分同一毫秒内生成的不同 ID。对于任意给定的时间戳 (`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)`](/zh/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1) 中规定的 Variant。1 = `Big-endian` (默认) ，2 = `Microsoft`。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 UUID 的字符串形式。[`String`](/zh/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

接受一个包含 36 个字符、格式为 `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` 的字符串，并返回表示其二进制形式的 [FixedString(16)](/zh/reference/data-types/fixedstring)；其格式可通过 `variant` 指定 (默认为 `Big-endian`) 。

**语法**

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

**参数**

* `string` — 36 个字符的字符串或定长字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString(36)`](/zh/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1) 中定义的 Variant。1 = `Big-endian` (默认) ，2 = `Microsoft`。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 `string` 的二进制表示。[`FixedString(16)`](/zh/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](/zh/reference/data-types/uuid)，并以 [FixedString(16)](/zh/reference/data-types/fixedstring) 形式返回其二进制表示；其格式可通过 `variant` 指定 (默认为 `Big-endian`) 。
此函数可替代对两个独立函数 `UUIDStringToNum(toString(uuid))` 的调用，因此无需先将 UUID 转换为字符串再提取其中的字节。

**语法**

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

**参数**

* `uuid` — UUID。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1) 中定义的 Variant。1 = `Big-endian` (默认) ，2 = `Microsoft`。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 UUID 的二进制表示。[`FixedString(16)`](/zh/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`](/zh/reference/data-types/string)
* `timezone` — 可选。返回值使用的[时区名称](/zh/reference/settings/server-settings/settings#timezone)。[`String`](/zh/reference/data-types/string)

**返回值**

返回一个精确到毫秒的 timestamp。如果该 UUID 不是有效的第 7 版 UUID，则返回 `1970-01-01 00:00:00.000`。[`DateTime64(3)`](/zh/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>
  此函数已弃用，且仅在启用 setting [`allow_deprecated_snowflake_conversion_functions`](/zh/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) 时才能使用。
  该函数将在未来的某个版本中移除。

  请改用函数 [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID)。
</Warning>

将 [DateTime64](/zh/reference/data-types/datetime64) 转换为给定时间点对应的第一个 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)。

**语法**

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

**参数**

* `value` — 日期时间。[`DateTime64`](/zh/reference/data-types/datetime64)

**返回值**

返回将输入值转换为该时间点的第一个 Snowflake ID 后的结果。[`Int64`](/zh/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](/zh/reference/data-types/datetime64) 值转换为给定时间点对应的第一个 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)。

**语法**

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

**参数**

* `value` — 日期时间。[`DateTime64`](/zh/reference/data-types/datetime64)
* `epoch` — Snowflake ID 的纪元，表示自 1970-01-01 起经过的毫秒数。默认为 0 (1970-01-01) 。若使用 Twitter/X 的纪元 (2015-01-01) ，请提供 1288834974657。[`UInt*`](/zh/reference/data-types/int-uint)

**返回值**

转换为 [`UInt64`](/zh/reference/data-types/int-uint) 的输入值

**示例**

**简单**

```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>

Introduced in：v21.10.0

<Warning>
  此函数已弃用，仅在启用设置 [`allow_deprecated_snowflake_conversion_functions`](/zh/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) 时才能使用。
  该函数将在未来的某个版本中移除。

  请改用函数 [dateTimeToSnowflakeID](#dateTimeToSnowflakeID)。
</Warning>

将 [DateTime](/zh/reference/data-types/datetime) 值转换为给定时间点对应的第一个 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)。

**Syntax**

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

**参数**

* `value` — 日期时间。[`DateTime`](/zh/reference/data-types/datetime)

**返回值**

返回该时间对应的第一个 Snowflake ID。[`Int64`](/zh/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](/zh/reference/data-types/datetime) 值转换为该时间点的第一个 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)。

**语法**

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

**参数**

* `value` — 日期时间。[`DateTime`](/zh/reference/data-types/datetime)
* `epoch` — Snowflake ID 的纪元，以自 1970-01-01 起经过的毫秒数表示。默认为 0 (1970-01-01) 。如果使用 Twitter/X 的纪元 (2015-01-01) ，请提供 1288834974657。[`UInt*`](/zh/reference/data-types/int-uint)

**返回值**

转换为 [`UInt64`](/zh/reference/data-types/int-uint) 的输入值

**示例**

**简单**

```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](/zh/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`](/zh/reference/data-types/datetime)

**返回值**

返回 UUIDv7。[`UUID`](/zh/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 生成”](#snowflake-id-generation)一节。

**语法**

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

**参数**

* `expr` — 任意的[表达式](/zh/reference/syntax#expressions)。如果在同一个查询中多次调用该函数，可用它来绕过[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。表达式的值不会影响返回的 Snowflake ID。可选。 - `machine_id` — 机器 ID，使用其最低 10 位。[Int64](/zh/reference/data-types/int-uint)。可选。

**返回值**

返回 Snowflake ID。[`UInt64`](/zh/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](/zh/reference/data-types/uuid)。

**语法**

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

**参数**

* `expr` — 可选。任意表达式；如果在同一查询中多次调用该函数，可用于绕过[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。该表达式的值不会影响返回的 UUID。

**返回值**

返回 UUIDv4。[`UUID`](/zh/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

生成一个[第 7 版](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04)的 [UUID](/zh/reference/data-types/uuid)。

有关 UUID 结构、计数器管理和并发保证的详细信息，请参见[“UUIDv7 生成”](#uuidv7-generation)一节。

<Note>
  截至 2025 年 9 月，第 7 版 UUID 仍处于草案阶段，其布局今后可能会发生变化。
</Note>

**语法**

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

**参数**

* `expr` — 可选。任意表达式。若在同一查询中多次调用该函数，可用其绕过[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。该表达式的值不会影响返回的 UUID。[`Any`](/zh/reference/data-types/index)

**返回值**

返回 UUIDv7。[`UUID`](/zh/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](/zh/reference/data-types/datetime) 类型的值返回。

**语法**

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

**参数**

* `value` — Snowflake ID。[`UInt64`](/zh/reference/data-types/int-uint)
* `epoch` — 可选。Snowflake ID 的纪元，以自 1970-01-01 起经过的毫秒数表示。默认值为 0 (1970-01-01) 。如果使用 Twitter/X 纪元 (2015-01-01) ，请提供 1288834974657。[`UInt*`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。[时区](/zh/reference/settings/server-settings/settings#timezone)。该函数会根据该时区解析 `time_string`。[`String`](/zh/reference/data-types/string)

**返回值**

返回 `value` 的时间戳部分。[`DateTime`](/zh/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](/zh/reference/data-types/datetime64) 类型的值。

**语法**

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

**参数**

* `value` — Snowflake ID。[`UInt64`](/zh/reference/data-types/int-uint)
* `epoch` — 可选。Snowflake ID 的纪元，以自 1970-01-01 起经过的毫秒数表示。默认为 0 (1970-01-01) 。对于 Twitter/X 纪元 (2015-01-01) ，请提供 1288834974657。[`UInt*`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。[时区](/zh/reference/settings/server-settings/settings#timezone)。该函数会根据该时区解析 `time_string`。[`String`](/zh/reference/data-types/string)

**返回值**

将 `value` 的时间戳部分作为 `DateTime64` 返回，`标度 = 3`，即毫秒精度。[`DateTime64`](/zh/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`](/zh/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) 时才能使用。
  该函数将在未来的某个版本中被移除。

  请改用函数 [`snowflakeIDToDateTime`](#snowflakeIDToDateTime)。
</Warning>

提取 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) 中的时间戳部分，并以 [DateTime](/zh/reference/data-types/datetime) 格式返回。

**语法**

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

**参数**

* `value` — Snowflake ID。[`Int64`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。[时区](/zh/reference/settings/server-settings/settings#timezone)。该函数会根据时区解析 `time_string`。[`String`](/zh/reference/data-types/string)

**返回值**

返回 `value` 的时间戳部分。[`DateTime`](/zh/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`](/zh/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) 时才能使用。
  该函数将在未来的某个版本中被移除。

  请改用函数 [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64)。
</Warning>

提取 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) 中的时间戳部分，并以 [DateTime64](/zh/reference/data-types/datetime64) 格式返回。

**语法**

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

**参数**

* `value` — Snowflake ID。[`Int64`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。[时区](/zh/reference/settings/server-settings/settings#timezone)。函数会根据该时区解析 `time_string`。[`String`](/zh/reference/data-types/string)

**返回值**

返回 `value` 的时间戳部分。[`DateTime64(3)`](/zh/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>

Introduced in: v21.1.0

将 String 值转换为 UUID 类型。如果转换失败，则返回默认 UUID 值，而不是抛出错误。

此函数会尝试解析长度为 36 个字符、采用标准 UUID 格式 (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) 的字符串。
如果该字符串无法转换为有效的 UUID，函数将返回提供的默认 UUID 值。

**语法**

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

**参数**

* `string` — 要转换为 UUID 的 36 个字符的 String 或 FixedString(36)。 - `default` — 如果第一个参数无法转换为 UUID 类型，则返回此 UUID 值。

**返回值**

如果成功，则返回转换后的 UUID；如果转换失败，则返回默认 UUID。 [`UUID`](/zh/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>

Introduced in: v20.12.0

将输入值转换为 `UUID` 类型的值；如果出错，则返回 `NULL`。

与 [`toUUID`](/zh/reference/functions/regular-functions/type-conversion-functions#toUUID) 类似，但在转换出错时返回 `NULL`，而不是抛出异常。

支持的参数：

* 标准格式 UUID 的字符串表示形式 (8-4-4-4-12 个十六进制数字) 。
* 不含连字符的 UUID 字符串表示形式 (32 个十六进制数字) 。

不支持的参数 (返回 `NULL`) ：

* 无效的字符串格式。
* 非字符串类型。
* 格式不正确的 UUID。

**Syntax**

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

**参数**

* `x` — UUID 的字符串表示形式。[`String`](/zh/reference/data-types/string)

**返回值**

如果转换成功，则返回 UUID 值；否则返回 `NULL`。[`UUID`](/zh/reference/data-types/uuid) 或 [`NULL`](/zh/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 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
```