Query Writing

3. 获取表关系

使用 sql_db_table_relationship 获取表间外键关系，确保 JOIN 条件正确。

4. 构建查询

• SELECT - 列和聚合函数
• FROM/JOIN - 通过 FK = PK 连接表
• WHERE - 聚合前的过滤条件
• GROUP BY - 所有非聚合列
• ORDER BY - 有意义的排序
• LIMIT - 默认 100 行

5. 验证和执行

检查所有 JOIN 都有条件，GROUP BY 正确，然后运行查询。

SQL 生成规则

1. 只生成 SELECT 查询。 绝不生成 INSERT/UPDATE/DELETE/DROP/ALTER。
2. 默认附加 LIMIT 100，除非用户明确指定数量。
3. 使用正确引号（MySQL 用反引号，PostgreSQL/SQLite 用双引号，SQL Server 用方括号）。
4. 只查询相关列，不使用 SELECT *。
5. 使用表别名以提高清晰度（如 o for orders, p for products）。
6. 日期格式化： 如果存在时间字段且未指定格式：
   • datetime → yyyy-MM-dd HH:mm:ss
   • date → yyyy-MM-dd
   • year-month → yyyy-MM
7. 多表关联： 优先使用 schema 中的主键和外键。

多维度查询策略

根据用户问题复杂度，可以生成多条 SQL，分别获取不同维度的数据：

何时使用多条 SQL

多维度查询意识

根据用户问题，自动判断需要哪些维度的查询：

• 趋势分析 → 包含 ORDER BY time ASC，按时间粒度 GROUP BY
• 分类对比 → 包含 ORDER BY metric DESC，按类别 GROUP BY
• 占比分析 → 包含百分比计算（子查询或窗口函数）
• 归因分析 → 包含多维度 GROUP BY + 增量贡献
• 增长率分析 → 使用窗口函数 LAG() 计算同比/环比

每条查询的元信息

为每条 SQL 标注用途和推荐图表类型，便于后续报告生成：

查询 1：获取月度趋势数据
推荐图表：折线图/面积图
SQL: SELECT ...

查询 2：获取各品类占比
推荐图表：饼图/环形图
SQL: SELECT ...

图表类型推荐

示例：按国家统计收入

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 ('2024-07', '2024-08')
GROUP BY p.category
ORDER BY diff DESC;

推荐图表：瀑布图/堆叠柱状图

质量指南

• 只查询相关列（不使用 SELECT *）
• 始终应用 LIMIT（默认 100）
• 使用表别名以提高清晰度
• 对于复杂查询：使用 write_todos 进行规划
• 绝不使用 DML 语句（INSERT, UPDATE, DELETE, DROP）
• SQL 执行失败时：分析错误，修正后重试（最多 2 次）
• 多条 SQL 时，每条标注用途和推荐图表类型
• 聚合查询务必检查 GROUP BY 是否完整