Introduction
duckfn_kuva is a DuckDB loadable extension: it
adds SQL functions to DuckDB, and once it is loaded they behave like DuckDB's own. You do not need to know
how it was written or to compile anything — the CLI, a Python or R session and the browser build all take
the same .duckdb_extension file.
It adds these functions:
| Function | Kind | What it does |
|---|---|---|
kuva_render(json) | scalar | Renders a chart described by a JSON string and returns it as an SVG document. |
kuva_render_terminal(json) | scalar | Renders the same JSON as terminal text (braille dots and ANSI colour). |
kuva_render_typst(json) | scalar | Renders the same JSON as Typst source — a .typ document for typst compile. |
kuva_render_file(json) | scalar | Renders the same JSON to an SVG file and returns its path. Native builds only. |
kuva_version() | scalar | The kuva version the extension was compiled against. |
kuva_render wraps kuva, a pure-Rust statistical plotting library: you
describe one figure — any of 64 chart types, from a scatter or histogram to a violin, sankey,
candlestick or heatmap, or several of them combined — as JSON, and the function returns a complete SVG.
Two further charts are composites rather than plot types (a genome-browser coverage figure and a
population allele-frequency figure); they use a top-level composite object, see
Composites.
The drawing happens inside the extension, so a chart comes out the same 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.
Install it
INSTALL duckfn_kuva FROM community;
LOAD duckfn_kuva;
Then call the function in any query:
-- press Run: the chart 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');
That block runs right here, in your browser: the site preloads the extension from the project's latest
release, so there is no LOAD to write. Installation covers the other ways to get
the file.
Where to go next
- Installation — the community repository, a release file, or a local build.
- Functions — the function and how the JSON chart spec is laid out.
- Plots — every chart type, each with a runnable example and its full field list; start with Histogram.
- Reference — the options shared across charts: axes, legends, themes, palettes and more.
- Versions — which kuva release each extension version wraps, and what changed.
- Development guide — building the extension from source. That part is for people working on this repository; it is not needed to use the extension.