Functions
Loading the extension registers five functions — one that returns SVG, one that returns terminal text, one
that returns Typst source, one that writes an SVG file and returns its path, and one that reports the kuva
version. All behave like DuckDB's own: use them in a projection, a WHERE clause or a GROUP BY, and they
combine with built-in functions freely.
| Function | Kind | Signature | Summary |
|---|---|---|---|
kuva_render | scalar | VARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHAR | Renders a chart described by a JSON string and returns it as an SVG document. The optional second argument is a JSON dataset registry. |
kuva_render_terminal | scalar | VARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHAR | Renders the same JSON as terminal text — braille dots and ANSI colour. The grid and the print switch ride along in the JSON. |
kuva_render_typst | scalar | VARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHAR | Renders the same JSON as Typst source — a .typ document (a CETZ vector drawing) for typst compile. |
kuva_render_file | scalar | VARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHAR | Renders the same JSON to an SVG file and returns its path, optionally opening it in a browser. Native builds only; the directory, file name and open switch ride along in the JSON. |
kuva_version | scalar | () -> VARCHAR | The kuva version this extension was compiled against (e.g. 0.6.0). |
kuva_render
kuva_render(spec_json VARCHAR) -> VARCHAR
kuva_render(spec_json VARCHAR, data_json VARCHAR) -> VARCHAR
kuva_render wraps kuva, a pure-Rust statistical plotting library. Its
argument is a JSON document describing one figure; its result is a complete SVG document as a string.
Because the drawing happens inside the extension, a chart renders identically wherever DuckDB runs — the
CLI, a Python or R session, a JVM host, or DuckDB-Wasm in the browser — with no matplotlib or ggplot2 on
the host.
The smallest useful call — read a column pair and render it:
-- press Run: the result is a complete SVG document, and it is drawn right here
SELECT kuva_render(to_json({
'series': [{'type': 'scatter', 'data': array_agg({'x': x, 'y': y})}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/scatter.tsv');
Every block on this site asks for "show":"svg", so pressing Run draws the chart in the result
area — fullscreen is where zoom and pan live.
JSON rather than a DuckDB STRUCT: one figure's series are heterogeneous (a scatter and a bar
carry different fields), and a STRUCT list is homogeneous, so it cannot express [StructA, StructB].
Key names are snake_case throughout.
Chart config and data apart
The second argument is a JSON object mapping dataset names to arrays of rows. A series names one with
dataset and maps its columns with encode:
SELECT kuva_render(
'{"series":[{"type":"scatter","dataset":"sales","encode":{"x":"revenue","y":"profit"}}]}',
to_json({'sales': array_agg({'revenue': revenue, 'profit': profit} ORDER BY month)})
) AS chart
FROM (VALUES (1, 10, 3), (2, 12, 5), (3, 9, 4), (4, 15, 8)) AS t(month, revenue, profit);
It exists so the chart config and the data can be built by different things — the config by a host SDK, the data by SQL — without either knowing the other's shape. The one-argument form is unchanged. See Datasets.
kuva_render_terminal
kuva_render_terminal(spec_json VARCHAR) -> VARCHAR
The same JSON, a different backend: instead of SVG you get terminal text — braille dots for dots, box-drawing characters for lines, ANSI colour for both.
The terminal's own settings live in the JSON, in a top-level terminal object, so this function stays at one
argument no matter what gets added later:
SELECT kuva_render_terminal(to_json({
'terminal': {'cols': 90, 'rows': 22},
'series': [{'type': 'bar', 'categories': ['a', 'b', 'c', 'd'], 'values': [4, 7, 5, 9]}]
})) AS frame;
| Field | Default | What it sets |
|---|---|---|
terminal.cols | 100 | Terminal width in character columns. |
terminal.rows | 30 | Terminal height in character rows. |
terminal.print | false | Write the frame to stdout and return NULL instead of returning it as a string. |
What comes back is a plain string carrying its escape sequences, so COPY (SELECT …) TO 'chart.ans' or a
pipe back into a shell both work — that is exactly what kuva's CLI prints for --terminal, and the two go
through the same TerminalBackend::new(cols, rows).render_scene(&scene). Errors behave as they do for
kuva_render: they fail the statement rather than returning NULL.
Two things worth knowing before you reach for it: a terminal is a dark surface, so this entry point renders
with the dark theme unless the spec asks for another (the default theme's near-black text disappears on a
near-black frame); and print exists because getting a string column onto a console in the DuckDB CLI is
awkward, while printing is trivial. See Terminal output.
kuva_render_typst
kuva_render_typst(spec_json VARCHAR) -> VARCHAR
kuva_render_typst(spec_json VARCHAR, data_json VARCHAR) -> VARCHAR
The same JSON, a third backend: instead of SVG you get Typst source — a complete .typ document with a
page setup, an @preview/cetz import and the figure drawn with CETZ primitives:
SELECT kuva_render_typst('{"series":[{"type":"line","data":[{"x":1,"y":2},{"x":2,"y":3}]}]}') AS source;
The returned string is the .typ file — write it out verbatim from your client, then
typst compile chart.typ gives you a PDF (or --format svg / --format png). Do not use
COPY … TO 'chart.typ': that is a CSV writer, so it adds a header row and doubles every " in the
document. See Typst output for the details and the workaround.
kuva does not embed a Typst compiler — this backend is pure string emission — so turning the source into a
PDF, SVG or PNG is a separate typst compile you run yourself. That is exactly when it is the right tool: a
figure destined for a larger Typst document, or one whose source you want to hand-edit. For everything
else, kuva_render draws the SVG inside the extension with nothing extra to install.
This entry point has no options object of its own — kuva's TypstBackend currently pins a single CETZ
version and exposes nothing configurable — so it stays at one argument (plus the optional dataset
argument). See Typst output.
kuva_render_file
kuva_render_file(spec_json VARCHAR) -> VARCHAR
kuva_render_file renders the same JSON and writes the SVG to a file, returning the path. It is the
one-statement convenience layer over COPY (SELECT kuva_render(…)) TO …: the directory, the file name and
whether to open the result all ride along in the JSON, in a top-level file object.
-- opens the chart in your browser and returns the path it wrote
SELECT kuva_render_file({
'file': {'open': true},
'series': [{'type': 'scatter', 'data': [{"x": 1, "y": 2}, {"x": 3, "y": 4}]}]
}::JSON);
| Field | Default | What it sets |
|---|---|---|
file.dir | system temp directory | Output directory; created if it does not exist. |
file.name | kuva-<time>-<random>[-<type>-<title>].svg | Output file name. A name with no extension gets .svg appended, and the rest is sanitized (illegal characters, Windows reserved device names, trailing dots and spaces). |
file.open | false | Open the written file in the system default browser. |
The returned path is what was actually written, so it is ready to feed into read_text(…), a downstream
tool, or a second query. With no file.name the file is named
kuva-<time>-<random>[-<type>-<title>].svg: the timestamp comes right after the prefix (so a directory
sorts by time), the chart type and title are appended when the spec carries them, and an existing file is
never overwritten. A name you do supply is used as-is (and overwrites), which is the point of naming it.
This function is native-builds only. A browser (DuckDB-Wasm) build has no local file system to write
to, so the function is not registered there at all — on the web, use kuva_render and show the SVG
string in the page. See File output.
kuva_version
kuva_version() -> VARCHAR
The kuva version this extension was compiled against. Since kuva 0.6 every rendered SVG also carries
<!-- Generated by kuva X.Y.Z --> near the top, but that artifact can be copied, trimmed or
re-serialized; this answers the question for the extension that is loaded right now, which is what you
want when triaging a figure that looks like it came from an older build.
SELECT kuva_version();
-- 0.6.0
How the spec is laid out
A spec has three levels. Each has its own page:
| Level | What it holds | Where |
|---|---|---|
| The figure | series, and the shared chrome: title, axes, grid, legend, theme, palette, font, annotations, figure. | Canvas, title & axes, Legends, Themes, and the rest of Reference |
| A series | One chart, tagged by type, plus the fields every series accepts (color, legend, tooltips, tooltip_labels). | Series & shared fields and that type's page under Plots |
| Shared values | Points, error bars, confidence bands, trend lines, grouped values. | Series & shared fields |
Plots documents all 64 chart types the extension registers, grouped the way kuva groups them — each
with a runnable example and the full list of fields its series accepts. Reference documents the
options shared across charts, so a chart page links there instead of repeating them.
Composition
Three kinds of composition are supported:
- Overlay. Put several series in one
serieslist; they share one set of axes. See Series & shared fields. - Multiple panels. Add a top-level
figureobject to lay several panels out in a grid. See Figure (multi-panel). - A second axis. Put a quantity in
secondary_seriesand describe its axis withy2_axisorx2_axis. See Secondary axes.
Two of kuva's charts are composites rather than Plot variants — a coverage figure and a
population-allele-frequency figure. They take a top-level composite object instead of series, and they
are mutually exclusive with series / figure. See Composites.
Errors
Any failure — malformed JSON, a wrong field type, an empty series list, a length mismatch, and so on —
fails the whole query rather than returning NULL. The message is in English and always starts with
kuva_render: :
SELECT kuva_render('{"series":[]}'); -- error: `series` must not be empty
Notes
- A failed render fails the statement. The error names the function, and the rest of the query is not
evaluated. Nothing is silently turned into
NULL. kuva_renderreturns a string, not a file. Writing it out is up to the caller (for exampleCOPY (SELECT kuva_render(…)) TO 'chart.svg') — or usekuva_render_file, which does exactly that and returns the path (native builds only).- JSON is the fallback API. It exists because
seriesis heterogeneous; a future SQL-friendly layer (one function per chart type,STRUCTarguments) can sit on top of the same renderer.