跳到主要内容

简介

duckfn_kuva 是一个 DuckDB 可加载扩展:它给 DuckDB 加了一批 SQL 函数,加载之后它们和 DuckDB 自带的函数没有区别。你不需要知道它是怎么写出来的,也不用编译 任何东西 —— CLI、Python / R 会话与浏览器里的构建接受的都同一份 .duckdb_extension 文件。

它加了这些函数:

函数类别作用
kuva_render(json)标量把一段 JSON 描述的图表渲染成一份 SVG 文档。
kuva_render_terminal(json)标量把同一段 JSON 渲染成终端文本(盲文点阵 + ANSI 色)。
kuva_render_typst(json)标量把同一段 JSON 渲染成 Typst 源码 —— 一份交给 typst compile 的 .typ 文档。
kuva_render_file(json)标量把同一段 JSON 写成 SVG 文件并返回路径;仅原生构建。
kuva_version()标量本扩展编译时链接的 kuva 版本。

kuva_render 包装了 kuva —— 一个纯 Rust 的统计绘图库:你用 JSON 描述 一张图(64 种图型任选 —— 散点、直方图,到小提琴图、桑基图、K 线图、热力图,也可以把几种叠在一起), 函数返回一份完整的 SVG。另外还有两种组合图(基因组浏览器式的覆盖度图与群体等位基因频率图),它们不是 图型而是独立的顶层入口,用 composite 对象描述,见组合图。绘图发生在扩展 内部,所以同一张图在 DuckDB 能跑的任何地方都长一样 —— CLI、Python / R 会话、JVM 宿主,或浏览器里的 DuckDB-Wasm —— 宿主机上不需要 matplotlib / ggplot2。

装上它​

INSTALL duckfn_kuva FROM community;
LOAD duckfn_kuva;

然后在任意查询里调用:

-- 点一下 Run:图就地画出来
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');

上面这个块就在你的浏览器里真跑:站点从项目的最新 Release 预加载了这个扩展,所以这里不用写 LOAD。 其他获取文件的方式见安装。

接下来去哪​

  • 安装 —— 社区仓、Release 文件,或者本地自己构建的产物。
  • 函数 —— 这个函数,以及 JSON 图表规格是怎么分层的。
  • 图表 —— 每一种图型都配一个能跑的例子和完整的字段表;先从直方图 看起。
  • 参考 —— 跨图型共用的参数:坐标轴、图例、 主题、调色板等等。
  • 版本 —— 每个扩展版本对应哪一版 kuva,以及各版本改了什么。
  • 开发指南 —— 从源码构建这个扩展。那是给改这个仓库的人看的;用扩展 本身不需要它。