函数
加载扩展会注册五个函数 —— 一个返回 SVG,一个返回终端文本,一个返回 Typst 源码,一个把 SVG 写成文件并
返回路径,还有一个报告 kuva 版本。它们和 DuckDB 自带的函数一样用:可以放进投影、WHERE 条件或
GROUP BY,也能和内置函数随意组合。
| 函数 | 类别 | 签名 | 说明 |
|---|---|---|---|
kuva_render | 标量 | VARCHAR -> VARCHAR、VARCHAR, VARCHAR -> VARCHAR | 把一段 JSON 描述的图表渲染成一份 SVG 文档。可选的第二个参数是一份 JSON 数据集注册表。 |
kuva_render_terminal | 标量 | VARCHAR -> VARCHAR、VARCHAR, VARCHAR -> VARCHAR | 把同一段 JSON 渲染成终端文本 —— 盲文点阵 + ANSI 色;网格与 print 开关都在 JSON 里带着。 |
kuva_render_typst | 标量 | VARCHAR -> VARCHAR、VARCHAR, VARCHAR -> VARCHAR | 把同一段 JSON 渲染成 Typst 源码 —— 一份 .typ 文档(CETZ 矢量图),交给 typst compile。 |
kuva_render_file | 标量 | VARCHAR -> VARCHAR、VARCHAR, VARCHAR -> VARCHAR | 把同一段 JSON 渲染成一份 SVG 文件并返回它的路径,可选用浏览器打开。只有原生构建支持;目录、文件名与 open 开关都在 JSON 里带着。 |
kuva_version | 标量 | () -> VARCHAR | 本扩展编译时链接的 kuva 版本(例如 0.6.0)。 |
kuva_render
kuva_render(spec_json VARCHAR) -> VARCHAR
kuva_render(spec_json VARCHAR, data_json VARCHAR) -> VARCHAR
kuva_render 包装了 kuva —— 一个纯 Rust 的统计绘图库。它的入参是一段
描述单张图的 JSON,出参是一份完整的 SVG 文档字符串。绘图发生在扩展内部,所以同一张图在 DuckDB 能跑的
任何地方都长一样 —— CLI、Python / R 会话、JVM 宿主,或浏览器里的 DuckDB-Wasm —— 宿主机上不需要
matplotlib / ggplot2。
最小可用的一次调用 —— 读一对列,然后把它画出来:
-- 点一下 Run:结果是一整份 SVG 文档,直接画在这里
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');
本站每个块都写了 "show":"svg",点 Run 就会把图画在结果区里;缩放与平移在全屏里。
为什么是 JSON 而不是 DuckDB 的 STRUCT:一张图里的 series 是异构的(scatter 与 bar 的字段各不
相同),而 STRUCT 的 LIST 要求元素同型,表达不了 [StructA, StructB]。键名一律 snake_case。
图表配置与数据分离
第二个参数是一个 JSON 对象,把数据集名映射到行数组。系列用 dataset 挑一个、用 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);
它存在的意义,是让图表配置与数据可以由不同的东西来构造 —— 配置交给宿主 SDK、数据交给 SQL —— 两边都 不必知道对方的形状。单参数写法完全没变。详见数据集。
kuva_render_terminal
kuva_render_terminal(spec_json VARCHAR) -> VARCHAR
同一段 JSON、另一个后端:出来的不是 SVG,而是终端文本 —— 点用盲文点阵、线用制表符、颜色用 ANSI。
终端自己的设置写在 JSON 里、放在顶层的 terminal 对象里,所以不管以后再往这条路上加什么,这个函数都只有一个
参数:
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;
| 字段 | 默认 | 设置什么 |
|---|---|---|
terminal.cols | 100 | 终端宽度(字符列数)。 |
terminal.rows | 30 | 终端高度(字符行数)。 |
terminal.print | false | 把这一帧写到 stdout 并返回 NULL,而不是作为字符串返回。 |
返回的是一个带着转义序列的普通字符串,所以 COPY (SELECT …) TO 'chart.ans' 或者直接回灌给 shell 都行 ——
那正是 kuva 的 CLI 在 --terminal 下会打印的东西,两者走的是同一个
TerminalBackend::new(cols, rows).render_scene(&scene)。错误的表现与 kuva_render 一致:让整条语句失败,
而不是返回 NULL。
伸手去用之前有两件事值得知道:终端是暗的,所以这个入口在没有指定主题时用 dark 主题渲染(默认主题的近黑文字
在近黑背景上等于没有);以及 print 之所以存在,是因为在 DuckDB CLI 里把一个字符串列弄到控制台上很别扭,
而打印是随手的。见终端输出。
kuva_render_typst
kuva_render_typst(spec_json VARCHAR) -> VARCHAR
kuva_render_typst(spec_json VARCHAR, data_json VARCHAR) -> VARCHAR
同一段 JSON,第三个后端:不再是 SVG,而是 Typst 源码 —— 一份完整的 .typ 文档,含页面设置、
@preview/cetz 的导入,图本身用 CETZ 的原语画出来:
SELECT kuva_render_typst('{"series":[{"type":"line","data":[{"x":1,"y":2},{"x":2,"y":3}]}]}') AS source;
返回的字符串就是那份 .typ —— 用你的客户端原样写出去,再 typst compile chart.typ 得到 PDF
(或 --format svg / --format png)。不要用 COPY … TO 'chart.typ':那是 CSV 写出器,会给文件
加一行表头、并把文档里每个 " 翻倍。细节与变通写法见 Typst 输出。
kuva 不内嵌 Typst 编译器(这个后端纯是字符串拼装),所以把源码变成 PDF / SVG / PNG 是你自己另跑的一步
typst compile。它恰好适合这种场景:图要放进一份更大的 Typst 文档,或者想拿源码来手改。其余情况交给
kuva_render,它在扩展内部就把 SVG 画好,不需要额外装任何东西。
这个入口没有自己的选项对象 —— kuva 的 TypstBackend 目前只认一个固定的 CETZ 版本、没有可配置项 ——
所以它保持单参数(外加可选的数据集参数)。见 Typst 输出。
kuva_render_file
kuva_render_file(spec_json VARCHAR) -> VARCHAR
kuva_render_file 渲染同一段 JSON,并把 SVG 写成一个文件,返回那个路径。它是
COPY (SELECT kuva_render(…)) TO … 之上的一层便捷封装:目录、文件名、要不要打开都写在 JSON 里、放在顶层的
file 对象里。
-- 在你的浏览器里打开这张图,并返回它写出的路径
SELECT kuva_render_file({
'file': {'open': true},
'series': [{'type': 'scatter', 'data': [{"x": 1, "y": 2}, {"x": 3, "y": 4}]}]
}::JSON);
| 字段 | 默认 | 设置什么 |
|---|---|---|
file.dir | 系统临时目录 | 输出目录;不存在时自动创建。 |
file.name | kuva-<时间>-<随机尾缀>[-<图型>-<标题>].svg | 输出文件名。没写后缀时补 .svg,其余部分会过一遍文件名合法性规则(非法字符、Windows 保留设备名、结尾的点与空格)。 |
file.open | false | 写完后用系统默认浏览器打开。 |
返回的就是真正写出去的那个路径,可以直接交给 read_text(…)、下游工具或下一条查询。没给 file.name 时文件名是
kuva-<时间>-<随机尾缀>[-<图型>-<标题>].svg:时间紧跟前缀(所以一个目录按名字排序就是按时间排序),spec 里带了
图型与标题就拼在后面,且绝不覆盖已有文件。你点名给了名字就用那个名字(会覆盖)—— 那正是点名的意义。
这个函数只有原生构建支持。 浏览器(DuckDB-Wasm)里没有本地文件系统可写,所以那边根本不注册这个函数 —— 在
网页上请用 kuva_render,把 SVG 字符串显示在页面里。见文件输出。
kuva_version
kuva_version() -> VARCHAR
本扩展编译时链接的 kuva 版本。kuva 0.6 起每份渲染出来的 SVG 头部也会带一行
<!-- Generated by kuva X.Y.Z -->,但那份产物可能被复制、被裁剪、被别的工具重新序列化;这个函数回答的是
「现在加载的这个扩展是哪一版」,排查「这张图是不是旧版画的」时正是要这个答案。
SELECT kuva_version();
-- 0.6.0
规格是怎么分层的
一份规格分三层,每层都有自己的页面:
| 层级 | 装什么 | 在哪 |
|---|---|---|
| 整张图 | series,以及共享的装饰:标题、坐标轴、网格、图例、主题、调色板、字体、标注、figure。 | 画布、标题与坐标轴、图例、主题,以及参考里的其它页 |
| 一个 series | 一张图,用 type 标明,外加每个 series 都能用的字段(color、legend、tooltips、tooltip_labels)。 | series 与通用字段,以及该 type 在图表里的那一页 |
| 共用的值 | 点、误差棒、置信带、趋势线、分组值。 | series 与通用字段 |
图表记录了扩展注册的全部 64 种图型,按 kuva 的分组方式归类 —— 每种都配一个能跑的例子和它的 series 接受的全部字段。参考记录跨图型共用的参数,所以图表页链接过去,而不是重复一遍。
组合
支持三种组合方式:
- 叠加。 把若干 series 放进同一个
series列表;它们共用一套坐标轴。见 series 与通用字段。 - 多面板。 在顶层加一个
figure对象,把若干面板排成网格。见多面板(figure)。 - 第二坐标轴。 把某个量放进
secondary_series,用y2_axis或x2_axis描述它的轴。见 第二坐标轴。
kuva 里还有两种图不是 Plot 变体,而是组合图:覆盖度图与群体等位基因频率图。它们用顶层的 composite
对象代替 series,且与 series / figure 互斥。见组合图。
错误
任何失败 —— JSON 格式错误、字段类型不对、series 列表为空、长度对不上等等 —— 都会让整个查询失败,
而不是返回 NULL。错误信息是英文,且始终以 kuva_render: 开头:
SELECT kuva_render('{"series":[]}'); -- error: `series` must not be empty
说明
- 渲染失败就会让整条语句失败。 错误里带着函数名,查询其余部分不会再求值。不会有东西被静默变成
NULL。 kuva_render返回的是字符串,不是文件。 写进文件由调用方决定(例如COPY (SELECT kuva_render(…)) TO 'chart.svg')—— 或者直接用kuva_render_file,它做的就是这件事并返回 路径(仅原生构建)。- JSON 是兜底 API。 它存在是因为
series是异构的;将来可以在同一个渲染器之上再包一层 SQL 友好的 API(每个图型一个函数、STRUCT参数)。