duckdb/ducklake

来源: https://github.com/duckdb/ducklake

DuckDB DuckLake 扩展

DuckLake 是一种开放的 Lakehouse 格式，基于 SQL 和 Parquet 构建。DuckLake 将元数据存储在目录数据库中（https://ducklake.select/docs/stable/duckdb/usage/choosing_a_catalog_database），并将数据存储在 Parquet 文件中。DuckLake 扩展允许 DuckDB 直接从 DuckLake 读取和写入数据。

更多信息请参阅 DuckLake 官方网站（https://ducklake.select）。

安装

DuckLake 可以使用 INSTALL 命令进行安装：

INSTALL ducklake;

最新的开发版本可以从 core_nightly 安装：

FORCE INSTALL ducklake FROM core_nightly;

使用方法

可以使用 ATTACH（https://duckdb.org/docs/stable/sql/statements/attach.html）语法附加 DuckLake 数据库，之后即可使用标准 SQL 创建、修改和查询表。

以下是一个简短的使用示例，将元数据存储在名为 metadata.ducklake 的 DuckDB 数据库文件中，并将数据存储在 file_path 目录下的 Parquet 文件中：

ATTACH 'ducklake:metadata.ducklake' AS my_ducklake (DATA_PATH 'file_path/');
USE my_ducklake;

CREATE TABLE my_ducklake.my_table(id INTEGER, val VARCHAR);
INSERT INTO my_ducklake.my_table VALUES (1, 'Hello'), (2, 'World');

FROM my_ducklake.my_table;
┌───────┬─────────┐
│  id   │   val   │
│ int32 │ varchar │
├───────┼─────────┤
│   1   │  Hello  │
│   2   │  World  │
└───────┴─────────┘

更新

UPDATE my_ducklake.my_table SET val='DuckLake' WHERE id=2;

FROM my_ducklake.my_table;
┌───────┬──────────┐
│  id   │   val    │
│ int32 │ varchar  │
├───────┼──────────┤
│   1   │  Hello   │
│   2   │ DuckLake │
└───────┴──────────┘

时间旅行

FROM my_ducklake.my_table AT (VERSION => 2);
┌───────┬─────────┐
│  id   │   val   │
│ int32 │ varchar │
├───────┼─────────┤
│   1   │  Hello  │
│   2   │  World  │
└───────┴─────────┘

Schema 演进

ALTER TABLE my_ducklake.my_table ADD COLUMN new_column VARCHAR;

FROM my_ducklake.my_table;
┌───────┬──────────┬────────────┐
│  id   │   val    │ new_column │
│ int32 │ varchar  │  varchar   │
├───────┼──────────┼────────────┤
│   1   │  Hello   │    NULL    │
│   2   │ DuckLake │    NULL    │
└───────┴──────────┴────────────┘

变更数据流（Change Data Feed）

FROM my_ducklake.table_changes('my_table', 2, 2);
┌─────────────┬───────┬─────────────┬───────┬─────────┐
│ snapshot_id │ rowid │ change_type │  id   │   val   │
│   int64     │ int64 │  varchar    │ int32 │ varchar │
├─────────────┼───────┼─────────────┼───────┼─────────┤
│      2      │   0   │   insert    │   1   │  Hello  │
│      2      │   1   │   insert    │   2   │  World  │
└─────────────┴───────┴─────────────┴───────┴─────────┘

更多信息请参阅使用指南（https://ducklake.select/docs/stable/duckdb/introduction）。

构建与加载扩展

构建时执行：

git submodule init
git submodule update --recursive
# 如需多核构建，请使用 `make GEN=ninja release`
make

子模块被固定在 .github/duckdb-version 中指定的 DuckDB 版本上，这也是 CI 构建所使用的版本。make pull 则会将子模块切换到各自分支的最新提交，此时构建可能会失败。

运行方式为执行捆绑的 duckdb shell：

./build/release/duckdb

贡献

我们欢迎对 DuckLake 扩展的外部贡献。目前活跃的开发分支是 main，所有贡献都应提交到该分支。

测试

# 运行所有 DuckLake 扩展测试
./build/release/test/unittest

# 运行单个测试文件
./build/release/test/unittest test/sql/transaction/create_conflict.test

# 运行匹配特定模式的测试
./build/release/test/unittest "test/sql/partitioning/*"

# 使用 DuckLake 作为存储后端运行 DuckDB 核心测试
./build/release/test/unittest --test-config test/configs/attach_ducklake.json --test-dir duckdb

# 使用 PostgreSQL 作为目录数据库运行 DuckLake 测试（需要运行中的 PostgreSQL）
./build/release/test/unittest --test-config test/configs/postgres.json

# 使用 SQLite 作为目录数据库运行 DuckLake 测试
./build/release/test/unittest --test-config test/configs/sqlite.json

# 启用删除向量（deletion vectors）运行测试
./build/release/test/unittest --test-config test/configs/deletion_vectors.json