Text-to-SQL 实践:元数据质量与生成结果验证

举报
数据库小学妹 发表于 2026/11/19 16:46:59 2026/11/19
【摘要】 同一个问题、同一个模型,换掉喂进去的元数据,错的地方就少了一大半。文章把 Text-to-SQL 的输入拆成 DDL、注释、样例值、指标口径四件套,讲清表太多时怎么召回与裁剪、生成后怎么用 EXPLAIN 预演和三层验证兜住,并给出一份可直接抄的 schema 描述模板。

大家好,我是数据库小学妹👋我踩过的坑,你别再踩。

2026 年上半年接了个活,给一套业务库配 Text-to-SQL。第一个问题很朴素,上个月华南的有效客户有多少。模型回了一段语法漂亮的 SQL,我跑了一遍,零行。让它改一版,数出来三万八。业务同学看了一眼说,这数不对吧,实际只有一千多。我以为模型不行,换了一个,还是三万八。

几次测试之后我突然想明白一件事。两个模型给出同一个错答案,说明它们看到的世界一样。而这个世界,是我喂给它们的。模型不知道华南是什么,也不知道有效客户怎么算。它只看见那几百行 DDL,然后按常识往下猜。

一、Text-to-SQL 的上限,卡在元数据上

先说清一件事。模型对你的库一无所知,它只知道上下文里那几百行 DDL。status TINYINT NOT NULL COMMENT '状态' 在它眼里就是一个整数,注释只有"状态"两个字。它可能猜 1 代表正常,也可能猜 0 是正常。猜对猜错,它都不会吭声,条件写出来照样能跑。

比 status 更麻烦的是三件事。一个是单位,amount BIGINT 存的是分还是元。DDL 里不写,模型就默认按元算。比按分算,客单价差一百倍。

一个是同名不同义。status 在客户表是客户状态,在订单表是订单状态。在工单表又是工单状态,模型看到三个 status 很容易拼错表。还有一个是时间,create_time、created_at、gmt_create 同时存在。取值还分业务时间和系统时间。

所以我现在的判断很干脆。Text-to-SQL 的上限,一大半由元数据质量决定。模型能力决定它把话说通不通顺;能不能把数算对,取决于你有没有告诉它这张表在这个公司里是什么意思。这篇不测模型排行榜,也不讲怎么审 AI 写的 SQL,只讲喂进去的那份东西。

二、Text-to-SQL 要喂的四件套,缺一件错一类

不用把整库文档都塞进去,四样东西就够用。它们各自解决一类歧义,缺哪一样就有一类错固定发生。我按这个顺序喂:DDL 定形状,注释定含义,样例值定取值,口径定算法。四样齐了,模型瞎猜的空间就小了。

喂什么 具体内容 解决的歧义 缺了会怎样
DDL 字段名、类型、主键、索引 有哪些字段可用、能不能连 编字段、连错表
注释 字段含义、取值范围 这个字段到底指什么 status=1 猜错,条件全歪
样例值 枚举、编码、单位 值长什么样 把编码当文本前缀匹配,直接零行
指标口径 业务词怎么算 “有效”“新增”“流失” SQL 能跑,数与业务对不上

注释和样例值最容易被跳过,因为它们看起来模型自己能懂。我踩坑那次就是这样。region_code VARCHAR(6) 存的是行政区划代码,我只写了"地区编码"四个字。模型不知道 440000 是广东,就写了 region_code LIKE '华南%'。全表扫一遍,一行没匹配上,于是换了个更宽松的条件,数就上去了。

-- 裸 DDL 下模型写出来的:把"华南"当成字符串前缀
SELECT COUNT(DISTINCT customer_id) FROM dwd_customer
WHERE status = 1 AND region_code LIKE '华南%';

-- 补了样例值和口径之后:按行政区划前缀,去掉已删除,带上有效客户定义
SELECT COUNT(DISTINCT customer_id) FROM dwd_customer
WHERE is_deleted = 0
  AND status = 1
  AND is_verified = 1
  AND LEFT(region_code, 2) IN ('44','45','46')
  AND last_login_time >= NOW() - INTERVAL 30 DAY;

补上样例值,它自己就会写 LEFT(region_code,2) IN ('44','45','46')。第一条返回零行,我把结果贴回去,让它重写。它放宽了条件,把 status = 1 的全都算了进去,三万八就是这么来的。第二条才是一千二百多,跟业务给的数对上了。区别不在模型水平。它拿到的是"地区编码"四个字,还是"44=广东、45=广西、46=海南"这一串。

三、表太多先裁剪,别让模型自由联想

库里有几百张表的时候,全量 DDL 是一份很重的输入。上下文窗口现在不小,几百张表有时真塞得进去。但塞进去之后,无关的表会一起干扰,模型开始在它们之间乱连。做法分两步,先按问题召回候选表,再对候选表裁列。

召回可以很土,不用上向量库。按业务域分白名单,一个域给五到十张表。再用字段名和注释做关键词匹配,命中"客户"就带上客户域。这一步的目标不是全,是把候选压到十张以内。

裁列也一样。敏感字段不要喂,既省上下文,也顺手减少暴露面。宽表里那几十个埋点字段、扩展字段对问答没用,一并砍掉。模型要的是能过滤和聚合的列,不是全部列。

下面这份模板可以直接改着用,我实际就按这个格式组织。它比裸 DDL 长不了太多,但把该说的都说了。顺序不用照抄,建议保留先用途、再字段、最后口径。模型读到第几行该干什么,是靠这个顺序养出来的。

### 表:dwd_customer(客户主档)
用途:一行一个客户,记录注册与状态。客户数、有效客户类问题的主表。
字段:
- customer_id   BIGINT   主键,客户唯一编号
- status        TINYINT  客户状态:0=待激活 1=正常 2=冻结 3=已注销
- is_verified   TINYINT  0=未实名 1=已实名
- region_code   VARCHAR(6) 行政区划代码,前两位是省:
                44=广东 45=广西 46=海南
- total_amount  BIGINT   累计消费金额,单位:分
- register_time DATETIME 注册时间(北京时间)
- last_login_time DATETIME 上一次登录(北京时间,可为空)
- is_deleted    TINYINT  0=有效 1=已删除,查询必须加 is_deleted=0
注意:金额类字段单位是分;时间字段均为北京时间。
口径:
- 有效客户 = last_login_time 在近 30 天内,且 is_verified=1,且 status=1,且 is_deleted=0
- 华南 = region_code 前两位属于 44~46

注意最后两行。它们不是 DDL,也不该写在数据库注释里。但对模型的价值,比前面所有行加起来都大。这类口径属于公司知识,建议单独维护成一份文件。跟代码一起走版本管理,改口径就改这份文件。

四、口径写进库里,别散在提示词里

指标口径是最容易被忽略的一件。业务说"有效客户",技术在库里有七八种实现。近三十天登录过、近三十天有下单。已完成实名、状态正常且未注销,都算一种。这几种口径算出来的数,能差一个数量级。

把定义写进元数据,模型就不会自由发挥。写不进去,就先在库里做成视图,让它只能查那个视图。问题是这两条都靠人自觉,人一走口径也跟着走。提示词改一版,口径散一份;换个项目,又得重来一遍。

2026 年 10 月 30 日,金仓开了一场发布会,主题是"Hello,AI数据库"。会上讲的库内语义构建,解决的正是这一段。语义对象里定义实体、属性、关系、口径、规则、标签,还有同义词。演示里把"大区"和"销售区域"指到同一个字段,把毛利率写成带公式的指标。更关键的是流程:语义先由 AI 推荐含义,再由人修正、批准,批准之后才生效。

这一条比技术本身重要。口径必须有人签字,不能由模型自己定。同义词进了库,"同名不同义"这个问题也从提示词搬到了库里。改一次,所有问数入口一起生效。不用挨个改提示词,也不会出现三份口径对不上。

五、生成之后,Text-to-SQL 要过三层验证

模型给的 SQL 不能直接执行,至少要过三道。三道分别是能不能跑通、结果对不对、代价可接受。顺序不能反,前一道没过,后一道白测。下面一道道说。

第一层是能不能跑通。这一步便宜,但要放在只读账号下跑。给 AI 用的账号不该和应用共用,也不该有写权限。行数上限也不能只写在提示词里,得在驱动层设。比如 JDBC 的 setMaxRows,或者给生成的 SQL 外面套一层 LIMIT。

第二层是结果对不对。做法是抽样比对,挑十到二十个高频问题。人工写标准 SQL,拿到标准答案,再和模型的结果比。这十道题就是你的最小标注集。后面每次改元数据、换模型,都拿它回归一遍。

第三层是代价可接受。语法对、结果也对,但执行计划是全表扫。这种在演示里看着成功,上线就是事故。所以执行前先过一遍 EXPLAIN。

TREE 格式里出现 Table scan on,再看后面的 rows 估算值。到十万级就拦下来,让它重写或者直接拒答。传统格式里对应的是 type 那一列的 ALL。这一层最容易被省掉,也最容易出事。

-- 生成的 SQL 先别执行,先看计划(FORMAT=TREE 需要 8.0.16 起)
EXPLAIN FORMAT=TREE
SELECT COUNT(DISTINCT c.customer_id)
FROM dwd_customer c
WHERE c.is_deleted = 0
  AND c.status = 1
  AND c.is_verified = 1
  AND LEFT(c.region_code, 2) IN ('44','45','46')
  AND c.last_login_time >= NOW() - INTERVAL 30 DAY;

-- 兜底:超时 + 只读(max_execution_time 只对只读 SELECT 生效,单位毫秒)
SET SESSION max_execution_time = 5000;

EXPLAIN 有两个盲区要知道。它不真正读数据,代价很小,但也看不到实际行数。想看实际行数得用 EXPLAIN ANALYZE(8.0.18 起)。那个是真跑,风险回到第一层,得在只读账号和超时保护下用。另外 max_execution_time 只掐只读 SELECT 的执行时长。卡在锁等待上不算,存储过程里的 SELECT 也不受它管。

金仓的语义对象带版本号,这一条在第二层帮得上忙。口径改过之后,同一句问题算出来的数会变。答案是哪个版本的口径算出来的,能查得到。验收时把版本号一起记下来,回归才有对比基准。

六、把错例变成资产,准确率才涨得动

最初那二十道题,我跑了三个版本。裸 DDL 答对六个,补上注释和样例值到十一个,再补口径到十五个。样本很小,只能看方向。但方向足够清楚:错误集中在字段含义和业务口径,不在 SQL 语法。

按错误类型分开统计,比看一个总准确率有用得多。五类错法,修法完全不同。表选错靠召回优化,列选错靠裁剪和命名。条件漏靠样例值,口径错只能靠口径文件。聚合维度错,靠几个正例教会它。

错例本身要回灌。把"问题 + 错误 SQL + 正确 SQL + 一句话说明错在哪"攒成几条示例,塞进提示词。这比写十条规则管用。我现在维护的是一个二三十条的错例库。谁发现答错就补一条,比开会讨论规则有效。这也是 Text-to-SQL 和纯手写 SQL 最不一样的地方:错误会自己长出来。

七、给 AI 的账号,边界要画在库上

给 AI 用的账号必须独立,只读,还得带超时和行数上限。只读挡的是写,挡不住它把整张表拉一遍。这件事我在讲 Agent 账户边界时专门拆过,这里补另一半。读多少、读多久,得在连接层卡住,不要指望模型自觉。

库这一侧还有一道闸。金仓把这些控制收进库内原生数据安全管控里。具体是角色权限、访问控制、SQL 防火墙、行级控制、审计五项。落到问数场景,第一件事是问清智能体挂的是哪个账户。第二件是把该拦的语句拦在库里,不是写在提示词里。第三件是让审计日志能对上同一个请求。

还有一种接法容易被忽略。智能体不直连数据库,凭证和连接池托管在服务端。KES 的 MCP Server 属于后一种。凭证不落在智能体那一侧,出事的时候能查得到人。

八、避坑清单

第一条是注释。status 后面只写"状态"两个字,等于没写。要写清 0、1、2、3 各代表什么,谁维护,改了通知谁。我给项目做验收时只看一件事:把注释导出来,业务同学能不能读懂。

口径不要散落在提示词里。今天写在提示词,明天写在文档,后天在某人脑子里。三份口径,迟早对不上。落到库里做成视图,或者落到一份跟代码同仓的文件里。只有一份是真的,其余的都是隐患。

最后一条是我自己踩的。我把全库 DDL 一次性喂进去,五百多张表。模型确实看得全,但它把订单表的 status 当成了客户状态。算出来的"有效客户"等于"所有下过单的客户",数直接大了一截。现在我给每个业务域单独一组表,一次不超过十张。

写在最后

AI 写 SQL 这件事,卡的不是它会不会写。卡的是你有没有把这张表在这个公司里是什么意思告诉它。DDL 只说形状,不说含义;注释、样例值、口径才是含义。这三样补齐,同一套模型的表现能差出一倍多。

这也是我看好金仓这条路的原因。它把语义、推理、安全三块能力搬进内核,落在信创和自主可控的底座上。语义放库内,口径就有人签字、有版本、有留痕。安全放库内,问数的权限边界就不用赌模型守不守规矩。关键基础设施这类场景敢让 AI 直接查库,靠的正是这些。数据主权握在自己手里,比多一个跑分实在。

你们给 AI 喂表结构时,注释写到什么程度?有没有遇到过同名 status 拼错表?评论区聊聊,我把我的 schema 模板整理一份给你。

我是数据库小学妹,帮你少走弯路少踩坑,咱们下篇见👋

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。