用于处理 UUID 的函数
generateUUIDv4
语法
generateUUIDv4([expr])
参数
返回值
UUIDv4 类型的值。
示例
首先,创建一个包含 UUID 类型列的表,然后将生成的 UUIDv4 插入到表中。
CREATE TABLE tab (uuid UUID) ENGINE = Memory;
INSERT INTO tab SELECT generateUUIDv4();
SELECT * FROM tab;
结果
┌─────────────────────────────────uuid─┐
│ f4bf890f-f9dc-4332-ad5c-0c18e73f28e9 │
└──────────────────────────────────────┘
每行生成多个 UUID 的示例
SELECT generateUUIDv4(1), generateUUIDv4(2);
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 8abf8c13-7dea-4fdf-af3e-0e18767770e6 │
└──────────────────────────────────────┴──────────────────────────────────────┘
generateUUIDv7
生成的 UUID 包含当前 Unix 时间戳(以毫秒为单位,48 位),后跟版本“7”(4 位),一个计数器(42 位)用于区分同一毫秒内的 UUID(包括一个变体字段“2”,2 位)和一个随机字段(32 位)。对于任何给定的时间戳 (unix_ts_ms),计数器从一个随机值开始,并且对于每个新的 UUID 增加 1,直到时间戳发生变化。如果计数器溢出,则时间戳字段增加 1,并且计数器重置为一个新的随机起始值。
函数 generateUUIDv7
保证在并发运行的线程和查询中,同一时间戳内的计数器字段单调递增。
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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
截至 2024 年 4 月,版本 7 UUID 处于草案状态,其布局在未来可能会发生变化。
语法
generateUUIDv7([expr])
参数
返回值
UUIDv7 类型的值。
示例
首先,创建一个包含 UUID 类型列的表,然后将生成的 UUIDv7 插入到表中。
CREATE TABLE tab (uuid UUID) ENGINE = Memory;
INSERT INTO tab SELECT generateUUIDv7();
SELECT * FROM tab;
结果
┌─────────────────────────────────uuid─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b │
└──────────────────────────────────────┘
每行生成多个 UUID 的示例
SELECT generateUUIDv7(1), generateUUIDv7(2);
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(2)────────────────────┐
│ 018f05c9-4ab8-7b86-b64e-c9f03fbd45d1 │ 018f05c9-4ab8-7b86-b64e-c9f12efb7e16 │
└──────────────────────────────────────┴──────────────────────────────────────┘
empty
检查输入的 UUID 是否为空。
语法
empty(UUID)
如果 UUID 包含全零(零 UUID),则认为它是空的。
参数
x
— UUID。 UUID。
返回值
- 对于空 UUID 返回
1
,对于非空 UUID 返回0
。 UInt8。
示例
要生成 UUID 值,ClickHouse 提供了 generateUUIDv4 函数。
查询
SELECT empty(generateUUIDv4());
结果
┌─empty(generateUUIDv4())─┐
│ 0 │
└─────────────────────────┘
notEmpty
检查输入的 UUID 是否非空。
语法
notEmpty(UUID)
如果 UUID 包含全零(零 UUID),则认为它是空的。
参数
x
— UUID。 UUID。
返回值
- 对于非空 UUID 返回
1
,对于空 UUID 返回0
。 UInt8。
示例
要生成 UUID 值,ClickHouse 提供了 generateUUIDv4 函数。
查询
SELECT notEmpty(generateUUIDv4());
结果
┌─notEmpty(generateUUIDv4())─┐
│ 1 │
└────────────────────────────┘
toUUID
将 String 类型的值转换为 UUID。
toUUID(string)
返回值
UUID 类型的值。
用法示例
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
结果
┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
toUUIDOrDefault
参数
返回值
UUID
toUUIDOrDefault(string, default)
返回值
UUID 类型的值。
用法示例
第一个示例返回第一个参数转换为 UUID 类型,因为它可以被转换。
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', cast('59f0c404-5cb3-11e7-907b-a6006ad3dba0' as UUID));
结果
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', CAST('59f0c404-5cb3-11e7-907b-a6006ad3dba0', 'UUID'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
第二个示例返回第二个参数(提供的默认 UUID),因为第一个参数无法转换为 UUID 类型。
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', cast('59f0c404-5cb3-11e7-907b-a6006ad3dba0' as UUID));
结果
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', CAST('59f0c404-5cb3-11e7-907b-a6006ad3dba0', 'UUID'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
toUUIDOrNull
接收 String 类型的参数并尝试将其解析为 UUID。如果失败,则返回 NULL。
toUUIDOrNull(string)
返回值
Nullable(UUID) 类型的返回值。
用法示例
SELECT toUUIDOrNull('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
结果
┌─uuid─┐
│ ᴺᵁᴸᴸ │
└──────┘
toUUIDOrZero
接收 String 类型的参数并尝试将其解析为 UUID。如果失败,则返回零 UUID。
toUUIDOrZero(string)
返回值
UUID 类型的值。
用法示例
SELECT toUUIDOrZero('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
结果
┌─────────────────────────────────uuid─┐
│ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┘
UUIDStringToNum
接收包含 36 个字符的字符串,格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
,并返回其二进制表示形式的 FixedString(16),其格式可由 variant
指定(默认为 Big-endian
)。
语法
UUIDStringToNum(string[, variant = 1])
参数
string
— 字符串 或 FixedString。variant
— 整数,表示由 RFC4122 指定的变体。1 =Big-endian
(默认),2 =Microsoft
。
返回值
FixedString(16)
用法示例
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid) AS bytes
结果
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid, 2) AS bytes
结果
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
UUIDNumToString
接收包含 UUID 二进制表示形式的 binary
,其格式可由 variant
指定(默认为 Big-endian
),并返回一个包含 36 个字符的文本格式字符串。
语法
UUIDNumToString(binary[, variant = 1])
参数
binary
— FixedString(16),作为 UUID 的二进制表示形式。variant
— 整数,表示由 RFC4122 指定的变体。1 =Big-endian
(默认),2 =Microsoft
。
返回值
字符串。
用法示例
SELECT
'a/<@];!~p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16)) AS uuid
结果
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
SELECT
'@</a;]~!p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
结果
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
UUIDToNum
接收一个 UUID 并返回其二进制表示形式的 FixedString(16),其格式可由 variant
指定(默认为 Big-endian
)。此函数替换对两个单独函数 UUIDStringToNum(toString(uuid))
的调用,因此无需从 UUID 到字符串的中间转换即可从 UUID 中提取字节。
语法
UUIDToNum(uuid[, variant = 1])
参数
返回值
UUID 的二进制表示形式。
用法示例
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid) AS bytes
结果
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
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
返回版本 7 UUID 的时间戳组件。
语法
UUIDv7ToDateTime(uuid[, timezone])
参数
返回值
- 具有毫秒精度的 Timestamp。如果 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 15: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 │
└──────────────────────────────────────────────────────────────────────────────────────┘
serverUUID
返回 ClickHouse 服务器首次启动时生成的随机 UUID。UUID 存储在 ClickHouse 服务器目录(例如 /var/lib/clickhouse/
)中的 uuid
文件中,并在服务器重启之间保留。
语法
serverUUID()
返回值
- 服务器的 UUID。 UUID。
generateSnowflakeID
生成一个 Snowflake ID。
生成的 Snowflake ID 包含当前 Unix 时间戳(以毫秒为单位,41 + 1 个最高位为零),后跟机器 ID(10 位)和一个计数器(12 位)用于区分同一毫秒内的 ID。对于任何给定的时间戳 (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)。
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 |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
语法
generateSnowflakeID([expr, [machine_id]])
参数
expr
— 用于绕过 公共子表达式消除 的任意 表达式,如果函数在查询中被多次调用。表达式的值对返回的 Snowflake ID 没有影响。可选。machine_id
— 机器 ID,使用最低 10 位。 Int64。可选。
返回值
UInt64 类型的返回值。
示例
首先,创建一个包含 UInt64 类型列的表,然后将生成的 Snowflake ID 插入到表中。
CREATE TABLE tab (id UInt64) ENGINE = Memory;
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 │
└────────────────────────────────┘
snowflakeToDateTime
此函数已弃用,仅当启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。此函数将在将来的某个时间点被移除。
以 DateTime 格式提取 Snowflake ID 的时间戳组件。
语法
snowflakeToDateTime(value[, time_zone])
参数
返回值
value
的时间戳组件,作为 DateTime 值。
示例
查询
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
结果
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
snowflakeToDateTime64
此函数已弃用,仅当启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。此函数将在将来的某个时间点被移除。
以 DateTime64 格式提取 Snowflake ID 的时间戳组件。
语法
snowflakeToDateTime64(value[, time_zone])
参数
返回值
value
的时间戳组件,作为 DateTime64,其刻度为 3,即毫秒精度。
示例
查询
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
结果
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│ 2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
dateTimeToSnowflake
此函数已弃用,仅当启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。此函数将在将来的某个时间点被移除。
将 DateTime 值转换为给定时间点的第一个 Snowflake ID。
语法
dateTimeToSnowflake(value)
参数
value
— 带时间的日期。 DateTime。
返回值
- 输入值转换为 Int64 数据类型,作为该时间点的第一个 Snowflake ID。
示例
查询
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
结果
┌─dateTimeToSnowflake(dt)─┐
│ 1426860702823350272 │
└─────────────────────────┘
dateTime64ToSnowflake
此函数已弃用,仅当启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。此函数将在将来的某个时间点被移除。
将 DateTime64 转换为给定时间点的第一个 Snowflake ID。
语法
dateTime64ToSnowflake(value)
参数
value
— 带时间的日期。 DateTime64。
返回值
- 输入值转换为 Int64 数据类型,作为该时间点的第一个 Snowflake ID。
示例
查询
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
结果
┌─dateTime64ToSnowflake(dt64)─┐
│ 1426860704886947840 │
└─────────────────────────────┘
snowflakeIDToDateTime
将 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
将 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,即毫秒精度。
示例
查询
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
结果
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
dateTimeToSnowflakeID
将 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,作为该时间点的第一个 Snowflake ID。
示例
查询
SELECT toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt, dateTimeToSnowflakeID(dt) AS res;
结果
┌──────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56 │ 6832626392367104000 │
└─────────────────────┴─────────────────────┘
dateTime64ToSnowflakeID
将 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,作为该时间点的第一个 Snowflake ID。
示例
查询
SELECT toDateTime('2021-08-15 18:57:56.493', 3, 'Asia/Shanghai') AS dt, dateTime64ToSnowflakeID(dt) AS res;
结果
┌──────────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56.493 │ 6832626394434895872 │
└─────────────────────────┴─────────────────────┘