自然语言转SQL引擎（免费版）

概述

本Skill解决一个高频痛点：业务人员知道想要什么数据，但无法将意图转化为SQL查询。通过自然语言描述需求，引擎自动生成语法正确、可执行的SQL语句。

免费版支持单表查询、基础多表JOIN、聚合统计等核心场景，覆盖日常80%的数据查询需求。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：将自然语言描述转、换为标准、支持多方言与、面向数据分析人员、与后端开发者的自、然语言转、知道想要什么数据、但写不出、的核心痛点、核心能力、将中文、英文的自然语言描、述转换为语法正确、支持表结构自动识、关系推导与查询验、Use、when、需要数据分析、报表生成、统计洞察、数据可视化时使用、不适用于实时流数、据处理等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：业务人员自助查询

运营人员需要查看"上个月消费超过1000元的VIP用户名单"，但不熟悉SQL。向Agent描述需求并提供表结构，引擎自动生成查询语句。

场景二：快速原型验证

开发者在设计新功能时，需要快速验证某个查询逻辑是否正确。用自然语言描述预期结果，引擎生成SQL后直接在测试库执行验证。

场景三：SQL学习辅助

SQL初学者通过对比自然语言描述与生成的SQL，理解每个子句的作用，加速学习过程。

快速开始

第一步：提供Schema（约30秒）

引擎需要知道你的表结构才能生成正确查询。提供方式任选其一：

-- 方式一：CREATE TABLE语句
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(200),
    vip_level INT DEFAULT 0,
    created_at TIMESTAMP
);
# ...
CREATE TABLE orders (
    id BIGINT PRIMARY KEY,
    user_id BIGINT REFERENCES users(id),
    amount DECIMAL(10,2),
    status VARCHAR(20),
    created_at TIMESTAMP
);

-- 方式二：DESCRIBE输出
DESCRIBE users;
DESCRIBE orders;

第二步：描述你的查询需求

帮我查询上个月消费总金额超过1000元的VIP用户，按消费金额从高到低排列，只显示前20名

第三步：获取生成的SQL

SELECT
    u.id,
    u.name,
    u.email,
    SUM(o.amount) AS total_spent
FROM users u
INNER JOIN orders o ON u.id = o.user_id
WHERE u.vip_level > 0
    AND o.status = 'completed'
    AND o.created_at >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1 month')
    AND o.created_at < DATE_TRUNC('month', CURRENT_DATE)
GROUP BY u.id, u.name, u.email
HAVING SUM(o.amount) > 1000
ORDER BY total_spent DESC
LIMIT 20;

示例

自然语言到SQL子句映射表

JOIN类型选择规则

多方言适配

-- PostgreSQL: 使用DATE_TRUNC
SELECT DATE_TRUNC('month', created_at), COUNT(*)
FROM orders GROUP BY 1;
# ...
-- MySQL: 使用DATE_FORMAT
SELECT DATE_FORMAT(created_at, '%Y-%m-01'), COUNT(*)
FROM orders GROUP BY 1;
# ...
-- SQLite: 使用strftime
SELECT strftime('%Y-%m-01', created_at), COUNT(*)
FROM orders GROUP BY 1;

最佳实践

Schema提供规范

1. 必须提供表名和字段名：引擎不会猜测不存在的字段
2. 标注字段类型：特别是时间类型（TIMESTAMP vs DATE）
3. 标注外键关系：帮助引擎正确推导JOIN条件
4. 提供业务语义：如 status 字段的枚举值含义

查询质量校验清单

生成SQL后，引擎自动执行以下校验：

• 所有引用的字段名在Schema中存在
• 所有表别名已定义
• JOIN条件使用了正确的关联字段
• 聚合查询包含GROUP BY
• 无歧义的字段引用（多表时使用别名限定）
• LIMIT语句配合ORDER BY使用

错误恢复策略

常见问题

Q1：没有提供Schema会怎样？

A：引擎不会猜测表名或字段名。如果未提供Schema，会主动询问用户："请提供相关表的字段名和类型，例如CREATE TABLE语句或DESCRIBE输出。"这是为了避免生成引用不存在字段的无效SQL。

Q2：支持哪些SQL方言？

A：免费版支持 PostgreSQL、MySQL、SQLite三种主流方言。生成查询时会根据用户指定的数据库类型适配语法差异（如日期函数、字符串拼接、分页语法等）。

Q3：能处理复杂的多表查询吗？

A：免费版支持最多2张表的JOIN查询。如果涉及3张及以上表的复杂关联，建议使用专业版，支持多表嵌套JOIN、子查询、CTE（公用表表达式）等高级特性。

Q4：生成的SQL会自动执行吗？

A：不会。本引擎只生成SQL语句，不执行查询。生成的SQL需要用户自行在数据库客户端中执行。这样可以避免误操作风险，用户可以在执行前审查SQL。

Q5：如何提高生成质量？

A：(1) 提供尽可能详细的Schema信息，包括字段类型和外键关系；(2) 在描述中明确指定排序、限制等条件；(3) 使用具体字段名而非泛化描述；(4) 标注目标数据库类型。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 数据库客户端: 任意支持SQL的客户端（DBeaver/Navicat/psql/mysql等）

依赖详情

API Key 配置

• 数据库连接串: 存储于环境变量 DATABASE_URL，格式 postgresql://user:pass@host:port/dbname
• 禁止: 在代码或脚本中硬编码数据库密码
• 推荐: 使用 .env 文件或密钥管理服务

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent生成SQL查询语句

已知限制

本免费体验版限制以下高级功能：

• 不支持3张及以上表的多表JOIN查询
• 不支持子查询、CTE（公用表表达式）、窗口函数
• 不支持查询解释（内联注释说明）
• 不支持替代方案生成（多种写法对比）
• 不支持查询性能优化建议与执行计划分析
• 不支持存储过程与触发器生成

解锁全部功能请使用专业版：text2sql-engine-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "自然语言转SQL免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "text2sql engine"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}