Rand Stats

Duckula

zef:skyter10086

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,省掉一次取数。

设计原则

  1. 不写 DuckDB 交互 —— 全部复用 DB::DuckDB
  2. 不拥有数据 —— 数据永远在 DuckDB 的向量里,Duckula 只描述"下一步算什么"
  3. SQL-first —— 所有算子编译成 SQL,filter/join/groupby 由 DuckDB 执行器完成
  4. SQL 可直写 —— duckula.sql(...) / $df.sql("... from self ..."), 不写 SQL 解析器:解析与优化都交给 DuckDB,只做字符串感知的占位符绑定
  5. 默认防注入 —— 值走参数绑定,标识符走 quote-ident + 白名单, SQL 直写走网关(DuckDB 解析器判定语句类型 / 写动词扫描 / enable_external_access=false)

状态

LazyFrame 与写入(Parquet / Appender)仍待实现。

路线图见 ARCHITECTURE.md。

依赖

开发

raku -Ilib -e 'use Duckula; say $Duckula::VERSION'          # 注意 sigil:$Duckula::VERSION
for f in t/*.rakutest; do raku -Ilib "$f"; done            # 全部回归

安装:

zef install .

文档

家族

模块职责
DB::DuckDBDuckDB 驱动(NativeCall + DB 接口)
App::DuckETLSQL-first ETL,带 TUI
DuckulaDataFrame API