UUIDs 相关函数 | ClickHouse Docs

UUIDv7 生成

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

 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Snowflake ID 生成

生成的 Snowflake ID 包含当前以毫秒为单位的 Unix 时间戳 (41 位，加上最高位的 1 个零位) ，后面依次是机器 ID (10 位) 和计数器 (12 位) ，用于区分同一毫秒内生成的不同 ID。对于任意给定的时间戳 (unix_ts_ms) ，计数器从 0 开始，每生成一个新的 Snowflake ID 就加 1，直到时间戳发生变化。若计数器溢出，则时间戳字段加 1，并将计数器重置为 0。

 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    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

UUIDNumToString

在以下版本中引入：v1.1.0

接受 UUID 的二进制表示，其格式可通过 variant 选择指定 (默认为 Big-endian) ，并返回一个包含 36 个字符的文本格式字符串。

语法

UUIDNumToString(binary[, variant])

参数

binary — UUID 的二进制表示。FixedString(16)
variant — RFC4122 中规定的 Variant。1 = Big-endian (默认) ，2 = Microsoft。(U)Int*

返回值

返回 UUID 的字符串形式。String

示例

用法示例

SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid

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

Microsoft 变体

SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid

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

UUIDStringToNum

引入版本：v1.1.0

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

语法

UUIDStringToNum(string[, variant = 1])

参数

string — 36 个字符的字符串或定长字符串。String 或 FixedString(36)
variant — RFC4122 中定义的 Variant。1 = Big-endian (默认) ，2 = Microsoft。(U)Int*

返回值

返回 string 的二进制表示。FixedString(16)

示例

用法示例

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes

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

Microsoft 变体

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes

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

UUIDToNum

引入版本：v24.5.0

接受一个 UUID，并以 FixedString(16) 形式返回其二进制表示；其格式可通过 variant 指定 (默认为 Big-endian) 。此函数可替代对两个独立函数 UUIDStringToNum(toString(uuid)) 的调用，因此无需先将 UUID 转换为字符串再提取其中的字节。

语法

UUIDToNum(uuid[, variant = 1])

参数

uuid — UUID。String 或 FixedString
variant — RFC4122 中定义的 Variant。1 = Big-endian (默认) ，2 = Microsoft。(U)Int*

返回值

返回 UUID 的二进制表示。FixedString(16)

示例

使用示例

SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes

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

Microsoft 变体

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

引入版本：v24.5.0

返回 UUID 第 7 版的时间戳部分。

语法

UUIDv7ToDateTime(uuid[, timezone])

参数

uuid — UUID 第 7 版。String
timezone — 可选。返回值使用的时区名称。String

返回值

返回一个精确到毫秒的时间戳。如果该 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 12: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 │
└──────────────────────────────────────────────────────────────────────────────────────┘

dateTime64ToSnowflakeID

引入版本：v24.6.0

将 DateTime64 值转换为给定时间点对应的第一个 Snowflake ID。

语法

dateTime64ToSnowflakeID(value[, epoch])

参数

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

返回值

转换为 UInt64 的输入值

示例

简单

SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))

6832626392367104000

dateTimeToSnowflakeID

引入版本：v24.6.0

将 DateTime 值转换为该时间点的第一个 Snowflake ID。

语法

dateTimeToSnowflakeID(value[, epoch])

参数

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

返回值

转换为 UInt64 的输入值

示例

简单

SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))

6832626392367104000

dateTimeToUUIDv7

引入版本：v25.8.0

将 DateTime 值转换为给定时间对应的 UUIDv7，如 RFC 9562 所定义。

有关 UUID 结构、计数器管理以及并发保证的详细信息，请参见"UUIDv7 生成"一节。

语法

dateTimeToUUIDv7(value)

参数

value — 日期时间。DateTime

返回值

返回 UUIDv7。UUID

示例

使用示例

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));

┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                 │
└──────────────────────────────────────────────────────────────────────┘

同一时间戳的多个 UUID

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));

┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘

generateSnowflakeID

引入版本：v24.6.0

生成 Snowflake ID。

函数 generateSnowflakeID 可保证时间戳中的计数字段在所有并发运行的线程和查询中的各次函数调用之间保持单调递增。

实现细节请参见“Snowflake ID 生成”一节。

语法

generateSnowflakeID([expr, [machine_id]])

参数

expr — 任意的表达式。如果在同一个查询中多次调用该函数，可用它来绕过公共子表达式消除。表达式的值不会影响返回的 Snowflake ID。可选。 - machine_id — 机器 ID，使用其最低 10 位。Int64。可选。

返回值

返回 Snowflake ID。UInt64

示例

用法示例

CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;

┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘

每行会生成多个 Snowflake ID

SELECT generateSnowflakeID(1), generateSnowflakeID(2);

┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘

基于表达式和机器 ID

SELECT generateSnowflakeID('expr', 1);

┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘

generateUUIDv4

引入版本：v1.1.0

生成一个第 4 版 UUID。

语法

generateUUIDv4([expr])

参数

expr — 可选。任意表达式；如果在同一查询中多次调用该函数，可用于绕过公共子表达式消除。该表达式的值不会影响返回的 UUID。

返回值

返回 UUIDv4。UUID

示例

使用示例

SELECT generateUUIDv4(number) FROM numbers(3);

┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘

公共子表达式消除

SELECT generateUUIDv4(1), generateUUIDv4(1);

┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7

引入版本：v24.5.0

生成由 RFC 9562 定义的第 7 版 UUID。

有关 UUID 结构、计数器管理和并发保证的详细信息，请参见"UUIDv7 生成"一节。

语法

generateUUIDv7([expr])

参数

expr — 可选。任意表达式。若在同一查询中多次调用该函数，可用其绕过公共子表达式消除。该表达式的值不会影响返回的 UUID。Any

返回值

返回 UUIDv7。UUID

示例

使用示例

SELECT generateUUIDv7(number) FROM numbers(3);

┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘

公共子表达式消除

SELECT generateUUIDv7(1), generateUUIDv7(1);

┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

snowflakeIDToDateTime

引入版本：v24.6.0

将 Snowflake ID 的时间戳组件作为 DateTime 类型的值返回。

语法

snowflakeIDToDateTime(value[, epoch[, time_zone]])

参数

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

示例

使用示例

SELECT snowflakeIDToDateTime(7204436857747984384) AS res

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeIDToDateTime64

引入版本：v24.6.0

返回 Snowflake ID 中的时间戳部分，结果为 DateTime64 类型的值。

语法

snowflakeIDToDateTime64(value[, epoch[, time_zone]])

参数

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 的时间戳部分作为 DateTime64 返回，标度 = 3，即毫秒精度。DateTime64

示例

用法示例

SELECT snowflakeIDToDateTime64(7204436857747984384) AS res

┌─────────────────────res─┐
│ 2024-06-06 10:59:58.851 │
└─────────────────────────┘

toUUIDOrDefault

Introduced in: v21.1.0

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

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

语法

toUUIDOrDefault(string, default)

参数

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

返回值

如果成功，则返回转换后的 UUID；如果转换失败，则返回默认 UUID。 UUID

示例

转换成功时返回解析后的 UUID

SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                    │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

转换失败则返回默认 UUID

SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                         │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

toUUIDOrNull

引入版本: v20.12.0

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

与 toUUID 类似，但在转换出错时返回 NULL，而不是抛出异常。

支持的参数：

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

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

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

语法

toUUIDOrNull(x)

参数

x — UUID 的字符串表示形式。String

返回值

如果转换成功，则返回 UUID 值；否则返回 NULL。UUID 或 NULL

示例

用法示例

SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid

┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │ ᴺᵁᴸᴸ         │
└──────────────────────────────────────┴──────────────┘