DuckLake 0.2

Mark Raasveldt

2025-07-04 · 5 分钟

我们DuckLake在一个多月前发布后，收到了社区热烈的积极反响。当然，我们也收到了一系列功能请求。通过 DuckLake 0.2 版本，我们很高兴能展示自那时以来的改进！

我们想先快速提醒一下：DuckLake 一词既指 DuckLake 开放标准，也指 ducklake DuckDB 扩展。在这篇博文中，我们将讨论影响这两者的更新。

DuckDB ducklake 扩展中的更新

用于管理 DuckLake 凭据的 Secrets

现在可以使用 secrets 来管理 DuckLake 凭据。这些 secrets 可以通过标准 secret 基础设施创建，并包含连接到给定 DuckLake 实例所需的所有相关信息。连接到 DuckLake 时，可以将 secret 名称作为参数传入。然后，连接信息会从该 secret 中加载。

命名 Secrets

您可以按如下方式将命名 secret 传递给 DuckLake

CREATE SECRET my_secret (
	TYPE ducklake,
	METADATA_PATH 'metadata.db',
	DATA_PATH 's3://my-s3-bucket/'
);

ATTACH 'ducklake:my_secret';

未命名 Secrets

除了命名 secrets 外，还可以有一个未命名 secret。当使用空连接字符串连接时，将使用此未命名 secret 进行连接

CREATE SECRET (
	TYPE ducklake,
	METADATA_PATH 'metadata.db',
	DATA_PATH 's3://my-s3-bucket/'
);

设置

此版本增加了对 DuckLake 更多设置的支持，特别是关于Parquet 文件写入的设置。现在支持以下设置列表。设置可以全局应用于整个 DuckLake，也可以在每个模式和每个表级别设置。这些设置会持久化到 DuckLake 的 ducklake_metadata 表中。

• parquet_compression：Parquet 文件的压缩算法（无压缩、snappy、gzip、zstd、brotli、lz4）。
• parquet_version：Parquet 格式版本（1 或 2）。
• parquet_compression_level：Parquet 文件的压缩级别。
• parquet_row_group_size：Parquet 文件中每个行组的行数。
• parquet_row_group_size_bytes：Parquet 文件中每个行组的字节数。
• target_file_size：插入和压缩操作的目标数据文件大小。

可以使用 set_option 方法设置

CALL ducklake.set_option('parquet_compression', 'zstd');

可以使用新的 options 函数读取给定 DuckLake 的设置。

FROM ducklake.options();

列出文件

我们添加了ducklake_list_files 函数。此函数返回给定快照中必须扫描的数据和相应删除文件的列表，以便扫描表的数据。这有助于将 DuckLake 集成到其他系统中。

FROM ducklake_list_files('ducklake', 'file');

直接附加 DuckLake

此版本还增加了对使用 duckdb CLI 和其他客户端直接附加 DuckLake 的支持

duckdb ducklake:my_file.db

DuckLake 0.2 标准中的更新

相对模式/表路径

在旧的 DuckLake 标准中，路径总是相对于全局数据路径。在 DuckLake v0.2 标准中，数据和删除文件的写入位置现在有三层

• 数据路径相对于表路径
• 表路径相对于模式路径
• 模式路径相对于全局数据路径

这使得数据文件可以以更结构化的方式写入。默认情况下，模式和表名被设置为文件写入的路径。例如

main/
	my_table/
		ducklake-uuid1.parquet
		ducklake-uuid2.parquet

路径存储在 ducklake_table 和 ducklake_schema 表中。

通过将给定表的所有文件写入指定子目录，现在可以在对象存储级别使用基于前缀的访问控制，从而授予用户仅访问数据库中特定模式或表的权限。

名称映射与添加现有 Parquet 文件

DuckLake 默认使用字段 ID 执行列映射。通过 DuckLake 写入 Parquet 文件时，每个列都包含一个字段 ID，指示它属于哪个顶级列。这允许 DuckLake 执行仅涉及元数据的修改操作，例如重命名和删除字段。

当注册通过其他方式或由其他写入器写入的现有 Parquet 文件时，这些文件通常不包含字段标识符。为了方便在 DuckLake 中使用这些 Parquet 文件，v0.2 增加了一种新的列映射方式，即名称映射。这使得注册 Parquet 文件如下

ATTACH 'ducklake:my_ducklake.db' AS my_ducklake;
CREATE TABLE my_ducklake.people (id BIGINT, name VARCHAR);
COPY (SELECT 42 AS id, 'Mark' AS name) TO 'people.parquet';
CALL ducklake_add_data_files('my_ducklake', 'people', 'people.parquet');

FROM my_ducklake.people;

┌───────┬─────────┐
│  id   │  name   │
│ int64 │ varchar │
├───────┼─────────┤
│  42   │ Mark    │
└───────┴─────────┘

添加到 DuckLake 的每个文件都有一个可选的 mapping_id，它告诉系统列名到字段 ID 的映射关系。由于这是按文件进行的，因此 Parquet 文件可以无限制地添加到 DuckLake。所有 DuckLake 操作都支持已添加的文件，包括模式演进和数据变更流。

设置

DuckLake v0.2 增加了对范围化设置的支持。存储在 ducklake_metadata 表中的设置现在具有一个可选的 scope 字段，以及一个 scope_id。这允许将设置限制在模式或表级别——而不是要求所有设置都全局生效。

分区转换

此版本增加了对年/月/日/小时分区转换的支持，允许直接使用这些函数来分区数据，而无需创建包含这些字段的单独列。

迁移指南

当 DuckDB 连接到运行 v0.1 版本的 DuckLake 时，将自动触发迁移，把 DuckLake 更新到 v0.2。为了执行迁移，会发出以下 SQL 查询。

ALTER TABLE ducklake_schema ADD COLUMN path VARCHAR DEFAULT '';
ALTER TABLE ducklake_schema ADD COLUMN path_is_relative BOOLEAN DEFAULT true;
ALTER TABLE ducklake_table ADD COLUMN path VARCHAR DEFAULT '';
ALTER TABLE ducklake_table ADD COLUMN path_is_relative BOOLEAN DEFAULT true;
ALTER TABLE ducklake_metadata ADD COLUMN scope VARCHAR;
ALTER TABLE ducklake_metadata ADD COLUMN scope_id BIGINT;
ALTER TABLE ducklake_data_file ADD COLUMN mapping_id BIGINT;
CREATE TABLE ducklake_column_mapping (mapping_id BIGINT, table_id BIGINT, type VARCHAR);
CREATE TABLE ducklake_name_mapping (mapping_id BIGINT, column_id BIGINT, source_name VARCHAR, target_field_id BIGINT, parent_column BIGINT);
UPDATE ducklake_partition_column
SET column_id = (SELECT list(column_id ORDER BY column_order)
FROM ducklake_column
WHERE table_id = ducklake_partition_column.table_id AND parent_column IS NULL AND end_snapshot IS NULL)[ducklake_partition_column.column_id + 1];
UPDATE ducklake_metadata
SET value = '0.2'
WHERE key = 'version';