Duckula
pandas / Polars 风格的 DataFrame API,跑在 DuckDB 上,用 Raku 写。
名字来自 Duck + Dracula——1988 年动画《Count Duckula》(内地译《怪鸭历险记》)。
一是指向底层的 DuckDB,二是隐喻"同时兼容 pandas 与 Polars 两套 API 的缝合体",
三是那只鸭子本就是家族里的异类:不吸血、爱蔬菜、讨厌阴森城堡。
快速上手
use Duckula;
use Duckula::Expr;
my $d = duckula; # 默认会话;隔离用 Duckula::Session.new
# 1. 读文件(路径走参数绑定)
my $df = $d.read-csv('orders.csv');
say $df.names; # 列名
say $df.shape; # (行数, 列数)
# 2. 取列 -> Series(注意是 {} 不是 [],Raku 的 [] 只收 Int)
my $amount = $df{'amount'};
say $amount.sum; # 走向量内存,整数列返回 Int
# 3. 表达式与算子(全部编译成 SQL,数据不搬进 Raku)
my $hot = $df.filter((col('amount') > 100) & (col('city').starts-with('北')))
.with-column((col('amount') * 1.1).alias('amount_taxed'))
.sort-values('amount', :desc);
# 4. 分组聚合
my $by-city = $df.group-by('city')
.agg(col('amount').sum.alias('total'), len().alias('n'))
.sort-values('total', :desc);
# 列名可以省:col('amount').sum 自动叫 amount_sum
say $df.group-by('city', 'kind').agg(col('amount').sum).names;
# 全表聚合(不分组)
say $df.agg(len().alias('n'), col('amount').max.alias('hi')).rows;
# 5. 连接(列名只在真冲突时加后缀,默认 _right)
my $cities = $d.read-csv('cities.csv'); # city, region
my $joined = $df.join($cities, on => 'city', :how<left>); # inner/left/right/full/semi/anti/cross
say $joined.names; # city,kind,amount,region
# 异名键用 Pair;多个同名键直接列(列名按你的表调整)
# $df.join($cities, on => 'city' => 'name'); # 左 city 对右 name
# $df.join($cities, on => <city kind>); # 两个同名键
# 6. 窗口 / 环比 / 排名 —— 窗口是表达式的一部分,入口是 with-column
$df.with-column(col('amount').sum.over('city').alias('city_total'))
.with-column((col('amount') / col('city_total')).alias('share'))
.with-column(col('amount').diff.alias('dod'))
.with-column(col('amount').rank(:desc).alias('rk'));
# 裸聚合会自动广播(等价 Polars 的 with_columns(pl.col('amount').sum()))
say $df.with-column(col('amount').sum.alias('total')).rows.elems; # 行数不变
# 7. 切片
$df.head(10); # = $df.limit(10)
$df.tail(10); # 末 10 行
$df.slice(5, 10); # 从第 6 行起取 10 行
$df.slice(-10); # 倒数 10 行
# 8. 也可以直接写 SQL,self 指当前 Frame
my $top = $by-city.sql('select city, total from self where total > ?', 1000);
# 9. 临时视图用完可回收(连接关闭时也会自动消失)
$d.drop-views;
# 10. Polars 风格的惰性路径:只攒计划,collect 才执行
my $lf = $d.scan-csv('orders.csv') # 一个字节都不读
.filter(col('amount') > 100)
.group-by('city')
.agg(col('amount').sum.alias('total'))
.sort-values('total', :desc)
.limit(10);
say $lf.explain; # 计划树 + 生成的 SQL(比 eager 的十层子查询干净得多)
my $out = $lf.collect; # 这时才真正扫文件
# 11. 导出 Arrow:交给 pyarrow / Polars,或任何读 C data interface 的库
my $arrow = $df.arrow;
say $arrow.schema.gist; # id: l city: u amount: d:18,2 这种
say $arrow.format-of('amount'); # 单看一列的类型
$arrow.chunks(-> $chunk {
say $chunk.length; # 2048 行一块,最后一块可能更短
say $chunk.column(0).ints; # 按 schema 的类型选 .ints / .int32s / .strs ...
});
$arrow.free;
# 12. 落成 Arrow IPC 文件:跨进程交给 pyarrow / Polars
$df.write-ipc('out.arrow'); # file 格式(.arrow/.feather)
$df.write-ipc('out.arrows', :format<stream>); # stream 格式,适合管道
# 不想落盘?直接拿字节(默认 stream 格式)
my Buf $bytes = $df.ipc-buf;
# Python 侧:
# >>> import pyarrow.ipc as ipc
# >>> ipc.open_file('out.arrow').read_all().to_pydict()
# >>> ipc.open_stream(bytes).read_all() # 读 ipc-buf 的产物
# 13. 写出去:Parquet / CSV / 真表(数据不出 DuckDB,返回行数)
$df.to-parquet('out.parquet'); # 默认 zstd
$df.to-parquet('out.parquet', :compression<snappy>);
$df.to-csv('out.csv'); # 可选 :!header :delimiter<;> :null<NA>
$df.to-table('clean_orders'); # CREATE TABLE AS,:!replace 则已存在就报错
$df.append-to('clean_orders'); # INSERT INTO ... SELECT
# 反向:Raku 里的行写进已有表(走 Appender,单事务)
$s.execute('CREATE TABLE t (i BIGINT, s VARCHAR)');
$s.insert('t', ((1, 'a'), (2, Any))); # Any -> NULL
# 14. 想知道一条 SQL 会被判成什么?问 DuckDB 的解析器
$s.classify('SELECT 1'); # (SELECT)
$s.classify('SELECT 1; CREATE TABLE t(a INT)'); # (SELECT CREATE)
$s.classify('PRAGMA database_list'); # (SELECT)
$s.sql('INSTALL arrow'); # 拒:DuckDB parsed it as LOAD
# 15. 读 Arrow IPC:别人(pyarrow / Polars / Duckula 自己)写的文件
my $raw = $s.read-arrow('out.arrow'); # file 格式
my $raw2 = $s.read-arrow('out.arrows'); # stream 格式,自动识别
my $raw3 = $s.read-arrow('out.arrow', :name<imported>); # 指定临时表名
# 数据落进一张 TEMP 表:连接一关就没了,Frame 不能跨连接用
say $raw.rows; # 已经解好的行
say $raw.filter(col('amount') > 100).rows; # 之后的算子照常交给 DuckDB
# 只想看看文件里是什么,不读数据:
say $s.describe-arrow('out.arrow').gist; # format/batches/rows/fields
# # 每个字段的 name:format 摘要也能单看:
say $s.describe-arrow('out.arrow')<fields>>>.gist.join(' | ');
# 16. 清洗与重塑:拼接 / 去重 / 频次 / 改名 / 删列 / 空值 / 类型
my $all = $df.concat($other); # 按名字对齐,缺的列补 NULL
my $same = $df.concat($other, :strict); # 列名必须完全一致(Polars 的 vertical)
say $df.unique('city').rows; # 去重,保持行序
say $df.unique('city', :keep<last>).rows; # first(默认)/ last / none / any
say $df.value-counts('city').gist; # city | count;:normalize 再加 proportion
say $df.rename('amount' => '金额').names; # 未改名的列原样保留
say $df.drop(<tmp raw>).names;
say $df.drop-nulls('amount').rows; # :how<all> 只丢整行全空的
say $df.fill-nulls('amount', :strategy<ffill>); # 或 :value(0) / mean / median / bfill
say $df.cast(amount => 'DECIMAL(18,4)').gist; # 表达式级:col('amount').cast('BIGINT')
# 17. 重塑与概览:展开 / 宽长互转 / 透视 / 采样 / 概览
say $df.explode('tags').rows; # 列表列展开;空列表/NULL 各留一行 NULL
say $df.explode(<x y>).rows; # 多列按位置展开,长度不齐补 NULL
say $df.explode('tags', :!keep-empty).rows; # 切回 DuckDB 原生:空列表不产行
my $long = $wide.unpivot(<q1 q2>, :index<id>); # id | variable | value
my $pvt = $long.pivot(:on<variable>, :index<id>, :values<value>);
say $pvt.gist; # 分组值成为列名;:agg<count|max|...>
say $pvt.sample(:n(2), :seed(42)).gist; # 可复现抽样;:frac(0.5) 按比例
say $df.describe.gist; # 每列一行:类型/分位数/空值率等 12 列
pivot 的分组值来自数据,所以在建算子时会先跑一次 SELECT DISTINCT(这是唯一
一个"立刻读数据"的动词,eager / lazy 都一样);它不用 DuckDB 原生 PIVOT ——
后者被语句分类器判成 MULTI,过不了只读守卫,因此改用条件聚合,列名由我们控制。
describe 是「每列一行」,与 pandas 的「每个统计量一行」不同,但多了类型、
近似唯一值数与空值率。
Arrow IPC 的字节由 Duckula 自己编码(一个最小 FlatBuffers 构造器 + Arrow 的
Message/Schema/File 布局),不需要 DuckDB 的 arrow 扩展。覆盖基本类型、
decimal、date/time/timestamp、list/struct/map、BLOB 以及 ENUM(走 DictionaryBatch)。
读侧(Duckula::ArrowRead)是同一套词汇表反着用:FlatBuffers 的 Type union 先
翻译成 Arrow format 字符串,再交给写侧的 parse-format 归一,所以解码分支与编码
分支一一对称。DuckDB 没有内置的 read_arrow(arrow 扩展没有 mingw 构建),因此
这里走「解码成 Raku 值 → CREATE TEMP TABLE → Appender 灌入」:没有裸指针、没有
废弃的 duckdb_arrow_array_scan,每个不支持的类型都能报出列名 + Arrow 类型。
标量、List、Struct、Map 及其任意互相嵌套全部支持(Map 就按
List<Struct> 解);FixedSizeList / Union / RunEndEncoded 明确报错。
两处有意的降级:Arrow 的 Interval 落成文本(Appender 的 cast 不支持 VARCHAR→INTERVAL),
Duration 落成 BIGINT(保留原始计数)。
ipc-buf 是 C data interface 裸指针的跨进程替代品:指针只在导出它的进程里有
效,而 IPC 字节可以塞进管道、交给 Inline::Python 里的 pa.ipc.open_stream(...)。
同一份 Arrow 文件反复 read-arrow 时,FlatBuffers 解析与逐 cell 解码只做一次:
缓存的是纯解码产物(列名 / 类型 / 列值),按「路径 + 字节数 + mtime」判失效,
进程内跨 session 共享;建表与 Appender 仍按各自连接重做。可观测与手动清理:
say $s.arrow-cache-stats; # {hits => 3, misses => 1, entries => 1}
$s.clear-arrow-cache; # 强制下次重解,也释放缓存内存
默认拒绝写操作,而且这个判定来自 DuckDB 自己的解析器,不是文本匹配:
duckdb_extract_statements 拆语句、duckdb_prepared_statement_type 定类型、
duckdb_nparams 数参数。所以 PRAGMA database_list 这种只读语句能放行(正则时代
因为含 pragma 一词被误拒),而 INSTALL / SET / COPY / ATTACH 各按真实类型拦下。
类型之外还有一层写动词扫描——因为 WITH d AS (DELETE ... RETURNING *) SELECT ...
的类型是 SELECT、EXPLAIN ANALYZE DELETE ... 的类型是 EXPLAIN,两条都会真的
改数据。$s.sql(..., :unsafe) 显式放开。
写文件走 COPY (<select>) TO 'file',DuckDB 自己做,一行都不经过 Raku;写表走
CREATE TABLE AS / INSERT INTO ... SELECT,数据同样不出库。COPY 不接受绑定
参数,所以路径与表名必须转义(sql-literal 单引号双写、quote-ident 双引号双写),
带引号的文件名和表名都实测可用。沙箱会话(Session.new(:sandbox))写文件会被当场
拒绝并说清原因,写表不受影响——表不出库。
Frame 与 LazyFrame 语义完全一致(同一套列名白名单、表达式、聚合、join 规则),
区别只在「什么时候拼 SQL」:Frame 每一步立刻套一层 SELECT,LazyFrame 攒计划树、
collect 时融合成一条扁平 SQL。LazyFrame.arrow 会先 collect——Arrow 的 chunk
就是执行结果本身,没法推迟。惰性路径的 to-parquet / to-csv / to-table 不需要
collect:参数渲染成字面量后直接交给 COPY,省掉一次取数。
设计原则
- 不写 DuckDB 交互 —— 全部复用
DB::DuckDB - 不拥有数据 —— 数据永远在 DuckDB 的向量里,Duckula 只描述"下一步算什么"
- SQL-first —— 所有算子编译成 SQL,
filter/join/groupby 由 DuckDB 执行器完成 - SQL 可直写 ——
duckula.sql(...) / $df.sql("... from self ..."),
不写 SQL 解析器:解析与优化都交给 DuckDB,只做字符串感知的占位符绑定 - 默认防注入 —— 值走参数绑定,标识符走
quote-ident + 白名单,
SQL 直写走网关(DuckDB 解析器判定语句类型 / 写动词扫描 / enable_external_access=false)
状态
- v0.18.0:
read-arrow 解码缓存。重复的 read-arrow 不再重解 FlatBuffers:
进程级缓存纯解码产物(names / types / cols),按「绝对路径 + 字节数 +
mtime」判失效,跨 session 共享(解码结果与连接无关)。刻意不缓存字节窗口
(Buf/Bytes/Tbl,会把整个文件钉在内存)、schema 对象、临时表(属于连接)。
命中后仍各自建表 + Appender,上限 8 个文件 FIFO 淘汰,Lock 保护。新增
$s.arrow-cache-stats / $s.clear-arrow-cache。共 812 项回归测试。 - v0.17.0:阶段 11 第二批 —— 重塑与概览。五个动词在
Frame 与 LazyFrame
上各一套、语义一致:explode(列表列展开,默认保留空列表/NULL 为一行 NULL,
多列按位置 zip)、unpivot(宽转长,走 DuckDB 原生 UNPIVOT)、pivot(长转宽,
分组值成列名,聚合函数走白名单)、sample(:n/:frac + :seed 可复现)、
describe(SUMMARIZE,每列一行 12 列)。SQL 构件集中在 Duckula::Reshape。
pivot 不用 DuckDB 原生 PIVOT —— 它被语句分类器判成 MULTI 过不了只读守卫,
改用条件聚合,代价是建算子时要先 SELECT DISTINCT 拿分组值。共 782 项回归测试。 - v0.16.0:阶段 11 第一批 —— 清洗与重塑。八个动词在
Frame 与 LazyFrame
上各一套、语义一致:concat(UNION ALL BY NAME,按名字对齐,:strict 要求
列名完全一致)、unique(first / last / none / any,前三种保持行序)、
value-counts(:normalize 加占比列)、rename、drop、drop-nulls(:how<any|all>)、
fill-nulls(:value 或 ffill / bfill / mean / median)、cast(列级
$df.cast(id => 'VARCHAR'),表达式级 col('id').cast('BIGINT'))。
SQL 片段集中在新的 Duckula::Clean(纯函数),eager 与 lazy 各自套壳;能表达成
投影/过滤的进计划树(drop-nulls 会与相邻 filter 合并成一个 WHERE),
需要集合运算或行序锚的退化成 Source。类型名过白名单 —— CAST(x AS ?) 不成立,
类型只能拼文本。共 730 项回归测试。 - v0.15.0:嵌套类型读入 + 字节可复现。
read-arrow 现在能读 Struct /
Map / List<Struct> / 结构套结构:Map 在 Arrow 里就是
List<Struct<key, value>>,entries 直接复用 Struct 的解码分支,因此没有新增
一套类型系统。渲染回 DuckDB 时三种容器各用它能 cast 的形式([..] /
{'k': v} / {k=v}),转义按 DuckDB 自己打印 VARCHAR 的规矩(反斜杠双写、
单引号写成 \')—— 混用 SQL 标准的单引号双写不会报错,只会静默给出错误的
字符串。写出侧同时补了 null 槽归一:定长槽清零、位图空值位清零、变长槽
清掉旧数据并把 offset 改成「长度 0」、复合类型把父级的空传给子级,于是同一份
逻辑数据必然写出逐字节相同的文件(CASE 出来的列、过滤后的列与源列三者字节
一致)。共 649 项回归测试。 - v0.14.0:Arrow 往返闭合 ——
ipc-buf 与 read-arrow。
Frame.ipc-buf / LazyFrame.ipc-buf / Arrow.ipc-buf 把结果编码成内存里的
IPC 字节(默认 stream 格式),与 write-ipc 共用同一份编码逻辑、字节逐位相同;
这是 C data interface 裸指针的跨进程替代。Session.read-arrow 反过来:
Duckula::ArrowRead 解 FlatBuffers(table/vtable、Schema、RecordBatch、
DictionaryBatch、Footer),把列 buffer 解码成 Raku 值,再建 TEMP 表用 Appender
灌进去。file / stream 两种格式、多批次、字典(含 delta)、List<标量> 全部支持,
标量类型往返后列类型与值都精确一致。describe-ipc 只读骨架不读数据。
共 634 项回归测试。 - v0.13.0:阶段 8 收口 —— 判定改由 DuckDB 自己的解析器给出。
duckdb_extract_statements 拆语句、duckdb_prepared_statement_type 定类型、
duckdb_nparams 数参数,替换掉前缀启发式与数问号。类型白名单之外再加一层写动词
扫描,因为 WITH d AS (DELETE ... RETURNING *) SELECT ... 的类型是 SELECT、
EXPLAIN ANALYZE DELETE ... 的类型是 EXPLAIN —— 只看类型会放行真的写操作。
Session.classify 可自查某条 SQL 被判成什么。共 597 项回归测试。依赖
DB::DuckDB:ver<1.2.0+>(新增 DB::DuckDB::Parser)。 - v0.12.0:阶段 7 收口 —— 写出。
to-parquet / to-csv / to-table /
append-to 在 Frame 与 LazyFrame 上各一套,数据不出 DuckDB;Session.execute
(写语句)、Session.insert(Appender 批量)、Session.create-table(接 Frame /
LazyFrame / SQL)补齐反向通道。路径与表名全部转义,沙箱会话写文件当场拒绝。
共 527 项回归测试。 - v0.11.0:阶段 6 收口 —— Arrow IPC 导出。
write-ipc($path, :$format<file|stream>)
把结果直接写成 Arrow IPC 字节(Duckula::ArrowIPC:自写 FlatBuffers 构造器 +
Message/Schema/RecordBatch/Footer 布局 + DictionaryBatch)。绕开 COPY … FORMAT
ARROW 对 arrow 扩展的依赖(该扩展只在标准平台发布)。全类型覆盖,产物用
pyarrow 26 逐值验证。共 457 项回归测试。 - v0.10.0:阶段 6 的第一半 —— Arrow 出口。
Frame.arrow / LazyFrame.arrow
返回 Duckula::Arrow:.schema 是整表类型描述(含嵌套结构),.chunks 逐块给
2048 行的 Arrow array,.fields / .format-of 查类型,free 幂等。依赖
DB::DuckDB:ver<1.1.0+>(该版补齐了 Arrow 的 schema 一半与反向导入)。
共 431 项回归测试。 - v0.9.0:阶段 4 ——
LazyFrame + 计划树 + collect。7 种计划节点
(source / project / filter / aggregate / join / sort / limit),渲染器把树累积成
一个 Query:相邻 filter 合并成一个 WHERE、filter 与 group-by 待在同一层,
该物化时才物化。explain 看计划树 + SQL;scan-csv / scan-parquet 惰性读;
LazyFrame.sql 走临时视图边界;? 参数从头留到 collect 才绑定。
顺带把 GroupBy / Join 的校验抽成 spec / join-layout 供两套 API 共用。
共 401 项回归测试。 - v0.8.0:窗口函数与切片——
Expr.over / cum-sum / cum-max / cum-min /
cum-count / shift / diff / rank / rolling-sum / rolling-mean;
with-column 支持裸聚合广播、覆盖同名列、窗口后锚回行序;with-columns 一次加多列;
Frame.limit / tail / slice(含负 offset)。阶段 5 到此收尾。共 337 项回归测试。 - v0.7.0:
join —— inner / left / right / full / semi / anti / cross,
同名键、多键、异名键(Pair)、自定义后缀;Frame.names 改走 LIMIT 0 只问 schema。
共 271 项回归测试。 - v0.6.1:
Frame.rows 按 ColumnView.type 还原类型——sum() 这类 HUGEINT
结果不再以字符串出现,DECIMAL 还原成 Rat。共 224 项回归测试。 - v0.6.0:分组聚合——
group-by(...).agg(...) / .count / Frame.agg(全表),
Expr.label 自动列名、Expr.is-aggregate 拦住非聚合表达式、重名与未知列提前报错。 - v0.5.0:表达式系统——
col()、算术 / 比较 / 逻辑运算符重载、字符串方法,
以及建立在它上面的 filter / with-column / sort-values(全部编译成 SQL)。 - v0.4.0:数据入口与
Series——read-csv / read-parquet(路径走绑定参数)、
$df{'col'} → Series(ColumnView 薄包,聚合零拷贝)、$df[0]、$df.select(...)。 - v0.3.0:SQL 入口——
duckula.sql(...)、Frame.sql("... from self ...")、
字符串感知的 self 占位符扫描(临时视图绑定,不是子查询)、参数固化、临时视图回收。 - v0.2.0:注入防护层——
Duckula::SQL(转义 / 掩码 / 计数 / 只读判定)+
Duckula::Guard(单语句 / 只读 / 占位符校验 + 外部访问沙箱)。 - v0.1.0:骨架(
META6.json + 入口模块 + 加载测试)。
LazyFrame 与写入(Parquet / Appender)仍待实现。
路线图见 ARCHITECTURE.md。
依赖
- Raku 6.d
DB::DuckDB >= 1.0.1Alien::Libduckdb >= 1.1.0
开发
raku -Ilib -e 'use Duckula; say $Duckula::VERSION' # 注意 sigil:$Duckula::VERSION
for f in t/*.rakutest; do raku -Ilib "$f"; done # 全部回归
安装:
zef install .
文档
家族
| 模块 | 职责 |
|---|
DB::DuckDB | DuckDB 驱动(NativeCall + DB 接口) |
App::DuckETL | SQL-first ETL,带 TUI |
Duckula | DataFrame API |