UUID()¶
函数说明¶
UUID() 和 UUID_V7() 生成 RFC 9562 定义的 native UUIDv7。原生值占 16 字节;客户端显示为 32 个十六进制数字和 4 个连字符:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee(共 36 字符)。需要版本 1 时使用 UUID_V1()。
UUIDv7 的开头是毫秒精度的 Unix 时间戳,后面为版本、variant 和随机位。该布局支持毫秒粒度的时间排序,但不保证不同设备之间或同一毫秒内的生成顺序。UUID 是标识符,不能作为秘密或访问令牌。
列存储与比较参见 UUID 类型。
常用函数语法¶
UUID()
UUID_V7()
UUID_V1()
UUID(datetime)
UUID_V7(datetime)
UUID(datetime) 和 UUID_V7(datetime) 返回指定时间的确定性下边界:设置时间戳位,保留版本和 variant 位,其余位清零。使用会话时区和毫秒精度。同一时刻的重复调用返回相同边界,不应使用此重载生成唯一行标识符。NULL datetime 返回 NULL;超出 UUIDv7 可表示范围的时间戳会报错。
MySQL 兼容性¶
MatrixOne 保留 UUID() 的 native UUIDv7 返回类型;MySQL 返回版本 1 的字符字符串。因此:
CREATE TABLE ... AS SELECT UUID()在 MatrixOne 中生成 UUID 列。native UUID 比较会将文本操作数解析为 UUID。
'fallback'等任意文本无效并报错。需要普通文本比较时使用CAST(UUID() AS CHAR)。UUID 与 CHAR/VARCHAR/TEXT 混合的值表达式(
CASE、IF、COALESCE、UNION、LEAST、GREATEST)使用能容纳完整 UUID 的字符结果。只有 UUID/NULL 的表达式保留原生类型。这不代表完整的 MySQL collation 兼容。
示例¶
-- 7
SELECT UUID_EXTRACT_VERSION(UUID());
-- 1
SELECT UUID_EXTRACT_VERSION(UUID_V1());
-- 36
SELECT LENGTH(CAST(UUID() AS CHAR));
-- 0
SELECT CAST(UUID() AS CHAR) IN ('fallback');
SELECT UUID(CAST('2026-01-01 00:00:00' AS DATETIME)) =
-- 1
UUID(CAST('2026-01-01 00:00:00' AS DATETIME));
-- 完整 UUID,不会截断
SELECT 'fallback' AS value UNION ALL
SELECT CAST('018f0000-0000-7000-8000-000000000001' AS UUID);
SET time_zone = '+00:00';
-- 019b7ca9-8f2e-7000-8000-000000000000
SELECT CAST(UUID(CAST('2026-01-02 03:04:05.678' AS DATETIME(3))) AS CHAR);
-- 018F0000000070008000000000000001
SELECT HEX(UUID_TO_BIN('018f0000-0000-7000-8000-000000000001', NULL));
-- 70000000018F00008000000000000001
SELECT HEX(UUID_TO_BIN('018f0000-0000-7000-8000-000000000001', 1));
-- 018f0000-0000-7000-8000-000000000001
SELECT BIN_TO_UUID(UUID_TO_BIN('018f0000-0000-7000-8000-000000000001', 1), 1);
每次无参调用生成新值,示例的实际值会变化。已有的 UUID(INTERVAL ...) 重载也生成新 UUID,但会按 interval 平移求值时刻;它与确定性的 datetime 时间边界不同。
UUID_SHORT()¶
UUID_SHORT() 不接受参数,返回 BIGINT UNSIGNED 标识符。它使用 MatrixOne 已有的 HAKeeper 分配器,而不是 MySQL 的 server-ID/启动时间位布局。在保留同一集群分配历史的前提下,跨 CN 和账号的成功调用具有唯一性。它不是 native UUID,不承诺全局顺序、连续值或保密性。
未使用的预留 ID,以及回滚或失败语句消耗的 ID 都不会复用。CN 重启通过持久化的 HAKeeper 预留保持唯一性。独立集群、克隆分配器状态或恢复到更早的分配器快照可能重复值;合并这些历史时需要外部命名空间。
分配器不可用、取消、无效预留或 uint64 范围耗尽时会报错,没有本地计数或随机回退。分配重试受查询的更早截止时间或每次向量求值 30 秒限制。使用此函数及其耗尽保护前,应升级 CN 和全部 HAKeeper 副本。回滚或重新安装时不要重置分配器状态。
SELECT UUID_SHORT(), UUID_SHORT();
IS_UUID()¶
函数说明¶
IS_UUID(str) 判断一个字符串是否为有效的 UUID。若字符串为有效 UUID 则返回 1,否则返回 0。若参数为 NULL 则返回 NULL。
以下几种 UUID 格式均可识别:
标准带连字符格式:
6ccd780c-baba-1026-9564-5b8c656024db无连字符格式(32 位十六进制数字):
6ccd780cbaba102695645b8c656024db带花括号格式:
{6ccd780c-baba-1026-9564-5b8c656024db}大写格式:
6CCD780C-BABA-1026-9564-5B8C656024DB
该函数对长度和十六进制字符组成进行校验。含额外空格、无效字符或长度不正确的字符串将返回 0。
函数语法¶
> IS_UUID(str)
参数释义¶
参数 |
说明 |
|---|---|
str |
必要参数。待测字符串。 |
示例¶
DROP DATABASE IF EXISTS uuid_test;
CREATE DATABASE uuid_test;
USE uuid_test;
-- 标准 UUID 格式
SELECT IS_UUID('6ccd780c-baba-1026-9564-5b8c656024db');
-- 无连字符格式
SELECT IS_UUID('6ccd780cbaba102695645b8c656024db');
-- 带花括号格式
SELECT IS_UUID('{6ccd780c-baba-1026-9564-5b8c656024db}');
-- 大写变体
SELECT IS_UUID('6CCD780C-BABA-1026-9564-5B8C656024DB');
-- URN 格式(不识别为有效 UUID)
SELECT IS_UUID('urn:uuid:6ccd780c-baba-1026-9564-5b8c656024db');
-- 无效:长度不足
SELECT IS_UUID('6ccd780c-baba-1026-9564-5b8c656024d');
-- 无效:含非十六进制字符
SELECT IS_UUID('6ccd780c-baba-1026-9564-5b8c656024dz');
-- 无效:字节数错误
SELECT IS_UUID('6ccd780c-baba-1026-95645b8c656024db');
-- 空字符串
SELECT IS_UUID('');
-- 非 UUID 字符串
SELECT IS_UUID('not-a-uuid');
-- NULL 参数
SELECT IS_UUID(NULL);
DROP DATABASE uuid_test;
UUID_TO_BIN()¶
函数说明¶
UUID_TO_BIN(str [, swap_flag]) 将 UUID 字符串转换为 16 字节的二进制表示。可选参数 swap_flag 控制字节序:
swap_flag= 0(默认):保留 UUID 字符串中的原始字节顺序。swap_flag= 1:将 time-high 字段移到 time-mid 和 time-low 之前。对于版本 1 UUID,把最高有效时间位放在前面可以提升索引局部性。UUIDv7 已将时间戳放在开头,应使用 0;交换不会改善 v7 的时间排序。
swap_flag 可以是数值,也可以是可解析为数值的字符串。0 表示不交换;任何非零值(包括小数和负数)都表示执行交换。字符串标志使用十进制数字前缀('1tail' 启用交换);没有数字前缀的字符串('abc')禁用交换。NULL 标志也禁用交换。str 为 NULL 时返回 NULL;非 NULL 的无效 UUID 仍报错,即使标志为 NULL。
函数语法¶
> UUID_TO_BIN(str [, swap_flag])
参数释义¶
参数 |
说明 |
|---|---|
str |
必要参数。有效的 UUID 字符串,支持带连字符、无连字符、带花括号或大写格式。 |
swap_flag |
可选参数。0 为保留原始字节顺序(默认);任何非零值都会将 time-high 移到 time-mid 和 time-low 之前(适用于 v1)。 |
示例¶
DROP DATABASE IF EXISTS uuid_test;
CREATE DATABASE uuid_test;
USE uuid_test;
-- 默认字节顺序
SELECT HEX(UUID_TO_BIN('6ccd780c-baba-1026-9564-5b8c656024db'));
-- 无连字符 UUID
SELECT HEX(UUID_TO_BIN('6ccd780cbaba102695645b8c656024db'));
-- 带花括号 UUID
SELECT HEX(UUID_TO_BIN('{6ccd780c-baba-1026-9564-5b8c656024db}'));
-- 大写 UUID
SELECT HEX(UUID_TO_BIN('6CCD780C-BABA-1026-9564-5B8C656024DB'));
-- 交换字节顺序(swap_flag = 1)
SELECT HEX(UUID_TO_BIN('6ccd780c-baba-1026-9564-5b8c656024db', 1));
-- NULL UUID 字符串
SELECT HEX(UUID_TO_BIN(NULL));
-- NULL swap_flag(与标志 0 的字节相同)
SELECT HEX(UUID_TO_BIN('6ccd780c-baba-1026-9564-5b8c656024db', NULL));
DROP DATABASE uuid_test;
BIN_TO_UUID()¶
函数说明¶
BIN_TO_UUID(bin [, swap_flag]) 将 16 字节的二进制表示还原为带连字符格式(aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee)的 UUID 字符串。可选参数 swap_flag 必须与相应 UUID_TO_BIN() 调用中使用的一致:
swap_flag= 0(默认):假定二进制值按原始字节顺序生成。swap_flag= 1:反转UUID_TO_BIN(..., 1)执行的时间字段重排,恢复原始 UUID 字符串的顺序。
输入 bin 必须为恰好 16 个字节。更短或更长的二进制值会产生错误。bin 为 NULL 时返回 NULL。swap_flag 为 NULL 表示不交换,不会跳过 16 字节输入校验。字符串标志遵循与 UUID_TO_BIN() 相同的十进制前缀规则。
函数语法¶
> BIN_TO_UUID(bin [, swap_flag])
参数释义¶
参数 |
说明 |
|---|---|
bin |
必要参数。由 |
swap_flag |
可选参数。必须与 |
示例¶
DROP DATABASE IF EXISTS uuid_test;
CREATE DATABASE uuid_test;
USE uuid_test;
-- 默认字节顺序的完整往返
SELECT BIN_TO_UUID(UUID_TO_BIN('6ccd780c-baba-1026-9564-5b8c656024db'));
-- swap_flag = 1 的完整往返
SELECT BIN_TO_UUID(UUID_TO_BIN('6ccd780c-baba-1026-9564-5b8c656024db', 1), 1);
-- swap_flag 前后不一致(结果不正确)
SELECT BIN_TO_UUID(UUID_TO_BIN('6ccd780c-baba-1026-9564-5b8c656024db', 1), 0);
-- NULL 二进制值
SELECT BIN_TO_UUID(NULL);
DROP DATABASE uuid_test;