duckdb v2.0.0 · ducklake v2.0-cyanoptera @ c506b268 · 源码级 · 2026-11-04

DuckLake 线程工作模型:谁在跑、在哪排队、哪里串行

DuckLake 没有自己的线程池:上面是 DuckDB 的调度层(两个线程池、每查询一条 lane、ConsumerToken 轮转),中间 4 条泳道是 DuckLake 各路径分别落在哪个线程上。节点第二、三行写的是由谁执行、并行还是串行;红框 = 串行点,一次只能一个线程通过。左边是元数据(catalog),右边是数据文件。

DuckDB v2.0.0 · 线程与调度(DuckLake 没有自己的线程池)
Catalog DB · 元数据
DATA_PATH · 数据文件
DuckLake 扩展 · 各路径落在哪个线程(红框 = 串行点)
① 读 · ducklake_scan
② 写 · INSERT
③ DELETE · 维护
④ 提交 · COMMIT
扫描读这些表物化清单时查一次
data_file快照下存活的文件
delete_file对应的删除文件
file_column_statsmin/max 剪整文件
inlined_data_tablesinlined 伪文件
inlined_data_<t>_<v>1 个 job 单线程读
inline 行什么时候写写路径不碰 catalog
InlineData行先留在事务里
COMMIT一起写进 inlined_data
> row_limit全部改走 COPY
flush_inlined_data之后再落成 Parquet
元数据访问规则每条都是串行点
内部 Connection每个 DuckLake 事务 1 条
connection_lock只保护创建
metadata_query_lock仅 Quack 后端
Postgres 事务构造时借 1 条连接
pg_pool_acquire_mode默认 force
max_connectionsclamp(1.5×核, 4, 32)
提交写这些表一批 SQL
snapshotPK = snapshot_id
snapshot_changes重试时比对冲突
data_file / delete_file本次新文件
table_stats …合并后的统计
PK 冲突= 别人先提交
默认值DuckDB v2.0.0
threads逻辑核数
external_threads1(调用线程)
async_threadsmin(4×核数, 256)
read_ahead_depth-1 自动
scheduler_process_partialfalse
轮转配额16
parquet_row_group_size122,880
target_file_size512MB
data_inlining_row_limit10
ducklake_max_retry_count10
retry_wait / backoff100ms / 1.5
Conn A 调用线程
编译 · COMMIT
PROCESS_PARTIAL
Executor
每查询一个
K=min(MaxThr,threads)
REGULAR 队列
每查询一条 lane
moodycamel
ConsumerToken
每 lane 取满 16 换
各查询轮得到
REGULAR 池
threads − 1 个 worker
PROCESS_ALL 不抢占
ASYNC 队列
I/O task
读列块 · 开关文件
ASYNC 池
min(4×核数, 256)
只取 ASYNC 队列
Conn B 调用线程
每个活跃连接
+1 条执行线程
PipelineFinishTask
Finalize · 单线程
谁先取到谁跑
event 计数
++finished_tasks
到齐才触发下游
Combine
本线程合进全局
local→global 带锁
BLOCKED → 唤醒
扫描 task 让出线程
I/O 完成重新入队
物化文件清单
InitializeGlobalState
调度时单线程查一次
定并行度
MULTIPLE_FILES
→ threads 个 task
领 row group
gstate.lock 下 ++
文件 k 领完才 k+1
InlinedDataReader
整张表 = 1 个 job
持扫描锁查元数据
ParquetReader
1 RG = 1 scan job
列块没到 → 挂起
DeleteFilter
开文件的线程读
delete file / DV
read-ahead
ASYNC 池提前开文件
read_ahead_depth=-1
InlineData
算子并行
全局计数器加锁
Sort(可选)
带排序且未分区
→ COPY 单线程
COPY · Prepare
各线程并行编码
PARALLEL_COPY
COPY · Flush
单文件锁串行追加
多线程写同一文件
换文件
> target_file_size
开关文件 → ASYNC
DuckLakeInsert
外层 sink · 1 task
每文件 1 行
登记到事务
TransactionState
等 COMMIT 写 catalog
DELETE 扫描
找出要删的行
worker 并行
Delete Sink
按文件攒行号
并入全局时加锁
Delete Finalize
单线程逐文件写
丢文件/行内/删除文件
flush_inlined
读 inlined 表 1 job
写文件走 COPY
merge_adjacent
相邻文件要保序
PRESERVE_ORDER
rewrite_data
扫描 + COPY 并行
删除多的文件重写
Compaction sink
不是并行 sink
每文件 1 行
内部元数据连接
每事务 1 条
SQL 在这里排队
单批 SQL
snapshot+文件+stats
首次不查冲突
COMMIT
调用线程上执行
FlushChanges
PK 冲突
回滚这次尝试
别人先提交了
sleep 退避
100ms×1.5ⁱ×rand
阻塞调用线程
CheckForConflicts
比对 changes
真冲突 → 报错
重写删除文件
TaskExecutor 并行
唯一自投 task
DuckDB 文件
默认 · 本地
同进程 ATTACH
PostgreSQL
多写者
postgres 扩展
SQLite
单机
sqlite 扩展
PG 连接池
force 无视上限
每事务借 1 条
对象存储
S3 · GCS · R2
httpfs / azure
本地磁盘
LocalFileSystem
开发 / 单机
Parquet 数据文件
不可变 · 只追加
RG ≤ 122,880 行
删除文件
-delete.parquet
-delete.puffin
写入中的新文件
提交前不可见
失败 → CleanupFiles
新删除文件
提交后生效
Finalize 逐个写
调度:task 入队 / 取 task 线程内部 / I/O 读路径 写路径 维护 元数据 / 提交 失败重试 串行点

关键不变量与常见误区

1两个池,每查询一条 lane

REGULAR 池(threads − 1 个后台 worker)跑计算 task,ASYNC 池(默认 min(4×核数, 256))只做 I/O;REGULAR worker 空闲时也会顺手做 ASYNC 队列里的活。每个查询的 Executor 在两个队列里各有一条 lane(task_scheduler_type.hpp:15、task_scheduler.cpp:156)。

2轮转保证轮得到,不保证有 worker

worker 用 ConsumerToken 取 task,每条 lane 取满 16 个就整体换下一条(提交 0f67e73fd31)。但没有优先级、不抢占:后台 worker 默认 PROCESS_ALL,一个 task 跑完或阻塞才放手。

3调用线程也是执行者

每个活跃连接的调用线程循环取自己查询那条 lane 的 task(client_context_execution.cpp:349 → executor.cpp:444)。N 个并发连接 ≈ 后台 worker + N 条调用线程同时在跑;新查询就算 worker 全忙,也至少以并行度 1 推进。

4扫描按 row group 领活

DuckLake 的清单固定报 MULTIPLE_FILES,扫描直接起 threads 个 task。领活在 gstate.lock 下做 row_group_index++:文件 k 的 row group 全被领走才轮到 k+1,已领走的同时解码;read-ahead 在 ASYNC 池提前开文件、读列块。

5写:编码并行、追加串行

rotate=true 让 COPY 走 PARALLEL_COPY_TO_FILE:各线程并行 Prepare,在单文件锁下 Flush,多线程写同一个文件,超过 target_file_size 才换。带排序且未分区的表会退化成单线程 COPY;DELETE 的删除文件在 Finalize 里由一个线程逐个写。

6提交在调用线程上

COMMIT 经每事务一条的内部连接发一批 SQL,第一次不查冲突。撞主键后 sleep 退避(阻塞的是这条连接线程,不占 worker),比对 snapshot_changes 再用 snapshot_id+1 重写,最多 10 次;需要时用 TaskExecutor 并行重写删除文件——DuckLake 唯一自己投 task 的地方。

✕误区:文件清单在 planning 阶段就查好

不是。扫描所在 pipeline 被调度时(Pipeline::Schedule → Reset),才在 InitializeGlobalState 里单线程查一次 catalog(ducklake_multi_file_reader.cpp:288),源码注释说是为了避免 worker 一起挤在 GetFiles() 的锁上。

✕误区:等 I/O 时 worker 在干等

v2.0 把 Parquet 列块读取包装成 ASYNC 任务(parquet_reader.cpp:2488),扫描 task 返回 BLOCKED、Deschedule 让出线程,I/O 做完再被唤醒入队。inlined 表例外:它的元数据查询在持有扫描锁时同步执行。

源码:duckdb v2.0.0 · ducklake/src(v2.0-cyanoptera @ c506b268)· duckdb-postgres main · 数值为默认值 icons: devicon / svgl / Apache Parquet / DuckLake repo / Lucide · made with stack-diagram