Skip to main content

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.

FunctionKindSignatureSummary
kuva_renderscalarVARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHARRenders 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_terminalscalarVARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHARRenders the same JSON as terminal text — braille dots and ANSI colour. The grid and the print switch ride along in the JSON.
kuva_render_typstscalarVARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHARRenders the same JSON as Typst source — a .typ document (a CETZ vector drawing) for typst compile.
kuva_render_filescalarVARCHAR -> VARCHAR, VARCHAR, VARCHAR -> VARCHARRenders 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_versionscalar() -> VARCHARThe 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;
FieldDefaultWhat it sets
terminal.cols100Terminal width in character columns.
terminal.rows30Terminal height in character rows.
terminal.printfalseWrite 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);
FieldDefaultWhat it sets
file.dirsystem temp directoryOutput directory; created if it does not exist.
file.namekuva-<time>-<random>[-<type>-<title>].svgOutput 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.openfalseOpen 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:

LevelWhat it holdsWhere
The figureseries, and the shared chrome: title, axes, grid, legend, theme, palette, font, annotations, figure.Canvas, title & axes, Legends, Themes, and the rest of Reference
A seriesOne 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 valuesPoints, 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 series list; they share one set of axes. See Series & shared fields.
  • Multiple panels. Add a top-level figure object to lay several panels out in a grid. See Figure (multi-panel).
  • A second axis. Put a quantity in secondary_series and describe its axis with y2_axis or x2_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_render returns a string, not a file. Writing it out is up to the caller (for example COPY (SELECT kuva_render(…)) TO 'chart.svg') — or use kuva_render_file, which does exactly that and returns the path (native builds only).
  • JSON is the fallback API. It exists because series is heterogeneous; a future SQL-friendly layer (one function per chart type, STRUCT arguments) can sit on top of the same renderer.