A SQL extension for declarative data visualization based on the Grammar of Graphics. Queries combine SQL data retrieval with a visualization spec in one composable syntax:
SELECT date, revenue, region FROM sales WHERE year = 2024
VISUALISE date AS x, revenue AS y, region AS color
DRAW line
LABEL title => 'Sales by Region'
The user-facing site is at https://ggsql.org. The README at README.md is the public introduction.
Anything about ggsql syntax or semantics belongs in doc/, not in any AGENTS.md file. That includes clause behaviour (VISUALISE, DRAW, PLACE, SCALE, FACET, PROJECT, LABEL), layer types, scales, aesthetics, and coordinate systems. AGENTS.md files describe the implementation around those features — they should link to doc/syntax/ rather than restate.
Writing ggsql queries: when you need to author or modify a ggsql query, use the vendored skill at doc/vendor/SKILL.md. It is the source of truth for the syntax Claude should produce; do not invent clauses, settings, aesthetics, or layer types beyond what it documents.
| Folder | Role | Type | Per-folder AGENTS.md |
|---|---|---|---|
src/ |
Core Rust library (crate ggsql) |
Cargo workspace member | src/AGENTS.md |
ggsql-cli/ |
ggsql command-line binary |
Cargo workspace member | ggsql-cli/AGENTS.md |
tree-sitter-ggsql/ |
Tree-sitter grammar + multi-language bindings | Cargo workspace member (also npm + PyPI) | tree-sitter-ggsql/AGENTS.md |
ggsql-jupyter/ |
Jupyter kernel | Cargo workspace member (also PyPI via maturin) | ggsql-jupyter/AGENTS.md |
ggsql-wasm/ |
WebAssembly bindings + browser playground | Cargo workspace member | ggsql-wasm/AGENTS.md |
ggsql-vscode/ |
VS Code / Positron extension | Standalone TypeScript / npm | ggsql-vscode/AGENTS.md |
doc/ |
Quarto documentation site (ggsql.org) | Quarto project | doc/AGENTS.md |
The Cargo workspace (/Cargo.toml) has five members: tree-sitter-ggsql, src, ggsql-cli, ggsql-jupyter, ggsql-wasm. Default workspace members exclude ggsql-wasm (it needs the wasm32 target and is built separately).
ggsql query ──► parser ──► Plot AST ──► executor ──► Spec ──► writer ──► output
(tree-sitter) (Reader runs SQL, (Vega-Lite JSON
applies stats, or PNG)
resolves scales)
- The parser splits the query at the
VISUALISEboundary. SQL goes to a pluggableReader(DuckDB, SQLite, ODBC); the VISUALISE part becomes a typedPlot. - The executor ties the two together: SQL → DataFrame, AST resolved against actual schema, stats and scales applied per layer.
- The writer renders the resolved
Specto an output format: Vega-Lite JSON (the default writer), SVG, PDF or a.hepplot document (all default features), or one of the four raster formats — PNG, JPEG, TIFF, WebP (non-default; they need a GPU adapter). Everything but Vega-Lite is implemented on top of the hephaestus renderer — a name that stays internal; users see the format names.
For details — module layout, traits, where extension points live — see src/AGENTS.md. For a specific renderer, src/writer/vegalite/AGENTS.md (Vega-Lite) or src/writer/hephaestus/AGENTS.md (the other seven). For the AST types, src/plot/AGENTS.md.
Prerequisite: tree-sitter-cli. Any Rust build regenerates the parser from grammar.js via tree-sitter-ggsql's build script, which runs tree-sitter generate and fails if tree-sitter-cli is not on PATH. Install it once with npm install -g tree-sitter-cli. To build against a pre-generated tree-sitter-ggsql/src/parser.c without the CLI (e.g. if you're not touching the grammar), set GGSQL_SKIP_GENERATE=1.
# Rust workspace (default members: tree-sitter-ggsql, src, ggsql-cli, ggsql-jupyter)
cargo build --workspace
cargo build --release --workspace
# Just the library
cargo build --package ggsql
# Just the CLI binary
cargo build --package ggsql-cli
# Wasm build (separate, not in default workspace members)
cd ggsql-wasm && ./build-wasm.sh
# VS Code extension
cd ggsql-vscode && npm install && npm run package
# Tree-sitter parser (regenerate after editing grammar.js)
cd tree-sitter-ggsql && npx tree-sitter generateThe MSRV is Rust 1.86, declared as rust-version in /Cargo.toml. This is the maximum Rust version CRAN ships, and the R package's vendored copy of ggsql has to build against it — only bump it when CRAN does. rust-version also points clippy's MSRV-aware lints at 1.86, so an accidental 1.87+ std API is flagged as a lint rather than surfacing as a cryptic E0658 at vendoring time. Keeping that guard is the main reason not to raise the declaration to match a dependency's.
parley declares 1.88 while compiling fine on 1.86. It is non-optional for the default svg/pdf/hep writers, so cargo's floor check refuses on 1.86 until --ignore-rust-version bypasses the declaration. That flag is not papering over a real incompatibility — the library genuinely compiles, which CI proves:
# The CRAN-toolchain claim, checked rather than asserted. Library only:
# --all-targets pulls the `adbc` dev-dependency path, and datafusion uses
# let-chains, so 1.86 fails there for real.
cargo +1.86 check --ignore-rust-version -p ggsqlThere is deliberately no root rust-toolchain.toml: pinning to 1.86 would force local cargo test and rust-analyzer onto the oldest supported toolchain. CI's default toolchain is stable — which still guards the MSRV, because clippy reads rust-version, not the toolchain — with the 1.86 check as its own step.
One thing is exempt from the 1.86 MSRV:
- The wasm bindings (
ggsql-wasm). R doesn't use wasm, and some wasm-only dependencies require a newer rustc, so the crate has norust-versionand a nestedggsql-wasm/rust-toolchain.tomlselects stable for builds run from that directory (./build-wasm.sh, Cargo, orpkg/).
svg, pdf and hep are default features and need no GPU adapter, no wgpu and — importantly — no libfontconfig1-dev: src/Cargo.toml names fontique directly to enable fontconfig-dlopen, so fontconfig is loaded at run time rather than linked at build time. That is what makes them safe to have on by default; see src/writer/hephaestus/AGENTS.md. The four raster writers (png, jpeg, tiff, webp) and ggsql view are not default and need an adapter at run time.
Cross-platform installers (NSIS / MSI / DMG / Deb): see INSTALLERS.md. Releases are tag-driven via .github/workflows/.
# Whole Rust workspace
cargo test --workspace
# A single crate
cargo test --package ggsql
cargo test --package ggsql-jupyter
# Tree-sitter corpus
cd tree-sitter-ggsql && npm test
# Jupyter kernel protocol tests (Python)
cd ggsql-jupyter/tests && pip install -r requirements.txt && pytestPer-folder AGENTS.md files cover component-specific test guidance.
- Reuse existing infrastructure and architectural choices. When adding new code, prefer extending or adapting what is already there over introducing a parallel implementation. If reuse requires changes elsewhere to accommodate the new caller, that is more palatable than implementing the same thing twice.
- Comments describe the current state of the code. Do not reference past states, how something used to work, what was changed, or why an earlier approach was abandoned — that history belongs in commit messages and
CHANGELOG.md. CHANGELOG.mdis the record of user-visible change over time. Consult it when you need to know when something landed or how behaviour evolved. Update it when adding a feature, changing behaviour, or removing something — but write one entry per feature, added when the feature is complete. Don't gradually accrete bullets during development.- Always run
cargo fmtand resolve allcargo clippywarnings at the end of any task that involves writing code. Do this before considering the task complete.
- What does clause/layer/scale X do? →
doc/syntax/. - How does the
ggsqlCLI work? Where do its subcommands live? →ggsql-cli/AGENTS.md. - How does the parser work? How is a
Plotbuilt? →src/AGENTS.md, thensrc/parser/. - How do I add a new geom / scale type / coord? →
src/plot/AGENTS.md. - How does Vega-Lite output get assembled? →
src/writer/vegalite/AGENTS.md. - How do the raster, SVG, PDF and
.hepwriters work? →src/writer/hephaestus/AGENTS.md, which also lists their known gaps. - How does
ggsql viewshow a plot in a window? →ggsql-cli/AGENTS.md, thenPlotViewerinsrc/writer/hephaestus/window.rs. - How does a query become rendered output end-to-end? →
src/AGENTS.md(execution pipeline), thensrc/execute/. - How does the Jupyter kernel route messages? →
ggsql-jupyter/AGENTS.md. - How does the VS Code / Positron extension talk to the kernel? →
ggsql-vscode/AGENTS.md. - How is the wasm playground built and embedded into the docs? →
ggsql-wasm/AGENTS.mdanddoc/AGENTS.md. - How do I add new ggsql syntax? → grammar in
tree-sitter-ggsql/AGENTS.md, then AST building insrc/parser/builder.rs(covered insrc/AGENTS.md), then docs indoc/AGENTS.md.