Update hephaestus with all the power it brings by thomasp85 · Pull Request #537 · posit-dev/ggsql

thomasp85 · 2026-09-07T13:01:35Z

This PR updates the hephaestus dependency to 0.4.1 and provides all of the happiness that it brings. All the file types are supported out of the box, and we can now provide a proper kernel solution to rendering for both the plot pane and for notebooks

teunbrand

Partial review fussing over docs, will continue tomorrow

teunbrand · 2026-09-08T14:11:04Z

+          # No feature flags: `raster-plots` is default, precisely so that a
+          # plain build matches the released wheel. It adds the png/jpeg/tiff
+          # writers, which need a GPU adapter at *run* time and fall back to
+          # SVG without one, so a wheel carrying them still works on a
+          # headless machine. No before-script-linux either: ggsql enables
+          # fontique's `fontconfig-dlopen`, so nothing here needs
+          # fontconfig-devel at build time — verified in this exact image,
+          # which does not ship it.


Just flagging that this comment feels like a scar

teunbrand · 2026-09-08T14:14:10Z

+        # Stable is the default toolchain. It is *not* the MSRV: `rust-version`
+        # in /Cargo.toml is 1.86 (CRAN's), which is what points clippy's
+        # MSRV-aware lints at 1.86 — so running clippy here still guards it.
+        # The default cannot be 1.86 itself, because the default writers pull
+        # `parley`, which declares 1.88, and the `adbc` test path needs 1.88
+        # for real.


Maybe we should have a claude.md at the workflow level? I feel like this comment about MSRVs is scattered throughout workflows and it might be better to have a single place to explain how we dance to CRAN's tunes

teunbrand · 2026-09-08T14:19:15Z

+ggsql exec -o chart.pdf "VISUALISE species AS fill FROM ggsql:penguins DRAW bar"
+```
+
+`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` mean themselves. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite as before. An explicit `--writer` always wins, and if it disagrees with the extension you get the format you asked for plus a note on `stderr`.


Suggested change

`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` mean themselves. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite as before. An explicit `--writer` always wins, and if it disagrees with the extension you get the format you asked for plus a note on `stderr`.

`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` indicate file extensions. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite. An explicit `--writer` always wins, and if the writer is inconsistent with the extension, you get the format you asked for plus a note on `stderr`.

Bit unclear what 'format you asked for' means: the writer format or the extension format?

teunbrand · 2026-09-08T14:27:11Z

+
+`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` mean themselves. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite as before. An explicit `--writer` always wins, and if it disagrees with the extension you get the format you asked for plus a note on `stderr`.
+
+**A binary format needs somewhere to go.** `pdf`, `hep` and the raster formats write bytes, so running one straight to a terminal would fill it with them. `ggsql` refuses instead, saying so on `stderr` and exiting non-zero — pass `--output`, or pipe it somewhere. A query with no `VISUALISE` prints its table, and honours `--output` the same way.


The phrasing of this part is confusing to me. I'd suggest to say that ggsql doesn't render byte results of these file formats to the terminal, followed by the suggestion what to do instead.

Maybe ggsql view is also a good suggestion here if interactive user intends to view their plots directly

teunbrand · 2026-09-08T14:31:49Z

+
+#### Per-format settings
+
+Each format additionally takes whatever it actually offers:


Suggested change

Each format additionally takes whatever it actually offers:

Each format offers additional settings:

teunbrand · 2026-09-08T14:42:33Z

+
+The Vega-Lite writer takes no options: its output is resolution-independent, so size, resolution and background belong to whatever renders the spec. Passing an option a writer doesn't understand is an error rather than a setting quietly ignored — and so is a setting a writer cannot honour, reported before the query runs rather than after.
+
+Where a format cannot express something the plot asks for, `ggsql` says so on `stderr` and still writes the file. That is a defect in an artifact you are about to publish, so it is reported whether or not `--verbose` is set, and it stays out of a piped `svg`.


Suggested change

Where a format cannot express something the plot asks for, `ggsql` says so on `stderr` and still writes the file. That is a defect in an artifact you are about to publish, so it is reported whether or not `--verbose` is set, and it stays out of a piped `svg`.

When a plot asks for a graphic that cannot be expressed by a format, `ggsql` says so on `stderr` and still writes the file. This is a defect in the file you produced, so the defect is reported whether or not `--verbose` is set, and it stays out of a piped `svg`.

teunbrand · 2026-09-08T14:45:05Z

 * `title`: The main title of the plot
 * `subtitle`: An additional, often longer and more descriptive, title beneath the main title
-* `caption`: A string placed below the plot, often used to add additional information about the data source etc. Not supported by the Vega-Lite writer, which has no equivalent; the png (raster) writer renders it.
+* `caption`: A string placed below the plot, often used to add additional information about the data source etc. Not supported by the Vega-Lite writer, which has no equivalent; every other writer renders it.


Suggested change

* `caption`: A string placed below the plot, often used to add additional information about the data source etc. Not supported by the Vega-Lite writer, which has no equivalent; every other writer renders it.

* `caption`: A string placed below the plot, often used to add additional information about the data source etc. Supported by every writer except Vega-Lite, which has no equivalent.

teunbrand · 2026-09-08T14:45:56Z

-The png writer reads the strings you provide here as markdown, so `LABEL title => 'Sales in **2024**'` renders the year in bold.
-This currently applies to the plot title, subtitle and caption, and to the axis titles.
-Legend titles and break labels (axis tick labels and legend keys) are still drawn literally — the renderer has no rich-text support on those slots yet, so markdown in them shows its markers. This is a gap rather than a design choice, and they will parse once the renderer catches up.
+Every writer except Vega-Lite reads the strings you provide here as markdown, so `LABEL title => 'Sales in **2024**'` renders the year in bold.


Suggested change

Every writer except Vega-Lite reads the strings you provide here as markdown, so `LABEL title => 'Sales in **2024**'` renders the year in bold.

Every writer except Vega-Lite interprets the strings you provide here as markdown, so `LABEL title => 'Sales in **2024**'` renders the year in bold.

teunbrand · 2026-09-08T14:52:53Z

 * `{selector body}` spans, which style a fragment without a dedicated marker. The selector is a single token: a colour name or CSS colour (`{.red hot}`), a hex colour (`{#0072B2 blue}`), or a size in points (`{.20 big}`). Combine them by nesting: `{.red {.20 big and red}}`.

-Note that `parse` is only honoured by the png writer.
+Note that `parse` is not honoured by the Vega-Lite writer, which has no rich text and always draws the label literally.


Maybe instead of mentioning every time that Vega-Lite doesn't support a feature (rich text, minor axis ticks etc), we have a feature x writer table somewhere for an easy overview. Such table can also accommodate the transparent background x jpeg limitation and possibly others.

teunbrand · 2026-09-08T14:58:28Z

 ## CLI

-The `ggsql` CLI should be on the PATH. Subcommands: `exec <QUERY>`, `run <FILE>`, `validate <QUERY>`, `parse <QUERY>`. Common options: `--reader <URI>` (default `duckdb://memory`), `--writer <FORMAT>` (default `vegalite`), `--output <PATH>`, `-v` (verbose).
+The `ggsql` CLI should be on the PATH. Subcommands: `exec <QUERY>`, `run <FILE>`, `validate <QUERY>`, `parse <QUERY>`, `view <QUERY>` (native window). Common options: `--reader <URI>` (default `duckdb://memory`), `--writer <FORMAT>` (default `vegalite`), `--output <PATH>` (its extension picks the writer when `--writer` is omitted), `-D key=value` (writer settings), `-v` (verbose). Writers: `vegalite`, `svg`, `pdf`, `hep` (no GPU needed) and `png`, `jpeg`, `tiff`, `webp` (rasterise on the GPU, not in every build).


Is there a way an agent can close a ggsql view window? If so, we should probably mention that.
Also is there a way an agent can determine whether its environment supports the formats that require the GPU?

thomasp85 added 18 commits September 4, 2026 13:43

Upgrade to hephaestus 0.4.0

d7d9b90

all the writers

d2684c3

Add window mode to CLI and switch to vello hybrid

da80311

Plumbing for kernel

d059d5e

Move rendering to thread

833e21b

First part of the kernel render

21a9646

Add plot.comm

bec8041

Ensure sizing on first render

37c0cd0

Remove VegaLite from extension + bump to 0.4.1 heph

f7fbc05

docs and format sniffing

ab6767b

debugging in positron

d28a1ad

small tweaks

ede6c51

use hephaestus in wasm

af7ac57

Last set of reviews + comment pruning

682b041

Merge branch 'main' into heph-0-4-0

6ca4846

support cache argument in view

25f28d1

Fix CI

e69007f

fix CI again

f33e91c

thomasp85 marked this pull request as ready for review September 8, 2026 14:03

thomasp85 requested review from georgestagg and teunbrand September 8, 2026 14:03

teunbrand reviewed Sep 8, 2026

View reviewed changes

Navigation Menu

Uh oh!

Update hephaestus with all the power it brings - #537

Update hephaestus with all the power it brings#537
thomasp85 wants to merge 18 commits into
mainfrom
heph-0-4-0

thomasp85 commented Sep 7, 2026

Uh oh!

teunbrand left a comment

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026 •

edited

Loading

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

teunbrand Sep 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` mean themselves. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite as before. An explicit `--writer` always wins, and if it disagrees with the extension you get the format you asked for plus a note on `stderr`.
	`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` indicate file extensions. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite. An explicit `--writer` always wins, and if the writer is inconsistent with the extension, you get the format you asked for plus a note on `stderr`.


		`json` and `vl.json` mean Vega-Lite; `svg`, `pdf`, `hep`, `png`, `jpg`/`jpeg`, `tif`/`tiff` and `webp` mean themselves. An extension `ggsql` doesn't recognise, or no `--output` at all, falls back to Vega-Lite as before. An explicit `--writer` always wins, and if it disagrees with the extension you get the format you asked for plus a note on `stderr`.

		A binary format needs somewhere to go. `pdf`, `hep` and the raster formats write bytes, so running one straight to a terminal would fill it with them. `ggsql` refuses instead, saying so on `stderr` and exiting non-zero — pass `--output`, or pipe it somewhere. A query with no `VISUALISE` prints its table, and honours `--output` the same way.


		#### Per-format settings

		Each format additionally takes whatever it actually offers:

	Each format additionally takes whatever it actually offers:
	Each format offers additional settings:


		The Vega-Lite writer takes no options: its output is resolution-independent, so size, resolution and background belong to whatever renders the spec. Passing an option a writer doesn't understand is an error rather than a setting quietly ignored — and so is a setting a writer cannot honour, reported before the query runs rather than after.

		Where a format cannot express something the plot asks for, `ggsql` says so on `stderr` and still writes the file. That is a defect in an artifact you are about to publish, so it is reported whether or not `--verbose` is set, and it stays out of a piped `svg`.

	Where a format cannot express something the plot asks for, `ggsql` says so on `stderr` and still writes the file. That is a defect in an artifact you are about to publish, so it is reported whether or not `--verbose` is set, and it stays out of a piped `svg`.
	When a plot asks for a graphic that cannot be expressed by a format, `ggsql` says so on `stderr` and still writes the file. This is a defect in the file you produced, so the defect is reported whether or not `--verbose` is set, and it stays out of a piped `svg`.

	* `caption`: A string placed below the plot, often used to add additional information about the data source etc. Not supported by the Vega-Lite writer, which has no equivalent; every other writer renders it.
	* `caption`: A string placed below the plot, often used to add additional information about the data source etc. Supported by every writer except Vega-Lite, which has no equivalent.

	Every writer except Vega-Lite reads the strings you provide here as markdown, so `LABEL title => 'Sales in 2024'` renders the year in bold.
	Every writer except Vega-Lite interprets the strings you provide here as markdown, so `LABEL title => 'Sales in 2024'` renders the year in bold.

Uh oh!

Conversation

thomasp85 commented Sep 7, 2026

Uh oh!

teunbrand left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

teunbrand Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

teunbrand Sep 8, 2026 •

edited

Loading