ggsql

ggsql 查询编写器

ggsql 使用一种语法，将 SQL 查询与 Grammar-of-Graphics 可视化规范结合在一起。编写查询时只能使用以下语法——绝不要自行编造子句、设置、美学映射、图层类型或调色板名称；如果不确定某项是否存在，请说明。

查询结构

可选的 SQL 部分 + 必需的 VISUALISE/VISUALIZE 部分。

• SELECT → VISUALISE：最后一条语句是 SELECT（裸 SELECT、WITH...SELECT、集合运算）；其结果传入 VISUALISE，后者不带 FROM。

  SELECT name, score_a, score_b FROM 'dataset.csv' WHERE value > 50
  VISUALISE score_a AS x, score_b AS y
  [DRAW / PLACE / SCALE / FACET / PROJECT / LABEL clauses]
  

• VISUALISE FROM：VISUALISE 指定自己的数据源（表/文件/CTE/内置数据集），后面不跟 SELECT。

  WITH summary AS (SELECT category, COUNT(*) AS n FROM 'dataset.csv' GROUP BY category)
  VISUALISE category AS x, n AS y FROM summary
  DRAW bar
  

数据源（位于 VISUALISE ... FROM 或 DRAW ... MAPPING ... FROM 中）：不加引号的表/CTE（FROM sales）、带引号的文件路径（FROM 'data.csv'）、内置数据集（FROM ggsql:penguins、FROM ggsql:airquality）。

VISUALISE 子句

启动可视化；可选的全局映射会由每个图层继承。

VISUALISE <mapping>, ... FROM <data-source>

映射形式：显式的 column AS aesthetic（例如 revenue AS y）；隐式的 column（名称 = 美学映射名称）；通配符 *（所有匹配列）；常量 'red' AS fill。

VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
VISUALISE * FROM my_table

DRAW 子句

定义一个图层；多个 DRAW 按从下到上的顺序叠加。给定全局映射/数据后，所有子句均为可选。

DRAW <layer-type>
  MAPPING <mapping>, ... FROM <data-source>
  REMAPPING <stat-property> AS <aesthetic>, ...
  SETTING <param> => <value>, ...
  FILTER <condition>
  PARTITION BY <column>, ...
  ORDER BY <column>, ...

• MAPPING — 与 VISUALISE 使用相同的形式；与全局映射合并（图层映射优先于全局映射），也可指定自己的 FROM。null 可阻止继承全局映射：MAPPING null AS color。
• REMAPPING — 用于统计图层（histogram、density、boxplot、violin、smooth、不带 y 的 bar）：将计算出的统计量映射到某个美学映射，例如，使用 REMAPPING density AS y，而不是图层的默认统计量。
• SETTING — 字面美学值或图层参数（绕过标度），例如 SETTING size => 5, stroke => 'red'。位置调整：'identity'（默认，适用于大多数图层）、'stack'（bar/histogram/area 的默认值）、'dodge'（boxplot/violin 的默认值）、'jitter'。
• FILTER — 图层数据的 SQL WHERE 条件：FILTER sex = 'female' AND body_mass > 4000。
• PARTITION BY — 除离散映射外的额外分组列：PARTITION BY Month。
• ORDER BY — 记录顺序，对 path 有影响：ORDER BY timestamp。

Aggregate（作为 SETTING）

将每个分组（PARTITION BY 列 + 离散映射）折叠为一行，并将数值映射替换为聚合值。适用图层：point line path bar area ribbon range segment rule text tile（不包括统计图层，统计图层有自己的聚合方式）。

SETTING aggregate => '<spec>'                -- single
SETTING aggregate => ('<spec>', '<spec>', …) -- list

规范可以是非定向 '<func>'（应用于每个未映射目标的数值美学映射；最多 2 个非定向默认值——第 1 个用于较低侧美学映射 x/xmin 等，以及所有非 range 图层；第 2 个用于较高侧 xend/xmax）或定向 '<aes>:<func>'（覆盖该美学映射的非定向设置）。

函数——归约：count sum prod min max range mid mean median geomean harmean rms sdev var iqr se p05–p95；位置函数（需要上游 ORDER BY）：first last diff；区间 <offset>±[<mult>]<expansion>，例如 'mean+1.96sdev'（偏移量：mean median geomean harmean rms sum prod min max mid p05–p95；扩展量：sdev se var iqr range）。

展开：为一个美学映射指定多个函数时，每个函数/分组会输出一行，并由合成的 aggregate 列标记——通过 REMAPPING aggregate AS <aes> 驱动另一个美学映射。长度相同的展开美学映射会同步运行；单函数目标会重复每一行。混合长度大于 1 时会报错。

-- min/max envelope as two lines per group, coloured by function
DRAW line MAPPING Date AS x, Temp AS y
  REMAPPING aggregate AS color
  SETTING aggregate => ('y:min', 'y:max')
  PARTITION BY Year

与标度的交互：对于定向美学映射，SCALE BINNED 在聚合后运行（因此统计量不会在箱内相互抵消）；非定向 SCALE BINNED 仍会在聚合前分箱，以驱动分组。连续值截断（SCALE <aes> FROM (lo, hi)）和离散越界过滤，只要涉及的美学映射已聚合，就会延后到聚合后执行。

PLACE 子句

注释图层，仅使用字面值，不支持数据映射；多个注释使用元组。

PLACE point SETTING x => 5, y => 10, color => 'red'
PLACE text SETTING x => (34, 44), y => (66, 49), label => ('Mean = 34', 'Mean = 44')

SCALE 子句

将数据映射为美学属性输出；始终应用合理的默认值。仅 aesthetic 为必填项。

SCALE <type> <aesthetic> FROM <input-range> TO <output-range> VIA <transform>
  SETTING <param> => <value>, ...
  RENAMING <value> => <label>, ...

• Type（位于 aesthetic 之前；省略时自动推断）：CONTINUOUS、DISCRETE、BINNED（将连续型分箱为离散型，绝不自动执行）、ORDINAL（绝不自动执行）、IDENTITY（直接传递，不显示图例）。
• Aesthetic — 仅限基本名称：x y fill stroke color(=fill+stroke) opacity size linewidth linetype shape panel row column。位置系列（xmin/xmax/xend/ymin/ymax/yend）通过基本名称进行缩放（SCALE x ...）。
• FROM — 连续型使用 (min, max)，null 表示推断（(0, null)）；离散型使用 ('A','B','C') 设置顺序，并将其余值视为 null；也可显式包含 null。
• TO — 值数组（('red','blue')、(1, 6)）或命名调色板（viridis、dark2、tableau10）。
• VIA — 连续型：linear log log2 ln exp10 exp2 sqrt square asinh pseudo_log pseudo_log2 pseudo_ln integer；时间型（日期/日期时间/时间列时自动启用）：date datetime time；离散型：string bool。
• SETTING — 连续型/分箱型：expand（因子或 (mult,add)，默认为 0.05，仅适用于 x/y）、oob（x/y 默认为 'keep'，其他默认 'censor'，也可设为 'squish'）、breaks（数量/数组/间隔字符串，例如 '2 months'）、pretty（布尔值，默认为 true）、reverse（布尔值）。仅连续型：minor_breaks（数量/数组/间隔字符串；Vega-Lite 会忽略此项）。仅分箱型：closed（'left'/'right'）。离散型/有序型：reverse。
• RENAMING — 直接格式化和通配符格式化（直接格式化优先）：RENAMING 'Adelie' => 'Pygoscelis adeliae', 'adelie' => null 或 RENAMING * => '{:Title}'（格式化器：Title UPPER lower、时间 %B %Y、数字 %.1f）。

SCALE x VIA date SETTING breaks => '2 months'
SCALE y FROM (0, 100) SETTING oob => 'squish'
SCALE BINNED x SETTING breaks => 10, pretty => false

FACET 子句

小型多图。1D：FACET region（换行排列，美学属性为 panel）；2D：FACET region BY category（网格排列，美学属性为 row/column）。设置：free（默认为 null/固定，也可设为 'x'、'y'、('x','y')）、missing（默认为 'repeat'，也可设为 'null'）、ncol/nrow（仅适用于 1D，二选一）。通过对分面美学属性使用 SCALE 进行自定义/筛选：

FACET region
SCALE panel RENAMING 'N' => 'North', 'S' => 'South'
FACET island
SCALE panel FROM ('Biscoe', 'Dream')   -- filters panels shown

PROJECT 子句

坐标系。

PROJECT <aesthetic>, ... TO <coord-type> SETTING <param> => <value>, ...

cartesian（默认）：美学属性为 x/y；设置 clip（布尔值，默认为 true）、ratio（数字或 null）。polar：美学属性为 radius（主要）/angle（次要）；设置 clip、start/end（角度，默认为 0/start+360）、inner（0-1 的环形图内孔比例，默认为 0）。交换顺序可翻转坐标轴（PROJECT y, x TO cartesian）；不使用 PROJECT 时，根据映射推断类型。

PROJECT TO polar SETTING inner => 0.5   -- donut chart

LABEL 子句

覆盖坐标轴/图例标签和标题：title、subtitle、caption 或任意美学属性名称；设为 null 可隐藏。

LABEL title => 'Sales by Region', x => 'Date', y => 'Revenue (USD)', fill => null

---

图层类型

• point — 必需：x、y；可选：size、colour、stroke、fill、opacity、shape。
• line — 必需：x、y；按主轴排序；可选：colour/stroke、opacity、linewidth、linetype；设置项 position、orientation（'aligned'/'transposed'）。
• path — 类似 line，但按数据顺序绘制（不排序）；美学属性相同。
• bar — 如果没有 y，则自动计数；可选：x、y、fill、colour、stroke；统计量：count、proportion；属性：weight；设置项：position（默认 'stack'）、width。方向由映射决定（x=垂直，y=水平）。
• histogram — 必需：x；统计量：count、density（默认重映射 count AS <secondary>）；设置项：position（'stack'）、bins（30）、binwidth、closed。
• density — 必需：x；统计量：density、intensity；设置项：position（'identity'）、bandwidth、adjust（1）、kernel（默认 'gaussian'，可选 epanechnikov triangular rectangular biweight cosine）。
• boxplot — 必需：x（分类）、y（连续）；统计量：type、value；设置项：position（'dodge'）、outliers（true）、coef（1.5）、width（0.9）、hinge（点，默认 null/隐藏）。
• violin — 必需：x（分类）、y（连续）；统计量：density、intensity（默认重映射 density AS offset）；设置项：position（'dodge'）、bandwidth、adjust、kernel、width（0.9）、side（'both' 'left' 'bottom' 'right' 'top'）、tails（默认 3）。
• smooth — 必需：x、y；统计量：intensity；设置项：method（默认 'nw'，可选 'ols'、'tls'）、bandwidth、adjust、kernel（仅适用于 nw）。
• area — 必需：x、y；锚定于零；设置项：position（'stack'）、orientation、total（标准化）、center（河流图）。
• ribbon — 类似 area，但显式指定 ymin/ymax，不锚定。
• segment — 必需：x、y、xend、yend；如果起点和终点共用一个坐标，请改用 range。
• rule — 必需：x 或 y（全图面参考线）；可选：slope（对角线：y = a + slope*x）。
• text — 必需：x、y、label；设置项：offset（数字或 (h,v)）、format（RENAMING 风格插值）、parse（布尔值，默认 true：markdown **bold**/*italic*/~~strike~~/`code`/{.red span}；Vega-Lite 不支持）、hjust（'left' 'right' 'centre' 或 0-1）、vjust（'top' 'bottom' 'middle' 或 0-1）。
• rect — 每个轴从 center/min/max/width/height 中选择 2 项，或仅指定 center（尺寸默认设为 1）。
• polygon — 必需：x、y；坐标有序；PARTITION BY 用于区分不同多边形。
• range — 必需：x、ymin、ymax；设置项 hinge（点，默认 10，设为 null 可隐藏）。

所有图层都支持 colour/stroke、fill、opacity、linewidth、linetype，以及适用情况下的 position。

命名颜色调色板

• 离散：ggsql10（默认）tableau10 category10 set1 set2 set3 dark2 paired pastel1 pastel2 accent kelly22
• 连续：sequential（默认）viridis plasma magma inferno cividis blues greens oranges reds purples greys ylgnbu ylorbr ylorrd batlow hawaii lajolla turku …
• 发散：vik/diverging rdbu rdylbu rdylgn spectral brbg prgn piyg puor berlin roma …
• 循环：romao/cyclic bamo broco corko viko

常见模式

-- Pie chart: bar layer in polar coords
VISUALISE species AS fill FROM ggsql:penguins
DRAW bar
PROJECT TO polar

-- Multi-series line chart
VISUALISE Date AS x
DRAW line MAPPING Temp AS y, 'Temperature' AS color
DRAW line MAPPING Ozone AS y, 'Ozone' AS color
SCALE x VIA date

-- Lollipop chart
SELECT ROUND(bill_dep) AS bill_dep, COUNT(*) AS n FROM ggsql:penguins GROUP BY 1
VISUALISE bill_dep AS x
DRAW range MAPPING 0 AS ymin, n AS ymax SETTING hinge => null
DRAW point MAPPING n AS y

-- Ridgeline / joy plot
VISUALISE Temp AS x, Month AS y FROM ggsql:airquality
DRAW violin SETTING width => 4, side => 'top'
SCALE ORDINAL y

-- Mean ± 1.96·sdev band per group, as a ribbon
VISUALISE Day AS x, Temp AS ymin, Temp AS ymax FROM ggsql:airquality
DRAW ribbon SETTING aggregate => ('mean-1.96sdev', 'mean+1.96sdev') PARTITION BY Month

CLI

ggsql 子命令：exec <QUERY>、run <FILE>、validate <QUERY>、parse <QUERY>、view <QUERY>（窗口模式，关闭前会一直阻塞）。选项：--reader <URI>（默认 duckdb://memory）、--writer <FORMAT>（默认 vegalite）、--output <PATH>（根据扩展名选择 writer）、-D key=value、-v。Writer：vegalite svg pdf hep（不需要 GPU）和 png jpeg tiff webp（需要 GPU，并非每个构建都支持）。

除非明确要求打开窗口，否则不要运行 ggsql view——它会阻塞，而且你无法关闭窗口；请改用 --output。图片优先使用 svg/pdf（不需要 GPU 适配器）；ggsql exec --help 会列出可用的 writer。

ggsql exec "VISUALISE bill_len AS x, bill_dep AS y FROM ggsql:penguins DRAW point" -v
ggsql exec "VISUALISE species AS fill FROM ggsql:penguins DRAW bar" -o chart.svg

参考

https://ggsql.org/syntax/index.llms.md — 最新语法文档。

回复说明

1. 为请求编写完整、有效的 ggsql 查询；在 VISUALISE 前使用 SQL/CTE 处理数据。
2. 选择可行的最简单图层类型和设置；在需要时添加 SCALE 来设置格式、调色板或范围，并添加 LABEL 设置标题。
3. 在查询后简要说明选择理由。切勿编造语法；不确定时请如实说明。
4. 未指定数据时，默认使用 ggsql:penguins/ggsql:airquality。
5. 使用 ggsql validate "<query>" 验证，使用 ggsql exec "<query>" -v 运行并显示输出。