ducklake

DuckLake

DuckLake は、SQL カタログデータベース（PostgreSQL、DuckDB、SQLite）と、あらゆるストレージバックエンド（ローカル、S3、R2、GCS、Azure）上の Parquet データファイルを使用する、オープンなレイクハウス形式です。

変更のたびに不変のスナップショットが作成され、タイムトラベル、変更フィード、競合解決が可能になります。

インストールと接続

INSTALL ducklake;
LOAD ducklake;

-- Local DuckDB catalog + local files
ATTACH 'ducklake:metadata.ducklake' AS my_lake;

-- PostgreSQL catalog + S3 storage
ATTACH 'ducklake:postgres:dbname=ducklake host=myhost' AS my_lake
    (DATA_PATH 's3://my-bucket/data/');

-- Read-only / at specific snapshot
ATTACH 'ducklake:metadata.ducklake' AS my_lake (READ_ONLY);
ATTACH 'ducklake:metadata.ducklake' AS my_lake (SNAPSHOT_VERSION 3);
ATTACH 'ducklake:metadata.ducklake' AS my_lake (SNAPSHOT_TIME '2025-05-26 00:00:00');

基本操作

-- DDL
CREATE SCHEMA my_schema;
CREATE TABLE my_schema.tbl (id INTEGER NOT NULL, name VARCHAR, ts TIMESTAMP);

-- DML
INSERT INTO tbl VALUES (1, 'alice', now());
UPDATE tbl SET name = 'bob' WHERE id = 1;
DELETE FROM tbl WHERE id = 1;

-- Upsert via MERGE INTO (no primary keys in DuckLake)
MERGE INTO target USING source
    ON target.id = source.id
    WHEN MATCHED THEN UPDATE SET name = source.name
    WHEN NOT MATCHED THEN INSERT VALUES (source.id, source.name);

スキーマの進化

すべての変更はメタデータのみを対象とします（ファイルの書き換えはありません）。

ALTER TABLE tbl ADD COLUMN new_col INTEGER;
ALTER TABLE tbl ADD COLUMN new_col VARCHAR DEFAULT 'hello';
ALTER TABLE tbl DROP COLUMN old_col;
ALTER TABLE tbl RENAME old_col TO new_name;
ALTER TABLE tbl ALTER col SET TYPE BIGINT;  -- lossless promotions only

有効な型の昇格：int8->int16/32/64、int16->int32/64、int32->int64、float32->float64。

スナップショットとタイムトラベル

-- List / inspect snapshots
SELECT * FROM my_lake.snapshots();
FROM my_lake.current_snapshot();

-- Add metadata to a snapshot
BEGIN;
INSERT INTO tbl VALUES (1, 'data');
CALL my_lake.set_commit_message('author', 'Description', extra_info => '{"key": "value"}');
COMMIT;

-- Time travel
SELECT * FROM tbl AT (VERSION => 3);
SELECT * FROM tbl AT (TIMESTAMP => now() - INTERVAL '1 week');

-- Change feed between snapshots
FROM my_lake.table_changes('tbl', 2, 5);
FROM my_lake.table_changes('tbl', now() - INTERVAL '1 week', now());

パーティショニング

ALTER TABLE tbl SET PARTITIONED BY (region);
ALTER TABLE tbl SET PARTITIONED BY (year(ts), month(ts));
ALTER TABLE tbl RESET PARTITIONED BY;

関数：identity、year()、month()、day()、hour()。新しいデータにのみ影響します。

メンテナンス

-- All-in-one
CHECKPOINT;

-- Individual operations
CALL ducklake_merge_adjacent_files('my_lake');
CALL ducklake_expire_snapshots('my_lake', older_than => now() - INTERVAL '1 week');
CALL ducklake_cleanup_old_files('my_lake', older_than => now() - INTERVAL '1 week');
CALL ducklake_delete_orphaned_files('my_lake', older_than => now() - INTERVAL '1 week');
CALL ducklake_rewrite_data_files('my_lake', 'tbl', delete_threshold => 0.5);

設定

-- Persistent settings (stored in catalog)
CALL my_lake.set_option('parquet_compression', 'zstd');
CALL my_lake.set_option('target_file_size', '256MB', table_name => 'big_table');

主な設定：parquet_compression（snappy/zstd/gzip）、target_file_size（512MB）、data_inlining_row_limit（0）、encrypted（false）、require_commit_message（false）。

通常の DuckDB との主な違い

• インデックス、主キー、外部キー、一意制約、チェック制約はありません
• INSERT ... ON CONFLICT ではなく MERGE INTO を使用します
• すべてのトランザクションでスナップショットが作成されます
• スキーマの変更はメタデータのみを対象とします
• 削除にはマージオンリードを使用します（インプレース変更ではなく、削除ファイルを使用します）
• 更新は、1 つのトランザクション内で DELETE + INSERT を実行します
• サポートされる制約は NOT NULL のみです