MySQL STATEMENT_DIGEST_TEXT 怎样把 SQL 规范化为摘要文本

把一条SQL作为字符串交给 STATEMENT_DIGEST_TEXT()，MySQL会返回可读的规范化摘要文本。它适合把主要结构相同、常量不同的请求放到一起观察；需要摘要哈希时则使用 STATEMENT_DIGEST()。

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

先确定需要原文、摘要文本还是哈希

假设工单里收集了两条查询：一条按商品编号317查询，另一条按编号922查询。如果只按原文计数，会得到两个条目；若要排查某种查询形状的调用情况，就更希望把常量差异从分组依据中移走。

先分清三种材料：SQL原文用于复现上下文；摘要文本用于阅读结构；摘要哈希用于给摘要一个紧凑标识。摘要不是执行计划，也不能单独说明查询是否走索引。以下示例是供读者使用的SQL，没有在本地数据库执行。

用字符串输入生成可读摘要

-- 将待分析SQL作为数据传入；这里不会执行字符串中的查询
SET @sample_sql = 'SELECT sku FROM inventory WHERE warehouse_id = 317';

-- 取可读的规范化摘要，观察常量与标识符的表示
SELECT STATEMENT_DIGEST_TEXT(@sample_sql) AS normalized_sql;

在这个简单例子中，观察重点是常量317对应的位置变成参数标记 ?，而inventory、sku、warehouse_id这些标识符仍然用于表达查询结构。不要把客户端显示的列宽或反引号外观当成业务含义。函数的返回值及解析行为见MySQL函数参考。

再给相同结构换一个常量，分别计算摘要：

-- 只改变条件里的常量，用于比较规范化结果
SET @sample_a = 'SELECT sku FROM inventory WHERE warehouse_id = 317';
SET @sample_b = 'SELECT sku FROM inventory WHERE warehouse_id = 922';

SELECT
  STATEMENT_DIGEST_TEXT(@sample_a) AS digest_a,
  STATEMENT_DIGEST_TEXT(@sample_b) AS digest_b;

这个对照用于理解同一种查询结构的归类；不要把它推广成“所有语义等价SQL都一定得到相同摘要”。如果把表名改成inventory_archive，就已经改变了被保留的对象标识。

与正则替换和格式化方案对比

如果输入是MySQL语句且希望采用MySQL的摘要口径，我会优先用内置函数。若只是排版供审阅，保留常量的格式化工具更直接。跨数据库采集则应另行明确方言支持，不能默认一个服务端解析器接受所有数据库的语法。

例如字段名 metric_2026和字符串里的数字都可能出现在文本里，简单“替换所有数字”的规则没有区分语法角色。这个例子说明自定义文本处理需要明确适用范围，而不是宣称某段正则能完整代替解析器。

给聚合工具同时保留文本与标识

-- 为同一条输入同时取得展示文本和摘要标识
SET @sample_sql = 'SELECT sku FROM inventory WHERE warehouse_id = 317';

SELECT
  STATEMENT_DIGEST_TEXT(@sample_sql) AS digest_text,
  STATEMENT_DIGEST(@sample_sql) AS digest_id;

在工具的数据结构里，可以把 digest_text作为列表的可读标题，把 digest_id作为摘要标识，同时保留采样来源。原始SQL若需要留存，应放在有明确访问范围的样本记录里。不要试图从摘要文本反推原来的317或922。

处理长SQL和解析失败

解析失败会报错，NULL输入返回NULL。批量工具要分别记录“输入缺失”“解析失败”和“成功取得摘要”，不应把错误统一改成空字符串后继续分组。

长SQL还受 max_digest_length影响；缓冲区截断后，差异若位于未收集的尾部，摘要可能无法区分它们。排查时先保留输入长度、运行环境与这个配置值，再决定如何解释合并结果。规范化机制及长度限制见MySQL摘要与采样文档。

-- 查看当前实例的摘要计算缓冲配置，不修改系统设置
SELECT @@GLOBAL.max_digest_length AS digest_buffer_bytes;

摘要里的对象名仍然可见，因此它不应被当作隐藏全部数据库结构信息的手段。是否允许把摘要写入日志、展示给哪些角色，仍由工具的数据访问规则决定。

摘要文本能直接作为可执行查询吗？

应把它作为展示与归类材料。常量已被移除，不能把摘要文本当作原始业务SQL直接重放。

相同摘要是否意味着执行计划相同？

摘要描述查询形状；执行计划和实际耗时还需要另外分析。不要用一个摘要标识替代计划与性能证据。

可以恢复原来参数吗？

不能从摘要还原被移除的常量。需要复现时，应关联经过适当授权保存的原始样本和必要上下文。