# Ggsql

Write ggsql queries, a grammar of graphics for SQL.

- Repository: https://github.com/posit-dev/skills (551 stars)
- Category: Data and ML
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add posit-dev/skills --skill ggsql -g -a claude-code -y`
Codex: `npx skills add posit-dev/skills --skill ggsql -g -a codex -y`
Cursor: `npx skills add posit-dev/skills --skill ggsql -g -a cursor -y`
Gemini CLI: `npx skills add posit-dev/skills --skill ggsql -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add posit-dev/skills`

## Description

Write ggsql queries, a grammar of graphics for SQL. Use when the user wants to create, modify, or understand a ggsql visualization query.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# ggsql Query Writer

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.

## Query structure

Optional SQL part + required `VISUALISE`/`VISUALIZE` part.

- **SELECT → VISUALISE**: last statement is a SELECT (bare, `WITH...SELECT`, set ops); its result feeds VISUALISE, which has no `FROM`.
  ```ggsql
  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 supplies its own source (table/file/CTE/built-in), no trailing SELECT.
  ```ggsql
  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`).

## VISUALISE clause

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`.
```ggsql
VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
VISUALISE * FROM my_table
```

## DRAW clause

The rest: https://github.com/posit-dev/skills/blob/HEAD/ggsql/ggsql/SKILL.md