| name | query-writing |
| description | 用于编写和执行 SQL 查询 - 支持多维度分析、多条 SQL 协同、智能图表推荐 |
查询编写技能
何时使用此技能
当您需要通过编写和执行 SQL 查询来回答问题时应使用此技能。
简单查询工作流程
对于涉及单个表的直接问题：
- 识别表 - 哪个表包含所需数据？
- 获取架构 - 使用
sql_db_schema 查看列
- 编写查询 - 使用 WHERE/LIMIT/ORDER BY 选择相关列
- 执行 - 使用
sql_db_query 运行
- 格式化答案 - 清晰地呈现结果
复杂查询工作流程
对于需要多个表的问题：
1. 规划方法
使用 write_todos 分解任务：
- 识别所有需要的表
- 映射关系（外键）
- 规划 JOIN 结构
- 确定聚合操作
- 判断是否需要多条 SQL
2. 检查架构
对每个表使用 sql_db_schema 查找连接列和所需字段。一次传入多表名，减少调用。
3. 获取表关系
使用 sql_db_table_relationship 获取表间外键关系，确保 JOIN 条件正确。
4. 构建查询
- SELECT - 列和聚合函数
- FROM/JOIN - 通过 FK = PK 连接表
- WHERE - 聚合前的过滤条件
- GROUP BY - 所有非聚合列
- ORDER BY - 有意义的排序
- LIMIT - 默认 100 行
5. 验证和执行
检查所有 JOIN 都有条件，GROUP BY 正确，然后运行查询。
SQL 生成规则
- 只生成 SELECT 查询。 绝不生成 INSERT/UPDATE/DELETE/DROP/ALTER。
- 默认附加 LIMIT 100，除非用户明确指定数量。
- 使用正确引号（MySQL 用反引号，PostgreSQL/SQLite 用双引号，SQL Server 用方括号）。
- 只查询相关列，不使用 SELECT *。
- 使用表别名以提高清晰度（如
o for orders, p for products）。
- 日期格式化： 如果存在时间字段且未指定格式：
- datetime →
yyyy-MM-dd HH:mm:ss
- date →
yyyy-MM-dd
- year-month →
yyyy-MM
- 多表关联： 优先使用 schema 中的主键和外键。
多维度查询策略
根据用户问题复杂度，可以生成多条 SQL，分别获取不同维度的数据：
何时使用多条 SQL
| 场景 | 策略 |
|---|
| 趋势+归因分析 | SQL1: 时间维度趋势数据；SQL2: 分类维度归因数据 |
| 综合报告 | SQL1: 汇总 KPI；SQL2: 趋势数据；SQL3: 排名/Top N |
| "为什么"类问题 | SQL1: 总体趋势确认变化；SQL2: 按维度分解贡献 |
| 对比分析 | SQL1: 当前周期数据；SQL2: 对比周期数据 |
多维度查询意识
根据用户问题，自动判断需要哪些维度的查询：
- 趋势分析 → 包含 ORDER BY time ASC，按时间粒度 GROUP BY
- 分类对比 → 包含 ORDER BY metric DESC，按类别 GROUP BY
- 占比分析 → 包含百分比计算（子查询或窗口函数）
- 归因分析 → 包含多维度 GROUP BY + 增量贡献
- 增长率分析 → 使用窗口函数 LAG() 计算同比/环比
每条查询的元信息
为每条 SQL 标注用途和推荐图表类型，便于后续报告生成：
查询 1：获取月度趋势数据
推荐图表：折线图/面积图
SQL: SELECT ...
查询 2：获取各品类占比
推荐图表：饼图/环形图
SQL: SELECT ...
图表类型推荐
| 数据特征 | 推荐图表 | 说明 |
|---|
| 时间序列 | 折线图/面积图 | 展示趋势变化 |
| 分类排名 | 水平柱状图 | Top N 排名展示 |
| 占比结构 | 饼图/环形图 | 各分类占比 |
| 多维对比 | 分组柱状图 | 不同组间指标对比 |
| 变化归因 | 瀑布图 | 各维度对变化的贡献 |
| 趋势+量 | 双轴图 | 柱线组合，展示量和率 |
| 综合评估 | 雷达图 | 多维度能力画像 |
| 增长率分析 | 折线图+数据标签 | 环比/同比变化 |
| 帕累托分析 | 组合图（柱状+累积线） | 头部集中度分析 |
| 异常检测 | 折线图+红色标注 | 偏离均值的异常值 |
示例：按国家统计收入
SELECT
c.Country,
ROUND(SUM(i.Total), 2) as TotalRevenue
FROM Invoice i
INNER JOIN Customer c ON i.CustomerId = c.CustomerId
GROUP BY c.Country
ORDER BY TotalRevenue DESC
LIMIT 10;
示例：多维度销售分析（多条 SQL）
用户问题： "分析今年的月度销售趋势，为什么8月特别高？"
查询 1：月度趋势
SELECT
DATE_FORMAT(order_date, '%Y-%m') as month,
ROUND(SUM(amount), 2) as total_sales,
COUNT(*) as order_count
FROM orders
WHERE YEAR(order_date) = 2024
GROUP BY DATE_FORMAT(order_date, '%Y-%m')
ORDER BY month ASC;
推荐图表：面积折线图
查询 2：8月品类分解归因
SELECT
p.category,
ROUND(SUM(o.amount), 2) as sales,
COUNT(*) as order_count
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE DATE_FORMAT(o.order_date, '%Y-%m') = '2024-08'
GROUP BY p.category
ORDER BY sales DESC;
推荐图表：水平柱状图
查询 3：8月 vs 7月品类对比
SELECT
p.category,
ROUND(SUM(CASE WHEN DATE_FORMAT(o.order_date, '%Y-%m') = '2024-08' THEN o.amount ELSE 0 END), 2) as aug_sales,
ROUND(SUM(CASE WHEN DATE_FORMAT(o.order_date, '%Y-%m') = '2024-07' THEN o.amount ELSE 0 END), 2) as jul_sales,
ROUND(SUM(CASE WHEN DATE_FORMAT(o.order_date, '%Y-%m') = '2024-08' THEN o.amount ELSE 0 END) -
SUM(CASE WHEN DATE_FORMAT(o.order_date, '%Y-%m') = '2024-07' THEN o.amount ELSE 0 END), 2) as diff
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE DATE_FORMAT(o.order_date, '%Y-%m') IN (, )
p.category
diff ;
推荐图表：瀑布图/堆叠柱状图
质量指南
- 只查询相关列（不使用 SELECT *）
- 始终应用 LIMIT（默认 100）
- 使用表别名以提高清晰度
- 对于复杂查询：使用 write_todos 进行规划
- 绝不使用 DML 语句（INSERT, UPDATE, DELETE, DROP）
- SQL 执行失败时：分析错误，修正后重试（最多 2 次）
- 多条 SQL 时，每条标注用途和推荐图表类型
- 聚合查询务必检查 GROUP BY 是否完整
