核心用法
Text-to-SQL 是一款将自然语言需求转换为标准 SQL 查询的专业工具，核心定位是解决"懂业务但不懂代码"的用户痛点。使用时需同时满足三个条件：自然语言描述 + 数据库 schema + SQL 请求。
三种工作模式
- 默认模式 (
/text-to-sql)：直接输出语法正确的 SQL 查询 - 解释模式 (
/text-to-sql/explain)：附带逐行注释，适合学习 SQL - 对比模式 (
/text-to-sql/alternatives)：提供 2-3 种等效写法（JOIN vs 子查询 vs CTE），帮助优化思路
执行流程
1. 确认 Schema：强制要求提供表结构，绝不猜测列名；支持 CREATE TABLE、DESCRIBE 输出等多种格式
2. 意图映射：将"最新"转为 ORDER BY date DESC LIMIT 1，将"每月收入"转为 DATE_TRUNC + GROUP BY
3. 智能 JOIN：自动识别多表关联需求，选择 INNER/LEFT JOIN 并匹配合适的键
4. 生成校验：检查列存在性、别名一致性、聚合完整性，拒绝 SELECT *
显著优点
- 精准性：强制 schema 验证，杜绝"幻觉列名"
- 教育性：解释模式降低 SQL 学习门槛
- 灵活性：方言感知（PostgreSQL/MySQL/SQLite），支持复杂嵌套查询
潜在局限
- 非执行环境：只生成不运行，需配合数据库工具使用
- 无 schema 设计能力：无法优化表结构或建议索引
- 关系依赖：外键关系需用户说明，不会自动推断
适合人群
- 产品经理、运营、分析师：快速获取数据无需依赖开发
- SQL 学习者：通过对比模式理解不同写法的差异
- 开发者：快速草拟复杂查询后再微调
常规风险
- 方言差异：未明确指定时可能生成语法不兼容的函数（如
DATE_TRUNC仅限 PostgreSQL） - 性能盲区：不评估查询执行计划，可能生成全表扫描语句
- 数据权限：生成的查询本身不携带权限检查，需在执行层控制