- name
SKILL.md
技能文件保留在发布者的仓库中。
在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add posit-dev/skills --skill ggsql -a cursor -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add posit-dev/skills --skill ggsql -a claude-code -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add posit-dev/skills --skill ggsql -a codex -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add posit-dev/skills --skill ggsql -a grok -y在 Grok Bot 聊天中发送复制的消息。Bot 会从 GitHub 获取这个 SKILL.md,并添加到你所有 Bot 共享的技能中。
Install this skill: https://github.com/posit-dev/skills/tree/HEAD/ggsql/ggsql来自发布者
ggsql combines a SQL query with a Grammar-of-Graphics visualization spec in one syntax. Write queries using ONLY the syntax below — NEVER invent clauses, settings, aesthetics, layer types, or palette names; say so if unsure whether something exists.
Optional SQL part + required VISUALISE/VISUALIZE part.
WITH...SELECT, set ops); its result feeds VISUALISE, which has no 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]
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
Data sources (in VISUALISE ... FROM or DRAW ... MAPPING ... FROM): unquoted table/CTE (FROM sales), quoted file path (FROM 'data.csv'), built-in dataset (FROM ggsql:penguins, FROM ggsql:airquality).
Starts the viz; optional global mappings inherited by every layer.
VISUALISE <mapping>, ... FROM <data-source>
Mapping forms: explicit column AS aesthetic (e.g. revenue AS y); implicit column (name = aesthetic name); wildcard * (all matching columns); constant 'red' AS fill.
VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
VISUALISE * FROM my_table
Defines a layer; multiple DRAW stack bottom→top. All subclauses optional given global mappings/data.
DRAW <layer-type>
MAPPING <mapping>, ... FROM <data-source>
REMAPPING <stat-property> AS <aesthetic>, ...
SETTING <param> => <value>, ...
FILTER <condition>
PARTITION BY <column>, ...
ORDER BY <column>, ...
FROM. null blocks inheriting a global mapping: MAPPING null AS color.histogram, density, boxplot, violin, smooth, bar w/o y): maps a computed stat to an aesthetic, e.g. REMAPPING density AS y instead of a layer's default stat.SETTING size => 5, stroke => 'red'. Position adjustment: 'identity' (default, most layers), 'stack' (default bar/histogram/area), 'dodge' (default boxplot/violin), 'jitter'.FILTER sex = 'female' AND body_mass > 4000.PARTITION BY Month.path: ORDER BY timestamp.Collapses each group (PARTITION BY cols + discrete mappings) to one row, replacing numeric mappings with aggregated values. Layers: point line path bar area ribbon range segment rule text tile (not stat layers, which have their own).
SETTING aggregate => '<spec>' -- single
SETTING aggregate => ('<spec>', '<spec>', …) -- list
Spec is untargeted '<func>' (every unmapped-target numeric aesthetic; ≤2 untargeted defaults — 1st for lower-side aesthetics x/xmin/etc + all non-range layers, 2nd for upper-side xend/xmax) or targeted '<aes>:<func>' (overrides untargeted for that aesthetic).
Functions — reductions: count sum prod min max range mid mean median geomean harmean rms sdev var iqr se p05–p95; positional (need upstream ORDER BY): first last diff; band <offset>±[<mult>]<expansion> e.g. 'mean+1.96sdev' (offsets: mean median geomean harmean rms sum prod min max mid p05–p95; expansions: sdev se var iqr range).
Explosion: targeting one aesthetic with multiple functions emits one row/function/group, tagged by a synthetic aggregate column — drive another aesthetic via REMAPPING aggregate AS <aes>. Equal-length exploded aesthetics run in lockstep; single-function targets repeat each row. Mixed lengths >1 error.
-- 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 interaction: for a targeted aesthetic, SCALE BINNED runs after aggregation (so stats aren't cancelled within a bin); untargeted SCALE BINNED still bins pre-aggregate to drive grouping. Continuous censoring (SCALE <aes> FROM (lo, hi)) and discrete OOB filtering defer to post-aggregate whenever that aesthetic is aggregated.
Annotation layer, literal values only, no data mapping; tuples for multiple annotations.
PLACE point SETTING x => 5, y => 10, color => 'red'
PLACE text SETTING x => (34, 44), y => (66, 49), label => ('Mean = 34', 'Mean = 44')
Maps data → aesthetic output; sensible defaults always apply. Only aesthetic is required.
SCALE <type> <aesthetic> FROM <input-range> TO <output-range> VIA <transform>
SETTING <param> => <value>, ...
RENAMING <value> => <label>, ...
CONTINUOUS, DISCRETE, BINNED (bin continuous→discrete, never auto), ORDINAL (never auto), IDENTITY (pass through, no legend).x y fill stroke color(=fill+stroke) opacity size linewidth linetype shape panel row column. Position families (xmin/xmax/xend/ymin/ymax/yend) scale via base name (SCALE x ...).(min, max), null infers ((0, null)); discrete ('A','B','C') sets order & nulls the rest, or include null explicitly.('red','blue'), (1, 6)) or named palette (viridis, dark2, tableau10).linear log log2 ln exp10 exp2 exp sqrt square asinh pseudo_log pseudo_log2 pseudo_ln integer; temporal (auto for date/datetime/time cols): date datetime time; discrete: string bool.expand (factor or (mult,add), default 0.05, x/y only), oob ('keep' default x/y, 'censor' default others, 'squish'), breaks (count/array/interval string e.g. '2 months'), pretty (bool, default true), reverse (bool). Continuous only: minor_breaks (count/array/interval string; ignored by Vega-Lite). Binned only: closed ('left'/'right'). Discrete/ordinal: reverse.RENAMING 'Adelie' => 'Pygoscelis adeliae', 'adelie' => null or RENAMING * => '{:Title}' (formatters: Title UPPER lower, time %B %Y, num %.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
Small multiples. 1D FACET region (wrap, aesthetic panel); 2D FACET region BY category (grid, aesthetics row/column). Settings: free (null default/fixed, 'x', 'y', ('x','y')), missing ('repeat' default / 'null'), ncol/nrow (1D only, pick one). Customize/filter via SCALE on the facet aesthetic:
FACET region
SCALE panel RENAMING 'N' => 'North', 'S' => 'South'
FACET island
SCALE panel FROM ('Biscoe', 'Dream') -- filters panels shown
Coordinate system.
PROJECT <aesthetic>, ... TO <coord-type> SETTING <param> => <value>, ...
cartesian (default): aesthetics x/y; settings clip (bool, default true), ratio (number or null). polar: aesthetics radius(primary)/angle(secondary); settings clip, start/end (degrees, default 0/start+360), inner (0-1 donut hole, default 0). Swap order to flip axes (PROJECT y, x TO cartesian); without PROJECT, type is inferred from mappings.
PROJECT TO polar SETTING inner => 0.5 -- donut chart
Overrides axis/legend labels & titles: title, subtitle, caption, or any aesthetic name; null suppresses.
LABEL title => 'Sales by Region', x => 'Date', y => 'Revenue (USD)', fill => null
position, orientation ('aligned'/'transposed').count, proportion; property weight; settings position (default 'stack'), width. Orientation from mapping (x=vertical, y=horizontal).count, density (default remap count AS <secondary>); settings position ('stack'), bins (30), binwidth, closed.density, intensity; settings position ('identity'), bandwidth, adjust (1), kernel ('gaussian' default, epanechnikov triangular rectangular biweight cosine).type, value; settings position ('dodge'), outliers (true), coef (1.5), width (0.9), hinge (points, default null/hidden).density, intensity (default remap density AS offset); settings position ('dodge'), bandwidth, adjust, kernel, width (0.9), side ('both' 'left' 'bottom' 'right' 'top'), tails (default 3).intensity; settings method ('nw' default, 'ols', 'tls'), bandwidth, adjust, kernel (nw only).All layers accept colour/stroke, fill, opacity, linewidth, linetype, and position where applicable.
ggsql10(default) tableau10 category10 set1 set2 set3 dark2 paired pastel1 pastel2 accent kelly22sequential(default) 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
ggsql subcommands: exec <QUERY>, run <FILE>, validate <QUERY>, parse <QUERY>, view <QUERY> (window, blocks until closed). Options: --reader <URI> (default duckdb://memory), --writer <FORMAT> (default vegalite), --output <PATH> (extension picks writer), -D key=value, -v. Writers: vegalite svg pdf hep (no GPU) and png jpeg tiff webp (GPU, not every build).
Don't run ggsql view unless a window was requested — it blocks and you can't close it; use --output instead. Prefer svg/pdf for pictures (no GPU adapter needed); ggsql exec --help lists available writers.
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 — latest syntax docs.
ggsql:penguins/ggsql:airquality when no data is specified.ggsql validate "<query>" to validate, ggsql exec "<query>" -v to run and show output.Write ggsql queries — a grammar of graphics for SQL. Use when the user wants to create, modify, or understand a ggsql visualization query.
---name: ggsqldescription: Write ggsql queries — a grammar of graphics for SQL. Use when the user wants to create, modify, or understand…---# ggsql/ggsql/SKILL.md常见问题
从发布者处下载 ggsql/ggsql/SKILL.md,或复制路径后打开仓库。PlugMCP 只收录该技能,不托管文件。
发布者将它存放在 https://github.com/posit-dev/skills。
Claude、Cursor、Codex 和 Grok Build 可以读取你从发布者仓库添加的 SKILL.md。在聊天中发送技能的 GitHub 文件夹链接,Grok Bot 就会安装它。
position'stack'orientationtotalcenterrange instead when one coord is shared between start/end.slope (diagonal: y = a + slope*x).offset (number or (h,v)), format (RENAMING-style interpolation), parse (bool, default true: markdown **bold**/*italic*/~~strike~~/`code`/{.red span}; not in Vega-Lite), hjust ('left' 'right' 'centre' or 0-1), vjust ('top' 'bottom' 'middle' or 0-1).hinge (points, default 10, null hides).