跳转到主要内容

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。
生成的 Snowflake ID 基于 UNIX 纪元 1970-01-01。虽然 Snowflake ID 的纪元并没有统一的标准或建议,但其他系统中的实现可能会使用不同的纪元,例如 Twitter/X (2010-11-04) 或 Mastodon (2015-01-01) 。
 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)
  • variantRFC4122 中规定的 Variant。1 = Big-endian (默认) ,2 = Microsoft(U)Int*
返回值 返回 UUID 的字符串形式。String 示例 用法示例
Query
SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid
Response
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
Microsoft 变体
Query
SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
Response
┌─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 个字符的字符串或定长字符串。StringFixedString(36)
  • variantRFC4122 中定义的 Variant。1 = Big-endian (默认) ,2 = Microsoft(U)Int*
返回值 返回 string 的二进制表示。FixedString(16) 示例 用法示例
Query
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes
Response
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
Microsoft 变体
Query
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes
Response
┌─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 的二进制表示。FixedString(16) 示例 使用示例
Query
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes
Response
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
Microsoft 变体
Query
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid, 2) AS bytes
Response
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

UUIDv7ToDateTime

引入版本:v24.5.0 返回 UUID 第 7 版的时间戳部分。 语法
UUIDv7ToDateTime(uuid[, timezone])
参数 返回值 返回一个精确到毫秒的 timestamp。如果该 UUID 不是有效的第 7 版 UUID,则返回 1970-01-01 00:00:00.000DateTime64(3) 示例 使用示例
Query
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
Response
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
指定时区
Query
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
Response
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                             2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘

dateTime64ToSnowflake

引入版本:v21.10.0
此函数已弃用,且仅在启用 setting allow_deprecated_snowflake_conversion_functions 时才能使用。 该函数将在未来的某个版本中移除。请改用函数 dateTime64ToSnowflakeID
DateTime64 转换为给定时间点对应的第一个 Snowflake ID 语法
dateTime64ToSnowflake(value)
参数 返回值 返回将输入值转换为该时间点的第一个 Snowflake ID 后的结果。Int64 示例 用法示例
Query
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
Response
┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘

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 的输入值 示例 简单
Query
SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
Response
6832626394434895872

dateTimeToSnowflake

Introduced in:v21.10.0
此函数已弃用,仅在启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。 该函数将在未来的某个版本中移除。请改用函数 dateTimeToSnowflakeID
DateTime 值转换为给定时间点对应的第一个 Snowflake ID Syntax
dateTimeToSnowflake(value)
参数 返回值 返回该时间对应的第一个 Snowflake ID。Int64 示例 使用示例
Query
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
Response
┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘

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 的输入值 示例 简单
Query
SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))
Response
6832626392367104000

dateTimeToUUIDv7

引入版本:v25.8.0 DateTime 值转换为给定时间对应的 UUIDv7 有关 UUID 结构、计数器管理以及并发保障的详细信息,请参见“UUIDv7 生成”一节。
截至 2025 年 9 月,第 7 版 UUID 仍处于草案阶段,其布局未来可能会发生变化。
语法
dateTimeToUUIDv7(value)
参数 返回值 返回 UUIDv7。UUID 示例 使用示例
Query
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));
Response
┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘
同一时间戳的多个 UUID
Query
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
Response
┌─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 示例 用法示例
Query
CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;
Response
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
每行会生成多个 Snowflake ID
Query
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
Response
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘
基于表达式和机器 ID
Query
SELECT generateSnowflakeID('expr', 1);
Response
┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘

generateUUIDv4

引入版本:v1.1.0 生成一个 第 4 版 UUID 语法
generateUUIDv4([expr])
参数
  • expr — 可选。任意表达式;如果在同一查询中多次调用该函数,可用于绕过公共子表达式消除。该表达式的值不会影响返回的 UUID。
返回值 返回 UUIDv4。UUID 示例 使用示例
Query
SELECT generateUUIDv4(number) FROM numbers(3);
Response
┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘
公共子表达式消除
Query
SELECT generateUUIDv4(1), generateUUIDv4(1);
Response
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7

引入版本:v24.5.0 生成一个版本 7UUID 有关 UUID 结构、计数器管理和并发保证的详细信息,请参见“UUIDv7 生成”一节。
截至 2025 年 9 月,版本 7 UUID 仍处于草案阶段,其布局今后可能会发生变化。
语法
generateUUIDv7([expr])
参数
  • expr — 可选。任意表达式。若在同一查询中多次调用该函数,可用其绕过公共子表达式消除。该表达式的值不会影响返回的 UUID。Any
返回值 返回 UUIDv7。UUID 示例 使用示例
Query
SELECT generateUUIDv7(number) FROM numbers(3);
Response
┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘
公共子表达式消除
Query
SELECT generateUUIDv7(1), generateUUIDv7(1);
Response
┌─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_stringString
返回值 返回 value 的时间戳部分。DateTime 示例 使用示例
Query
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
Response
┌─────────────────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_stringString
返回值 value 的时间戳部分作为 DateTime64 返回,标度 = 3,即毫秒精度。DateTime64 示例 用法示例
Query
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
Response
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeToDateTime

引入版本:v21.10.0
此函数已弃用,仅在启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。 该函数将在未来的某个版本中被移除。请改用函数 snowflakeIDToDateTime
提取 Snowflake ID 中的时间戳部分,并以 DateTime 格式返回。 语法
snowflakeToDateTime(value[, time_zone])
参数
  • value — Snowflake ID。Int64
  • time_zone — 可选。时区。该函数会根据时区解析 time_stringString
返回值 返回 value 的时间戳部分。DateTime 示例 使用示例
Query
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
Response
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘

snowflakeToDateTime64

引入版本:v21.10.0
此函数已弃用,且仅在启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。 该函数将在未来的某个版本中被移除。请改用函数 snowflakeIDToDateTime64
提取 Snowflake ID 中的时间戳部分,并以 DateTime64 格式返回。 语法
snowflakeToDateTime64(value[, time_zone])
参数
  • value — Snowflake ID。Int64
  • time_zone — 可选。时区。函数会根据该时区解析 time_stringString
返回值 返回 value 的时间戳部分。DateTime64(3) 示例 用法示例
Query
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
Response
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘

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
Query
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
Response
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
转换失败则返回默认 UUID
Query
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
Response
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

toUUIDOrNull

Introduced in: v20.12.0 将输入值转换为 UUID 类型的值;如果出错,则返回 NULL toUUID 类似,但在转换出错时返回 NULL,而不是抛出异常。 支持的参数:
  • 标准格式 UUID 的字符串表示形式 (8-4-4-4-12 个十六进制数字) 。
  • 不含连字符的 UUID 字符串表示形式 (32 个十六进制数字) 。
不支持的参数 (返回 NULL) :
  • 无效的字符串格式。
  • 非字符串类型。
  • 格式不正确的 UUID。
Syntax
toUUIDOrNull(x)
参数
  • x — UUID 的字符串表示形式。String
返回值 如果转换成功,则返回 UUID 值;否则返回 NULLUUIDNULL 示例 用法示例
Query
SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid
Response
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
最后修改于 2026年6月10日