跳至主要内容

用于处理 UUID 的函数

generateUUIDv4

生成一个 版本 4UUID

语法

generateUUIDv4([expr])

参数

  • expr — 用于绕过 公共子表达式消除 的任意 表达式,如果函数在查询中被多次调用。表达式的值对返回的 UUID 没有影响。可选。

返回值

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

生成一个 版本 7UUID

生成的 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])

参数

  • expr — 用于绕过 公共子表达式消除 的任意 表达式,如果函数在查询中被多次调用。表达式的值对返回的 UUID 没有影响。可选。

返回值

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 返回 0UInt8

示例

要生成 UUID 值,ClickHouse 提供了 generateUUIDv4 函数。

查询

SELECT empty(generateUUIDv4());

结果

┌─empty(generateUUIDv4())─┐
│ 0 │
└─────────────────────────┘

notEmpty

检查输入的 UUID 是否非空。

语法

notEmpty(UUID)

如果 UUID 包含全零(零 UUID),则认为它是空的。

此函数也适用于 数组字符串

参数

  • x — UUID。 UUID

返回值

  • 对于非空 UUID 返回 1,对于空 UUID 返回 0UInt8

示例

要生成 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

参数

  • string — 36 个字符的字符串或 FixedString(36)。 字符串
  • default — 如果第一个参数无法转换为 UUID 类型,则用作默认值的 UUID。 UUID

返回值

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])

参数

  • binaryFixedString(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])

参数

  • uuidUUID
  • variant — 整数,表示由 RFC4122 指定的变体。1 = Big-endian(默认),2 = Microsoft

返回值

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

带有表达式和机器 ID 的示例

SELECT generateSnowflakeID('expr', 1);

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

snowflakeToDateTime

危险

此函数已弃用,仅当启用设置 allow_deprecated_snowflake_conversion_functions 时才能使用。此函数将在将来的某个时间点被移除。

DateTime 格式提取 Snowflake ID 的时间戳组件。

语法

snowflakeToDateTime(value[, time_zone])

参数

  • value — Snowflake ID。 Int64
  • time_zone时区。函数根据时区解析time_string。可选。 String

返回值

  • 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 — Snowflake ID。 Int64
  • time_zone时区。函数根据时区解析time_string。可选。 String

返回值

  • 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)

参数

返回值

  • 输入值转换为 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 │
└─────────────────────────┴─────────────────────┘

另请参阅