ggsql 可视化技能

使用 ggsql SQL 语法，从表格数据生成图表。

概述

ggsql 基于“图形语法”（Grammar of Graphics）为 SQL 扩展了可视化能力。您只需编写熟悉的 SQL 查询，并添加可视化子句，即可直接生成图表——无需 Python 或 R 环境。

适用场景

✅ 请在以下情况下使用该技能：

• “将此数据可视化为散点图”
• “生成变量 X 的直方图”
• “绘制柱状图，比较不同类别下的 Y 值”
• “绘制时间序列数据”
• “从表格生成热力图”
• 用户提供表格数据并明确要求生成图表

不适用场景

❌ 请勿在以下情况下使用该技能：

• 需要交互式/动态图表 → 请使用 JavaScript 库
• 需执行复杂统计可视化 → 请使用 Python/R
• 构建大规模数据仪表板 → 请使用专用 BI 工具
• 需 3D 可视化 → 请使用专业三维可视化软件

输入 Schema

data: 
chart_type: point | line | bar | histogram | boxplot | violin | density | heatmap | pie
mapping:
  x: <列名>        # 大多数图表必需
  y: <列名>        # 散点图、折线图、柱状图、箱线图必需
  fill: <列名>     # 可选，用于颜色填充编码
  color: <列名>    # 可选，用于描边颜色
  shape: <列名>    # 可选，用于散点形状
  size: <列名>     # 可选，用于散点大小
options:
  title: <图表标题>              # 可选
  subtitle: <图表副标题>        # 可选
  x_label:            # 可选
  y_label:            # 可选
  binwidth: <数值>                # 直方图专用
  facet: <列名>              # 一维分面（small multiples）
  facet_by: <列名>           # 二维分面
  scale_x: continuous | discrete | binned | log10
  scale_y: continuous | discrete | binned | log10
  scale_fill: continuous | discrete | binned

输出

• SVG 图表文件（主输出）
• PNG 图表文件（可选）
• 嵌入式 base64 编码图像（适用于聊天界面显示）

图表类型与模板

散点图（point）

必需映射项：x、y
可选映射项：fill、color、shape、size

VISUALISE {x} AS x, {y} AS y, {fill} AS fill
FROM {data_source}
DRAW point
LABEL title => '{title}', x => '{x_label}', y => '{y_label}'

折线图（line）

必需映射项：x、y
可选映射项：color、linetype

VISUALISE {x} AS x, {y} AS y, {color} AS color
FROM {data_source}
DRAW line
LABEL title => '{title}', x => '{x_label}', y => '{y_label}'

柱状图（bar）

必需映射项：x、y（或仅提供 x，自动计数）
可选映射项：fill

SELECT {x}, COUNT(*) as count FROM {data_source}
GROUP BY {x}
VISUALISE {x} AS x, count AS y, {fill} AS fill
DRAW bar
LABEL title => '{title}', x => '{x_label}', y => '{y_label}'

直方图（histogram）

必需映射项：x
可选映射项：fill、binwidth

VISUALISE {x} AS x, {fill} AS fill
FROM {data_source}
DRAW histogram
  SETTING binwidth => {binwidth}
LABEL title => '{title}', x => '{x_label}'

箱线图（boxplot）

必需映射项：x（分类变量）、y（数值变量）
可选映射项：fill

VISUALISE {x} AS x, {y} AS y, {fill} AS fill
FROM {data_source}
DRAW boxplot
LABEL title => '{title}', x => '{x_label}', y => '{y_label}'

热力图（tile）

必需映射项：x、y、fill
可选映射项：无

VISUALISE {x} AS x, {y} AS y, {fill} AS fill
FROM {data_source}
DRAW tile
SCALE BINNED fill
LABEL title => '{title}', x => '{x_label}', y => '{y_label}'

密度图（density）

必需映射项：x
可选映射项：fill

VISUALISE {x} AS x, {fill} AS fill
FROM {data_source}
DRAW density
LABEL title => '{title}', x => '{x_label}'

小提琴图（violin）

必需映射项：x（分类变量）、y（数值变量）
可选映射项：fill

VISUALISE {x} AS x, {y} AS y, {fill} AS fill
FROM {data_source}
DRAW violin
LABEL title => '{title}', x => '{x_label}', y => '{y_label}'

饼图（pie，使用极坐标投影）

必需映射项：fill
可选映射项：无

SELECT {fill}, COUNT(*) as count FROM {data_source}
GROUP BY {fill}
VISUALISE {fill} AS fill, count AS y
DRAW bar
PROJECT polar
LABEL title => '{title}'

标度类型（Scale Types）

分面（Faceting，即 Small Multiples）

一维分面

VISUALISE {x} AS x, {y} AS y
FROM {data_source}
DRAW point
FACET {facet_column}

二维分面

VISUALISE {x} AS x, {y} AS y
FROM {data_source}
DRAW point
FACET {facet_column} BY {facet_by_column}

多层图表（Multi-layer Charts）

组合多个 DRAW 子句：

VISUALISE {x} AS x, {y} AS y
FROM {data_source}
DRAW line
  MAPPING {group} AS color
DRAW point
  MAPPING {group} AS fill
LABEL title => '{title}'

执行方式

方式 1：WASM Playground（推荐用于测试）

1. 访问 https://ggsql.org/wasm/
2. 使用内置数据集：ggsql:penguins、ggsql:airquality
3. 点击“Upload Data”按钮上传 CSV 文件
4. 运行 SQL 并导出为 SVG/PNG

方式 2：CLI（本地执行）

# 安装
cargo install ggsql-cli

# 运行
ggsql-cli run -f input.sql -o output.svg

方式 3：Jupyter Kernel

uv tool install ggsql-jupyter
ggsql-jupyter --install

示例

示例 1：带颜色编码的散点图

输入：

data: penguins.csv
chart_type: point
mapping:
  x: bill_length_mm
  y: bill_depth_mm
  fill: species
options:
  title: Penguin Bill Dimensions
  x_label: Bill Length (mm)
  y_label: Bill Depth (mm)

生成的 SQL：

SELECT * FROM 'penguins.csv'
VISUALISE bill_length_mm AS x, bill_depth_mm AS y, species AS fill
DRAW point
LABEL
  title => 'Penguin Bill Dimensions',
  x => 'Bill Length (mm)',
  y => 'Bill Depth (mm)'

示例 2：直方图

输入：

data: sales.csv
chart_type: histogram
mapping:
  x: revenue
options:
  title: Revenue Distribution
  binwidth: 1000

生成的 SQL：

SELECT * FROM 'sales.csv'
VISUALISE revenue AS x
DRAW histogram
  SETTING binwidth => 1000
LABEL title => 'Revenue Distribution'

示例 3：分面散点图

输入：

data: penguins.csv
chart_type: point
mapping:
  x: bill_length_mm
  y: bill_depth_mm
  fill: species
options:
  title: Penguins by Island
  facet: island

生成的 SQL：

SELECT * FROM 'penguins.csv'
VISUALISE bill_length_mm AS x, bill_depth_mm AS y, species AS fill
DRAW point
FACET island
LABEL title => 'Penguins by Island'

示例 4：多层图表

输入：

data: sales.csv
chart_type: multi
mapping:
  x: date
  y: revenue
  group: region
options:
  title: Revenue Trend by Region

生成的 SQL：

SELECT * FROM 'sales.csv'
VISUALISE date AS x, revenue AS y
DRAW line
  MAPPING region AS color
DRAW point
  MAPPING region AS fill
LABEL title => 'Revenue Trend by Region'

SQL 生成逻辑

接收到 YAML 输入后，按如下流程生成 SQL：

1. 解析 chart_type 以选择对应模板
2. 校验必需的映射字段是否已提供
3. 根据 mapping 构建 VISUALISE 子句
4. 添加对应图层类型的 DRAW 子句
5. 按需添加 SCALE、FACET、LABEL 等可选子句
6. 若 data 为 CSV 路径，则使用 FROM 'path/to/file.csv'
7. 若 data 为 SQL 表引用，则使用 FROM table_name

注意事项

• ggsql 当前处于 alpha 阶段（v0.2.7），语法可能持续演进
• WASM Playground 是最便捷的测试方式
• 无需 Python/R 运行环境
• 生成的图表为静态图像（SVG/PNG），不支持交互
• 遵循“图形语法”理念：通过图层（layers）、标度（scales）、坐标系（coordinates）等基本单元组合构建图表

资源

• 官方网站
• 语法文档
• 示例图库
• GitHub 仓库
• WASM Playground