Skip to main content

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:

FunctionKindWhat it does
kuva_render(json)scalarRenders a chart described by a JSON string and returns it as an SVG document.
kuva_render_terminal(json)scalarRenders the same JSON as terminal text (braille dots and ANSI colour).
kuva_render_typst(json)scalarRenders the same JSON as Typst source — a .typ document for typst compile.
kuva_render_file(json)scalarRenders the same JSON to an SVG file and returns its path. Native builds only.
kuva_version()scalarThe 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.