DuckLake 入门：在一小时内用 DuckDB 搭建湖仓
内容提要
DuckLake是DuckDB团队推出的开放湖仓表格式，元数据存于SQL数据库，数据存为Parquet文件，1.0版于2026年4月发布。本文用Python和duckdb包在笔记本上搭建湖仓：生成示例Parquet数据，创建表并加载，执行追加、更新及增删列等模式变更，用AT (VERSION => n)查询历史版本并恢复误删数据，最后合并小文件。需注意旧文件要过期快照后清理，小写入默认内联，单客户端用DuckDB目录，多用户改用PostgreSQL。
延伸解读
元数据集中管理带来的运维简化
DuckLake 将表清单、模式、快照和文件统计等元数据统一存放在支持 ACID 的 SQL 数据库中，而非像 Iceberg 或 Delta Lake 那样分散在多个元数据文件里。这意味着查找所需文件只需一条 SQL 查询，快照信息也可直接通过 snapshots() 表查看。对于习惯 SQL 的团队，这种设计降低了理解与调试成本，但前提是所选数据库需支持事务和主键约束。
时间旅行与数据恢复的实用边界
通过 AT (VERSION => n) 或 AT (TIMESTAMP => ...) 可查询任意历史快照，甚至恢复误删数据。但文章强调，DuckLake 不会自动删除旧数据文件，因为时间旅行依赖它们。要回收空间，必须显式过期快照并清理文件，且过期后便无法再回溯到该版本。因此，保留策略需提前规划，避免因清理过早而丧失恢复能力。
小写入内联与目录选型的注意事项
默认情况下，10 行以内的小写入会内联到目录数据库中，而非生成新的 Parquet 文件，这解释了为何 5000 行插入会产生文件而 3 行插入不会。此外，使用 DuckDB 文件作为目录仅支持单客户端；多用户场景需改用 PostgreSQL 目录，并安装 postgres 扩展。这些细节直接影响湖仓的并发能力与存储布局，部署前应结合使用场景选择。
Q&A
DuckLake 是什么？它和 Iceberg、Delta Lake 有什么不同？
DuckLake 是 DuckDB 团队推出的开放湖仓表格式，1.0 版于 2026 年 4 月发布。它将表元数据存储在 SQL 数据库中，数据存储为 Parquet 文件。与 Iceberg、Delta Lake 在元数据文件中记录信息不同，DuckLake 通过 SQL 查询即可找到所需文件。
搭建 DuckLake 需要满足哪些前提条件？
需要 DuckDB v1.5.2 或更高版本、较新的 Python 3 以及首次使用时联网（DuckDB 会自动下载 ducklake 扩展）。安装命令为 pip install "duckdb>=1.5.2"，然后验证版本。
DuckLake 的目录数据库应该怎么选？单客户端和多用户分别用什么？
根据使用场景选择：单客户端用 DuckDB 文件作为目录；多个本地客户端用 SQLite；多用户湖仓用 PostgreSQL。本文示例使用 DuckDB 文件，但需注意它只允许单个客户端连接。
如何在 DuckLake 中查询历史版本并恢复误删的数据？
使用 AT (VERSION => n) 子句查询指定快照版本，也可用 AT (TIMESTAMP => ...) 按时间查询。恢复误删数据时，从包含该数据的快照中 INSERT 回表中，例如从 evolved 快照恢复 west 区域订单。
DuckLake 的日常维护需要注意哪些点？
需要定期合并小文件（使用 ducklake_merge_adjacent_files），但旧数据文件不会自动删除，必须过期快照后再清理，可用 CHECKPOINT 语句定期执行。另外，小写入默认内联（最多 10 行），可用 ducklake_flush_inlined_data 移出。
DuckLake 支持索引、主键等约束吗？
不支持。与其他湖仓格式一样，DuckLake 不支持索引、主键、外键、UNIQUE 和 CHECK 约束。
