name: text-to-sql description: 将自然语言查询转换为SQL。用于数据库查询、数据分析和报告。 version: 1.0 model: sonnet invoked_by: both user_invocable: true tools: [Read, Write, Grep, Glob] best_practices:

提供数据库模式上下文
执行前验证SQL
使用参数化查询
在样本数据上测试查询 error_handling: graceful streaming: supported verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

模式：认知/提示驱动 — 无独立实用脚本；通过代理上下文使用。

文本转SQL技能

身份

文本转SQL - 使用数据库模式上下文和查询模式将自然语言查询转换为SQL。

能力

查询生成：将自然语言转换为SQL
模式感知：使用数据库模式进行准确查询
查询优化：生成优化的SQL查询
参数化查询：创建安全的参数化查询

用法

基本SQL生成

何时使用：

从自然语言进行数据库查询
数据分析请求
报告查询
即席数据库查询

如何调用：

“生成SQL以查找上个月注册的所有用户”
“创建查询以按产品计算总营收”
“编写SQL以查找重复记录”

它做什么：

分析自然语言查询
参考数据库模式
生成SQL查询
验证查询语法
返回参数化查询

高级功能

模式集成：

加载数据库模式
理解表关系
使用列类型和约束
处理连接和聚合

查询优化：

生成高效查询
使用适当索引
优化连接
最小化数据传输

安全性：

参数化查询（防止SQL注入）
验证查询语法
在样本数据上测试
错误处理

最佳实践

模式上下文：提供完整数据库模式
查询验证：执行前验证SQL
参数化：始终使用参数化查询
测试：在样本数据上测试查询
优化：审查查询性能

集成

与数据库架构师

文本转SQL使用来自database-architect的模式：

表定义
关系
约束
索引

与开发者

文本转SQL为开发者生成查询：

查询模板
参数化查询
查询优化
错误处理

示例

示例1：简单查询

用户：“查找上个月注册的所有用户”

文本转SQL：
1. 分析查询
2. 参考用户表模式
3. 生成SQL：
   SELECT * FROM users
   WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 MONTH)
4. 返回参数化查询

示例2：复杂查询

用户：“计算第四季度按产品的总营收”

文本转SQL：
1. 分析查询
2. 参考订单和产品表
3. 生成SQL：
   SELECT p.name, SUM(o.total) as revenue
   FROM orders o
   JOIN products p ON o.product_id = p.id
   WHERE o.created_at >= '2024-10-01'
     AND o.created_at < '2025-01-01'
   GROUP BY p.id, p.name
4. 返回优化查询

评估

评估框架

基于Claude Cookbooks模式，文本转SQL评估包括：

语法验证：

SQL语法正确性
模式合规性
查询结构验证

功能测试：

在测试数据库上执行查询
结果正确性
性能验证

Promptfoo集成：

多个提示变体（基础、少样本、思维链、RAG）
温度扫描
模型比较（Haiku vs Sonnet）

评估配置：为您的评估设置创建promptfoo配置文件（例如，text_to_sql_config.yaml）。

运行评估

# 运行文本转SQL评估（先创建配置）
npx promptfoo@latest eval -c text_to_sql_config.yaml

评估指标

语法准确性：具有有效SQL语法的查询百分比
功能正确性：返回正确结果的查询百分比
模式合规性：使用正确模式的查询百分比
性能：查询执行时间和优化

Cookbooks最佳实践

1. 提供模式上下文

始终包含完整数据库模式：

具有列类型的表定义
关系和外部键
约束和索引
样本数据模式

2. 使用少样本示例

提供类似查询示例：

简单查询
具有连接的复杂查询
聚合查询
子查询模式

3. 复杂查询的思维链

对于复杂查询，使用思维链推理：

将查询分解为步骤
识别所需表
计划连接和聚合
逐步生成SQL

4. RAG用于模式理解

使用RAG检索相关模式信息：

为查询查找相关表
理解关系
获取列详细信息
检索查询模式

文本转SQLSkill text-to-sql