核心功能与用法
text-to-sql 是一个自然语言到SQL查询的转换工具，专为解决"懂业务但不懂SQL"的用户痛点设计。其核心定位明确：作为意图翻译桥梁，而非SQL执行环境、schema设计工具或数据分析平台。
三大使用模式
| 模式 | 功能 | 适用场景 |
|------|------|---------|
| `/text-to-sql` | 生成标准SQL查询 | 用户描述数据需求并提供了数据库schema |
| `/text-to-sql/explain` | 输出带注释的SQL | 用户需要学习理解查询逻辑 |
| `/text-to-sql/alternatives` | 提供2-3种替代方案 | 用户对比不同JOIN策略或子查询写法 |
标准执行流程
1. 确认Schema：强制要求用户提供表结构，绝不猜测字段名
2. 意图映射：将"最近30天"→date >= '2024-01-01'、"前10名"→ORDER BY ... LIMIT 10等
3. JOIN处理：自动识别多表关联需求，选择INNER/LEFT JOIN类型
4. 验证输出：检查字段存在性、别名一致性、聚合完整性
显著优点
- 意图识别精准：内置完整的自然语言→SQL组件映射表，覆盖90%常见查询场景
- 安全机制严格：强制schema前置验证、禁止SELECT *、强制表别名、字段全限定引用
- 教学友好：explain模式降低SQL学习门槛，alternatives模式展示最佳实践对比
- 多方言支持：适配PostgreSQL、MySQL、SQLite等主流数据库语法差异
潜在局限
- 非执行环境：仅生成代码，不验证查询结果正确性，也不返回实际数据
- 复杂查询边界：窗口函数、递归CTE、存储过程等高级特性支持有限
- 业务语义盲区：无法理解字段业务含义（如"活跃用户"需用户自行定义计算逻辑）
- 关系推断依赖：多表JOIN时必须用户明确外键关系，无法自动推断
适合人群
| 用户类型 | 使用场景 |
|---------|---------|
| 产品经理/运营 | 自助提取数据，减少开发排期依赖 |
| 数据分析师 | 快速生成查询草稿，再人工优化 |
| SQL初学者 | 通过explain模式学习查询结构 |
| 全栈开发者 | 处理不熟悉的复杂schema时加速查询编写 |
常规风险提示
1. 数据安全风险：生成的查询可能涉及敏感字段，需用户自行审查
2. 性能风险：无法评估索引命中情况，复杂查询可能产生全表扫描
3. 语义偏差风险：自然语言歧义可能导致查询逻辑与真实意图不符（如"最近"是否包含今天）
4. schema同步风险：若提供的表结构与实际数据库不一致，查询将执行失败