MySQL STATEMENT_DIGEST 的结果怎样用于归并同形 SQL

我第一次把 SQL 慢查询按“类型”归并时，发现只看原始 SQL 文本很快就会失控：同一条查询只要换一个用户编号，就会多出一行。MySQL 的 STATEMENT_DIGEST() 正好适合生成归并键，而 STATEMENT_DIGEST_TEXT() 负责留下人能读懂的规范化文本。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/encryption-functions.html

这篇只处理“同形 SQL 怎么归到一类”：输入是 SQL 字符串，输出是规范化文本、digest hash 和按 hash 聚合的统计结果。

先看两个函数各自留下什么结果

STATEMENT_DIGEST_TEXT() 会把字面量替换为 ?，适合展示结构；STATEMENT_DIGEST() 会对同一份规范化结果计算 SHA-256 字符串，适合作为分组键。表名、列名等对象标识仍属于结构的一部分，不能把 digest 理解成“只看 SQL 模板”。

-- 先保存一条带字面量的 SQL，便于同时观察文本和哈希结果
SET @stmt = 'SELECT * FROM orders WHERE customer_id = 10 AND quantity > 20';

-- 规范化文本用于阅读和展示，字面量会变成参数标记
SELECT STATEMENT_DIGEST_TEXT(@stmt) AS digest_text;

-- digest hash 用作归并键，返回十六进制字符串
SELECT STATEMENT_DIGEST(@stmt) AS digest_hash;

这两个函数都依赖 MySQL parser。传入 NULL 时结果也是 NULL；SQL 解析失败则会报错。因此，归并流程应该先把输入来源和错误处理定下来，不能把任意日志片段直接当作合法 SQL。

把同形 SQL 变成稳定的归并键

下面两条语句的数值不同，但结构相同。实际接入程序时，通常为每条 SQL 同时保存原文、规范化文本和 digest hash：原文便于追溯，规范化文本便于解释，hash 负责连接聚合记录。

-- 两条 SQL 只改变字面量，目标是得到同一个结构分组
WITH samples AS (
  SELECT 'SELECT * FROM orders WHERE customer_id = 10 AND quantity > 20' AS stmt
  UNION ALL
  SELECT 'SELECT * FROM orders WHERE customer_id = 20 AND quantity > 100'
)
SELECT
  STATEMENT_DIGEST_TEXT(stmt) AS digest_text,
  STATEMENT_DIGEST(stmt) AS digest_hash,
  COUNT(*) AS sample_count
FROM samples
GROUP BY STATEMENT_DIGEST(stmt);

这里的关键不是比较原始字符串，而是让 MySQL 对每个字符串执行同一套规范化规则。把 digest_hash 作为键后，业务侧仍应保留一条代表性 digest_text，否则只有哈希值的报表很难排查。

把 digest_hash 接进聚合查询

如果数据来自应用采样表，可以把计算结果落成三列：digest_hash、digest_text 和 sample_sql，再按 hash 统计次数与耗时。下面的写法强调关系，不绑定某个现成表结构。

-- digest_hash 是分组键，代表文本和指标都从同一分组汇总
SELECT
  digest_hash,
  MIN(digest_text) AS representative_text,
  COUNT(*) AS execution_count,
  SUM(duration_us) AS total_duration_us,
  AVG(duration_us) AS average_duration_us
FROM sampled_sql
WHERE digest_hash IS NOT NULL
GROUP BY digest_hash
ORDER BY total_duration_us DESC;

我更倾向于把“次数”和“总耗时”同时放进结果里：次数高但单次很快的问题，和次数不多却总耗时很高的问题，处理优先级并不一样。这里的字段来自示例采样表，生产系统需要按自己的采样模型映射。

长度和异常边界别忽略

max_digest_length 决定计算规范化 digest 时可使用的字节数。语句超过这个范围后，后续 token 不再参与 digest；如果两个长 SQL 只在截断点之后不同，它们可能被归到同一类。因此，归并结果要配合合理的长度设置，并把“可能截断”当成报表说明。

还有三个容易踩的坑：

• 把 STATEMENT_DIGEST() 当成密码哈希或业务主键使用；它的目的是真实 SQL 结构归类。
• 只保存 hash，不保存规范化文本；后续看到一串十六进制值时无法解释。
• 忽略解析错误和 NULL；这会让无效输入悄悄进入统计结果。

一张表记住怎么选

相关问题

STATEMENT_DIGEST_TEXT() 和 STATEMENT_DIGEST() 能互相替代吗？

不能。前者面向阅读，后者面向归并键；最实用的做法是成对保存。

为什么两条 SQL 的 digest 可能不一样？

它们可能不只是字面量不同，也可能在表名、列名、结构或截断范围上存在差异。先比较规范化文本，再判断是否应该放进同一组。