一篇读懂结构化数据 RAG：表格、数据库与 Text-to-SQL

结构化数据 RAG 的定义：不是「从表格里搜」，是「用表格回答」

向量 RAG 的对象是「非结构化文档」——检索出相关的文本片段、交给模型生成回答。结构化数据 RAG 的对象是「有 schema 的数据」——关系数据库的表、数据仓库的视图、电子表格——它不是「搜出相关行」，而是把自然语言问题翻译成结构化查询（SQL、Pandas 代码、或 API 调用），执行后把结果交给模型组织成回答。

这个本质差异决定了两者管线完全不同。向量 RAG 的管线：文档切块 → 嵌入 → 检索 → 生成。结构化 RAG 的管线：理解 schema → 生成查询 → 执行 → 结果 → 组织回答——它需要「理解数据模型」的能力（表与表的关系、字段的语义），这比「找相似文本」复杂得多。

Schema 理解：SQL 生成的前提

Text-to-SQL 的第一步不是写 SQL，是理解数据库的 schema——有哪些表、表之间怎么关联、字段的含义与类型。三种 schema 供给方式。方式一：DDL 直给——把 CREATE TABLE 语句放进提示词，模型从 DDL 推断表结构与关系——最简单，但对大数据库的 token 成本高。方式二：Schema 摘要——人工或自动生成 schema 的摘要（每张表的用途、关键字段的含义、常见 JOIN 关系）——比 DDL 更有用（DDL 只有类型没有语义）。方式三：Few-shot 示例——给出「问题 → SQL」的配对示例（3–5 个典型查询），让模型学习数据库的「惯用写法」——对复杂 JOIN 与业务逻辑的表达至关重要。

Schema 太大怎么办：数据库有几百张表时，全部塞进 prompt 不可行——schema 路由（先判断需要哪些表，只给相关表的 schema）或层级摘要（先给全库概览、命中相关表后展开详情）是主流方案。Text-to-SQL 的成功 80% 取决于 schema 理解的质量——模型写 SQL 的能力很强，但对「你们公司的 schema 长什么样」一无所知。

SQL 生成与执行：从生成到验证的闭环

SQL 生成的提示词工程：schema + few-shot 示例 + 用户问题 → 生成 SQL。三个工程要点。要点一：方言意识——MySQL 的 LIMIT 与 Oracle 的 ROWNUM、日期函数的差异——模型的 SQL 方言意识取决于训练数据，指定目标方言（「生成 PostgreSQL 语法的 SQL」）可以显著提升正确率。要点二：只读约束——生成的 SQL 必须只读（SELECT）——在执行前做 SQL 的解析与校验（禁止 DROP/DELETE/UPDATE——安全底线，本库安全篇的原则）。要点三：错误恢复的闭环——SQL 执行失败（语法错、列名错）→ 把错误信息回喂模型修正——「生成-执行-报错-修正」的循环是 Text-to-SQL 的标准模式（本库 Coding Agent 的验证闭环思想）。

执行结果的交给模型：SQL 返回的原始数据（表格）不是最终答案——把查询结果 + 原始问题交给模型，让模型把数据「翻译」成自然的回答（「上季度销售额是 340 万，环比增长 15%，主要由华东区贡献」——数字是 SQL 算的、叙述是模型写的）。

与向量 RAG 的分工与组合

两者的适用域有清晰的分界。结构化 RAG 适用：「有多少、什么趋势、哪个最高」——答案是数据可以算出来的（定量查询）。向量 RAG 适用：「怎么、为什么、什么意思」——答案是文本中的知识（定性查询）。组合策略：一个智能体同时持有两种工具（向量检索工具 + SQL 工具），按问题性质路由——「上季度华东区的销售政策是什么」既有数据（销售额）又有知识（政策内容）——组合查询的形态。路由的判断（本库查询路由篇）：问题的答案「在数据库里」还是「在文档里」——问题里含「多少/排名/趋势」→ 数据；含「怎么/为什么/什么规定」→ 文档。

常见坑与最佳实践

坑一：幻觉数据——模型编造不存在的列名或表名（schema 里没有的字段，模型凭训练数据「脑补」）——schema 的准确供给 + 生成后的列名校验是防线。坑二：语义的歧义——「销售额」是订单金额还是营收确认？——业务术语表（列名的业务含义注释）是解药。坑三：复杂的 JOIN 逻辑——多表 JOIN 的正确性依赖 schema 关系的理解——few-shot 中加入典型的多表 JOIN 示例。坑四：大数据量的聚合——百万行表的聚合查询很慢——先 LIMIT 探索、再精确聚合的两步策略。最佳实践的收束：Text-to-SQL 的成功率 = schema 质量 × few-shot 质量 × 验证闭环——三个变量都可以由工程控制——它不是一个「模型能力」问题，是一个「管线设计」问题。

## Text-to-SQL 的进阶模式：多表 JOIN、聚合与子查询的处理

Text-to-SQL 的简单查询（单表 SELECT）已经很成熟，真正的挑战在复杂查询。多表 JOIN：「上季度华东区的销售额和对应的销售负责人」——需要 JOIN 订单表、销售表与员工表三张表。模型对 JOIN 的正确性取决于对 schema 关系的理解（外键关系、JOIN 方向）——schema 中的外键关系描述（「订单表.region_id 关联区域表.id」）能显著提升 JOIN 的正确率。聚合与分组：「每个部门的平均薪资，按降序排列，只显示超过公司平均的部门」——嵌套的聚合（HAVING 子查询）——模型的嵌套 SQL 能力取决于训练数据中类似模式的比例。子查询：「比平均薪资高的员工」——子查询的嵌套深度是错误率的高发区。进阶的工程手段：SQL 的分解策略——复杂查询拆成多步简单查询（先查中间结果再合并——每步的 SQL 更简单、验证更容易）；SQL 的模板化——常见查询模式预定义为模板（按部门统计、按时间趋势——模板填参数），模型的自由生成只处理模板覆盖不了的长尾。进阶模式的收束：Text-to-SQL 的准确率与查询复杂度成反比——简单查询 95%+、复杂 JOIN 可能只有 60-70%——分解策略与模板化是提升复杂查询准确率的两大手段。

Text-to-SQL 的评测与迭代：准确率的度量与提升路径

Text-to-SQL 的评测需要专门的度量体系：执行准确率（生成的 SQL 执行结果与标准答案一致的比例）、语法正确率（SQL 是否能成功执行不报错）、以及 JOIN 正确率（多表查询的 JOIN 路径是否正确）。评测集的构造：从真实用户的查询日志中采样（覆盖简单 SELECT、多表 JOIN、聚合、子查询等不同难度），每类 10-20 个样本，标注标准 SQL 与标准答案。提升的路径按瓶颈定位：语法错误 → 改进 few-shot 的方言覆盖；列名幻觉 → 强化 schema 的描述质量；JOIN 错误 → 增加 schema 关系描述与 JOIN 示例；语义错误 → 增加业务术语表（列名的业务含义注释）。Text-to-SQL 的迭代是持续的：新查询类型出现 → 测试集扩展 → 提示词或 schema 描述更新 → 回归验证。Text-to-SQL 的准确率不是一次达标就完事，它需要与知识库质量管理（本库质量篇）一样持续运营——新表、新字段、新业务逻辑都可能导致准确率退化，回归测试是防线。

Text-to-SQL 的实战清单：从部署到优化的检查项

Text-to-SQL 部署的检查清单：schema 的供给策略确认（DDL/摘要/few-shot 的选择与测试）、SQL 的安全约束（只读校验与禁止 DML 的解析检查）、错误恢复的闭环（生成-执行-报错-修正的自动化）、结果的展示格式（表格/图表/文本的输出格式）、以及用户反馈的收集（SQL 正确性的用户确认）。部署后的运维：SQL 正确率的持续监控、新表与新字段的 schema 更新、few-shot 示例的定期更新（新查询模式的补充）、以及 bad case 的入库与修复。Text-to-SQL 的检查清单是一个持续迭代的工程文档——每次发现新的 failure mode 都要加入清单——清单越完善、覆盖越全面。

Text-to-SQL 的进阶：Schema Linking 与列名消歧

Text-to-SQL 的核心难点之一是 Schema Linking——把自然语言中的实体映射到数据库中的正确表和列。「查询客户的订单」——「客户」对应 customers 表还是 users 表？「订单」是 orders 还是 order_items？Schema Linking 的策略：列名的语义匹配（用嵌入模型将用户查询的实体与 schema 的列名/注释匹配——语义相似度最高的是正确映射的候选）、外键关系的利用（通过外键关系推断 JOIN 路径——「客户有订单」的外键关系指示了 JOIN 方向）、以及列名的消歧——同名字段的消歧（两个表都有 name 字段——通过上下文判断用哪个表的 name）。Schema Linking 的评估：schema linking 的准确率是 Text-to-SQL 的第一道关卡——链接错了表或列，后续的 SQL 生成必然错误——schema linking 的准确率是 Text-to-SQL 评测的独立维度。

Text-to-SQL 的进阶：Schema Linking 与执行校验

Text-to-SQL 的核心难点之一是 Schema Linking——把自然语言中的实体映射到数据库中的正确表和列。「查询客户的订单」——「客户」对应 customers 表还是 users 表？Schema Linking 的策略：列名的语义匹配（用嵌入模型将用户查询的实体与 schema 的列名注释匹配）、外键关系的利用（通过外键关系推断 JOIN 路径）、以及列名的消歧——同名字段通过上下文判断归属哪个表。链接错了表或列，后续的 SQL 生成必然错误——schema linking 的准确率是 Text-to-SQL 评测的独立维度。方言意识同样关键——MySQL 的 LIMIT 与 Oracle 的 ROWNUM、日期函数的差异——指定目标方言可以显著提升正确率。安全底线是只读约束：执行前对 SQL 做解析校验，禁止 DML 语句进入数据库。错误恢复的闭环——SQL 执行失败把错误信息回喂模型修正——生成、执行、报错、修正的循环是 Text-to-SQL 生产化的标准模式。

小结

结构化数据 RAG 把自然语言翻译成结构化查询，与向量 RAG 的「检索文本」是本质不同的两条管线。Schema 理解（DDL + 摘要 + few-shot）是成功的前提，SQL 生成与执行的闭环（生成 → 执行 → 报错 → 修正）是标准模式，与向量 RAG 的路由组合（数据问题走 SQL、知识问题走向量）是生产架构。Text-to-SQL 的成功率 = schema 质量 × few-shot 质量 × 验证闭环——它不是模型能力问题，是管线设计问题。