ggsql 可视化查询编写：在 SQL 中嵌入图形语法时使用

当用户要创建、修改或理解 ggsql 可视化查询时，用 SQL + VISUALISE 语法编写、验证并运行查询。

适用场景

解决思路

1. 只使用本文列出的语法；绝不要发明子句、设置、aesthetic、图层类型或调色板名称；不确定是否存在就直说。
2. 查询结构：可选 SQL 部分 + 必需的 VISUALISE/VISUALIZE 部分。
3. SELECT → VISUALISE：最后一条语句是 SELECT（裸 SELECT、WITH...SELECT、集合操作）；其结果输入 VISUALISE，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 子句]。
4. 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。
5. 数据源：在 VISUALISE ... FROM 或 DRAW ... MAPPING ... FROM 中，可写不带引号的表/CTE（FROM sales）、带引号的文件路径（FROM 'data.csv'）、内置数据集（FROM ggsql:penguins、FROM ggsql:airquality）。
6. VISUALISE 子句：启动可视化；可选全局 mapping 会被每个图层继承。写法：VISUALISE <mapping>, ... FROM <data-source>。
7. Mapping 形式：显式 column AS aesthetic（如 revenue AS y）；隐式 column（列名=aesthetic 名）；通配符 *（所有匹配列）；常量 'red' AS fill。
8. DRAW 子句：定义一个图层；多个 DRAW 从下往上堆叠。所有子子句在已有全局 mapping/数据时都可选。写法：DRAW <layer-type> MAPPING <mapping>, ... FROM <data-source> REMAPPING <stat-property> AS <aesthetic>, ... SETTING <param> => <value>, ... FILTER <condition> PARTITION BY <column>, ... ORDER BY <column>, ...。
9. DRAW 的 MAPPING：形式同 VISUALISE；与全局 mapping 合并（图层优先），可加自己的 FROM；null 阻止继承全局 mapping：MAPPING null AS color。
10. DRAW 的 REMAPPING：用于 stat 图层（histogram、density、boxplot、violin、smooth、无 y 的 bar）；把计算出的统计量映射到 aesthetic，如 REMAPPING density AS y，而不是用图层默认统计量。
11. DRAW 的 SETTING：字面量 aesthetic 值或图层参数（绕过 scales），如 SETTING size => 5, stroke => 'red'。位置调整：'identity'（默认，大多数图层）、'stack'（默认 bar/histogram/area）、'dodge'（默认 boxplot/violin）、'jitter'。
12. DRAW 的 FILTER：对图层数据使用 SQL WHERE 条件：FILTER sex = 'female' AND body_mass > 4000。
13. DRAW 的 PARTITION BY：在离散 mapping 之外增加分组列：PARTITION BY Month。
14. DRAW 的 ORDER BY：记录顺序，对 path 很重要：ORDER BY timestamp。
15. Aggregate（一种 SETTING）：把每个组（PARTITION BY 列 + 离散 mapping）折叠为一行，用聚合值替换数值 mapping。适用图层：point line path bar area ribbon range segment rule text tile（stat 图层不适用，它们有自己的聚合）。
16. Aggregate 写法：单值 SETTING aggregate => '<spec>'；列表 SETTING aggregate => ('<spec>', '<spec>', …)。
17. Aggregate 的 spec：未定向 '<func>'（作用于每个未映射目标的数值 aesthetic；最多 2 个未定向默认值——第 1 个用于下侧 aesthetic x/xmin 等及所有非 range 图层，第 2 个用于上侧 xend/xmax）或定向 '<aes>:<func>'（覆盖该 aesthetic 的未定向值）。
18. Aggregate 函数——归约：count sum prod min max range mid mean median geomean harmean rms sdev var iqr se p05–p95；位置函数（需要上游 ORDER BY）：first last diff；带 band：<offset>±[<mult>]<expansion>，如 'mean+1.96sdev'（offset：mean median geomean harmean rms sum prod min max mid p05–p95；expansion：sdev se var iqr range）。
19. Aggregate 的 Explosion：对一个 aesthetic 使用多个函数会按每组每函数发出一行，并用合成的 aggregate 列标记；可通过 REMAPPING aggregate AS <aes> 驱动另一个 aesthetic。等长的 exploded aesthetic 同步运行；单函数目标重复每一行。混合长度 >1 会报错。示例：DRAW line MAPPING Date AS x, Temp AS y REMAPPING aggregate AS color SETTING aggregate => ('y:min', 'y:max') PARTITION BY Year。
20. Aggregate 与 scale 交互：对定向 aesthetic，SCALE BINNED 在聚合后运行（这样统计量不会在一个 bin 内被抵消）；未定向 SCALE BINNED 仍在聚合前分箱以驱动分组。连续删截（SCALE <aes> FROM (lo, hi)）和离散 OOB 过滤，在该 aesthetic 被聚合时延后到聚合后。
21. PLACE 子句：注释图层，只用字面量值，不做数据 mapping；多个注释用元组。示例：PLACE point SETTING x => 5, y => 10, color => 'red'；PLACE text SETTING x => (34, 44), y => (66, 49), label => ('Mean = 34', 'Mean = 44')。
22. SCALE 子句：将数据映射到 aesthetic 输出；总是有合理默认值。只有 aesthetic 是必需的。写法：SCALE <type> <aesthetic> FROM <input-range> TO <output-range> VIA <transform> SETTING <param> => <value>, ... RENAMING <value> => <label>, ...。
23. SCALE 的 Type（在 aesthetic 前；可省略并推断）：CONTINUOUS、DISCRETE、BINNED（连续→离散，永不自动）、ORDINAL（永不自动）、IDENTITY（透传，无图例）。
24. SCALE 的 Aesthetic：只写基础名：x y fill stroke color(=fill+stroke) opacity size linewidth linetype shape panel row column。位置族（xmin/xmax/xend/ymin/ymax/yend）通过基础名缩放（SCALE x ...）。
25. SCALE 的 FROM：连续用 (min, max)，null 表示推断（(0, null)）；离散用 ('A','B','C') 设置顺序并让其余为 null，或显式包含 null。
26. SCALE 的 TO：值数组（('red','blue')、(1, 6)）或命名调色板（viridis、dark2、tableau10）。
27. SCALE 的 VIA：连续：linear log log2 ln exp10 exp2 exp sqrt square asinh pseudo_log pseudo_log2 pseudo_ln integer；时间（date/datetime/time 列自动）：date datetime time；离散：string bool。
28. SCALE 的 SETTING：连续/binned：expand（factor 或 (mult,add)，默认 0.05，仅 x/y）、oob（'keep' 默认 x/y，'censor' 默认其他，'squish'）、breaks（数量/数组/间隔字符串如 '2 months'）、pretty（bool，默认 true）、reverse（bool）。仅连续：minor_breaks（数量/数组/间隔字符串；Vega-Lite 忽略）。仅 binned：closed（'left'/'right'）。离散/ordinal：reverse。
29. SCALE 的 RENAMING：直接 + 通配符格式化（直接优先）：RENAMING 'Adelie' => 'Pygoscelis adeliae', 'adelie' => null 或 RENAMING * => '{:Title}'（格式化器：Title UPPER lower，时间 %B %Y，数字 %.1f）。
30. SCALE 示例：SCALE x VIA date SETTING breaks => '2 months'；SCALE y FROM (0, 100) SETTING oob => 'squish'；SCALE BINNED x SETTING breaks => 10, pretty => false。
31. FACET 子句：小多图。一维 FACET region（wrap，aesthetic panel）；二维 FACET region BY category（网格，aesthetic row/column）。设置：free（null 默认/固定、'x'、'y'、('x','y')）、missing（'repeat' 默认 / 'null'）、ncol/nrow（仅一维，二选一）。通过 SCALE 定制/过滤 facet aesthetic。
32. FACET 示例：FACET region; SCALE panel RENAMING 'N' => 'North', 'S' => 'South'；FACET island; SCALE panel FROM ('Biscoe', 'Dream') 过滤显示的 panel。
33. PROJECT 子句：坐标系。写法：PROJECT <aesthetic>, ... TO <coord-type> SETTING <param> => <value>, ...。cartesian（默认）：aesthetic x/y；设置 clip（bool，默认 true）、ratio（数字或 null）。polar：aesthetic radius（主）/angle（次）；设置 clip、start/end（角度，默认 0/start+360）、inner（0-1 甜甜圈孔，默认 0）。交换顺序可翻转轴（PROJECT y, x TO cartesian）；没有 PROJECT 时，类型由 mapping 推断。示例：PROJECT TO polar SETTING inner => 0.5。
34. LABEL 子句：覆盖轴/图例标签与标题：title、subtitle、caption 或任意 aesthetic 名；null 表示隐藏。示例：LABEL title => 'Sales by Region', x => 'Date', y => 'Revenue (USD)', fill => null。
35. 图层类型 point：必需 x、y；可选 size、colour、stroke、fill、opacity、shape。
36. 图层类型 line：必需 x、y；按主轴排序；可选 colour/stroke、opacity、linewidth、linetype；设置 position、orientation（'aligned'/'transposed'）。
37. 图层类型 path：类似 line 但按数据顺序（不排序）；相同 aesthetics。
38. 图层类型 bar：没有 y 时自动计数；可选 x、y、fill、colour、stroke；统计量 count、proportion；属性 weight；设置 position（默认 'stack'）、width。方向由 mapping 决定（x=垂直，y=水平）。
39. 图层类型 histogram：必需 x；统计量 count、density（默认 remap count AS <secondary>）；设置 position（'stack'）、bins（30）、binwidth、closed。
40. 图层类型 density：必需 x；统计量 density、intensity；设置 position（'identity'）、bandwidth、adjust（1）、kernel（'gaussian' 默认，epanechnikov triangular rectangular biweight cosine）。
41. 图层类型 boxplot：必需 x（类别）、y（连续）；统计量 type、value；设置 position（'dodge'）、outliers（true）、coef（1.5）、width（0.9）、hinge（points，默认 null/隐藏）。
42. 图层类型 violin：必需 x（类别）、y（连续）；统计量 density、intensity（默认 remap density AS offset）；设置 position（'dodge'）、bandwidth、adjust、kernel、width（0.9）、side（'both' 'left' 'bottom' 'right' 'top'）、tails（默认 3）。
43. 图层类型 smooth：必需 x、y；统计量 intensity；设置 method（'nw' 默认、'ols'、'tls'）、bandwidth、adjust、kernel（仅 nw）。
44. 图层类型 area：必需 x、y，锚定在零；设置 position（'stack'）、orientation、total（归一化）、center（steamgraph）。
45. 图层类型 ribbon：类似 area 但显式 ymin/ymax，不锚定。
46. 图层类型 segment：必需 x、y、xend、yend；当起点/终点共享一个坐标时改用 range。
47. 图层类型 rule：必需 x 或 y（整面板参考线）；可选 slope（对角线：y = a + slope*x）。
48. 图层类型 text：必需 x、y、label；设置 offset（数字或 (h,v)）、format（RENAMING 风格插值）、parse（bool，默认 true：markdown **bold**/*italic*/~~strike~~/`code`/{.red span}；Vega-Lite 不支持）、hjust（'left' 'right' 'centre' 或 0-1）、vjust（'top' 'bottom' 'middle' 或 0-1）。
49. 图层类型 rect：每个轴从 center/min/max/width/height 中选 2 个，或只给 center（默认 size 为 1）。
50. 图层类型 polygon：必需 x、y；坐标有序；PARTITION BY 分隔不同多边形。
51. 图层类型 range：必需 x、ymin、ymax；设置 hinge（points，默认 10，null 隐藏）。
52. 所有图层都接受 colour/stroke、fill、opacity、linewidth、linetype，以及在适用时的 position。
53. 命名颜色调色板——离散：ggsql10(默认) tableau10 category10 set1 set2 set3 dark2 paired pastel1 pastel2 accent kelly22。
54. 命名颜色调色板——顺序：sequential(默认) viridis plasma magma inferno cividis blues greens oranges reds purples greys ylgnbu ylorbr ylorrd batlow hawaii lajolla turku 等。
55. 命名颜色调色板——发散：vik/diverging rdbu rdylbu rdylgn spectral brbg prgn piyg puor berlin roma 等。
56. 命名颜色调色板——循环：romao/cyclic bamo broco corko viko。
57. Common pattern 饼图：bar 图层 + polar 坐标：VISUALISE species AS fill FROM ggsql:penguins DRAW bar PROJECT TO polar。
58. Common pattern 多系列折线图：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。
59. Common pattern 棒棒糖图：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。
60. Common pattern 山脊图/joy plot：VISUALISE Temp AS x, Month AS y FROM ggsql:airquality DRAW violin SETTING width => 4, side => 'top' SCALE ORDINAL y。
61. Common pattern 每组均值 ± 1.96·sdev 带状图（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。
62. 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。Writers：vegalite svg pdf hep（无 GPU）和 png jpeg tiff webp（GPU，并非所有构建都有）。
63. 不要运行 ggsql view，除非明确要求窗口——它会阻塞且你无法关闭；改用 --output。优先用 svg/pdf 输出图片（不需要 GPU adapter）；ggsql exec --help 列出可用 writers。
64. CLI 示例：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。
65. 参考：https://ggsql.org/syntax/index.llms.md 获取最新语法文档。
66. 响应说明：为用户请求编写完整、有效的 ggsql 查询；在 VISUALISE 前用 SQL/CTE 塑形数据。
67. 选择能工作的最简单图层类型/设置；在合理时添加 SCALE 做格式化/调色板/范围，添加 LABEL 做标题。
68. 查询后简要解释选择。绝不要发明语法——不确定就说。
69. 未指定数据时默认用 ggsql:penguins/ggsql:airquality。
70. 用 ggsql validate "<query>" 验证，用 ggsql exec "<query>" -v 运行并显示输出。

适用边界 · 注意事项

• 不要在没有要求窗口时运行 ggsql view，因为它会阻塞且无法关闭；应使用 --output 输出到文件。
• 不确定 ggsql 语法、子句、aesthetic、图层或调色板是否存在时，不要发明，直接说明不确定。
• 不要对 stat 图层使用 SETTING aggregate（它们有自己的聚合）；不要将混合长度 >1 的 exploded aesthetic 一起使用，否则会报错。