Ggsql

ggsql Query Writer

Write valid ggsql visualization queries from natural-language requests. ggsql combines SQL data shaping with a declarative grammar of graphics.

Use this skill when

• Creating or modifying a ggsql query.
• Converting a chart request into ggsql.
• Explaining, validating, or running ggsql.
• Choosing ggsql layers, mappings, scales, facets, projections, or labels.

Do not trigger for ordinary SQL work that has no visualization component.

Required reference

Read references/syntax.md before writing or changing a query. It is the complete upstream language reference and defines the allowed clauses, aesthetics, layers, settings, palettes, and CLI commands.

Never invent ggsql syntax. If the reference does not document a requested feature, say so and offer the closest documented form.

Workflow

1. Identify the data source, columns, desired visual encodings, grouping, and output.
2. Shape data with SQL or CTEs before VISUALISE when necessary.
3. Choose the simplest documented DRAW layer and mappings.
4. Add SCALE, FACET, PROJECT, or LABEL only when the request needs them.
5. If ggsql is available, validate with ggsql validate. Render with ggsql exec ... -v only when output is requested.
6. Return the complete query, then briefly explain consequential choices.

Minimal pattern

SELECT category, SUM(value) AS total
FROM 'data.parquet'
GROUP BY category
VISUALISE category AS x, total AS y
DRAW bar
LABEL
  title => 'Total by category',
  x => 'Category',
  y => 'Total'

Alternatively, let VISUALISE name the source:

VISUALISE bill_len AS x, bill_dep AS y, species AS color
FROM ggsql:penguins
DRAW point

Guardrails

• Use only documented clauses, settings, aesthetics, layers, transforms, and palettes.
• Preserve the user's source names and column names.
• Prefer ggsql:penguins or ggsql:airquality only when example data is needed.
• Do not claim validation or rendering unless the command actually ran.
• Keep SQL portable unless the selected backend requires a documented dialect feature.