# Duckula **Repository Path**: skyter10086/duckula ## Basic Information - **Project Name**: Duckula - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-20 - **Last Updated**: 2026-11-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Duckula **pandas / Polars 风格的 DataFrame API,跑在 DuckDB 上,用 Raku 写。** 名字来自 `Duck` + `Dracula`——1988 年动画《Count Duckula》(内地译《怪鸭历险记》)。 一是指向底层的 DuckDB,二是隐喻"同时兼容 pandas 与 Polars 两套 API 的缝合体", 三是那只鸭子本就是家族里的异类:不吸血、爱蔬菜、讨厌阴森城堡。 ## 快速上手 ```raku 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); # 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 => ); # 两个同名键 # 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 格式) 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); $df.to-csv('out.csv'); # 可选 :!header :delimiter<;> :null $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); # 指定临时表名 # 数据落进一张 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')>>.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).rows; # first(默认)/ last / none / any say $df.value-counts('city').gist; # city | count;:normalize 再加 proportion say $df.rename('amount' => '金额').names; # 未改名的列原样保留 say $df.drop().names; say $df.drop-nulls('amount').rows; # :how 只丢整行全空的 say $df.fill-nulls('amount', :strategy); # 或 :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().rows; # 多列按位置展开,长度不齐补 NULL say $df.explode('tags', :!keep-empty).rows; # 切回 DuckDB 原生:空列表不产行 my $long = $wide.unpivot(, :index); # id | variable | value my $pvt = $long.pivot(:on, :index, :values); say $pvt.gist; # 分组值成为列名;:agg 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` 解);`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 (