DuckLake

ducklake 익스텐션은 DuckLake 형식으로 저장된 데이터베이스에 연결(attach)하는 기능을 추가해요. 이 익스텐션의 전체 문서는 DuckLake 웹사이트에서 볼 수 있어요.

DuckLake 1.0은 2026년 4월에 출시됐어요. 발표 블로그 글을 읽어보세요.

출처: 문서

본문

설치와 로드 (Installing and Loading)

ducklake를 설치하려면:

INSTALL ducklake;

ducklake 익스텐션은 ATTACH 절에서 처음 사용할 때 투명하게 자동 로드돼요. 수동으로 로드하고 싶다면:

LOAD ducklake;

사용법 (Usage)

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

테이블 (Tables)

DuckDB에서 ducklake 익스텐션은 my_ducklake{:.language-sql .highlight}라는 이름의 DuckLake에 대한 카탈로그 테이블을 __ducklake_metadata_⟨my_ducklake⟩{:.language-sql .highlight} 카탈로그에 저장해요.

함수 (Functions)

DuckLake는 여러 함수를 등록한다는 점을 참고해요. 이 함수들은 카탈로그 이름을 첫 번째 인자로 호출해야 해요. 예:

FROM ducklake_snapshots('my_ducklake');

┌─────────────┬────────────────────────────┬────────────────┬──────────────────────────┐
│ snapshot_id │       snapshot_time        │ schema_version │         changes          │
│    int64    │  timestamp with time zone  │     int64      │ map(varchar, varchar[])  │
├─────────────┼────────────────────────────┼────────────────┼──────────────────────────┤
│      0      │ 2025-05-26 11:41:10.838+02 │       0        │ {schemas_created=[main]} │
└─────────────┴────────────────────────────┴────────────────┴──────────────────────────┘

`ducklake_snapshots`

catalog 이름의 DuckLake 카탈로그에 저장된 스냅샷을 반환해요.

파라미터 이름	파라미터 타입	명명된 파라미터	설명
`catalog`	`VARCHAR`	no

정보는 다음 스키마의 테이블로 인코딩돼요:

컬럼 이름	컬럼 타입
`snapshot_id`	`BIGINT`
`snapshot_time`	`TIMESTAMP WITH TIME ZONE`
`schema_version`	`BIGINT`
`changes`	`MAP(VARCHAR, VARCHAR[])`

`ducklake_table_info`

ducklake_table_info 함수는 catalog라는 이름의 DuckLake 카탈로그에 저장된 테이블에 대한 정보를 반환해요.

파라미터 이름	파라미터 타입	명명된 파라미터	설명
`catalog`	`VARCHAR`	no

정보는 다음 스키마의 테이블로 인코딩돼요:

컬럼 이름	컬럼 타입
`table_name`	`VARCHAR`
`schema_id`	`BIGINT`
`table_id`	`BIGINT`
`table_uuid`	`UUID`
`file_count`	`BIGINT`
`file_size_bytes`	`BIGINT`
`delete_file_count`	`BIGINT`
`delete_file_size_bytes`	`BIGINT`

`ducklake_table_insertions`

ducklake_table_insertions 함수는 주어진 테이블에서 주어진 버전 또는 타임스탬프의 스냅샷 사이에 삽입된 행을 반환해요. start_snapshot과 end_snapshot의 타입이 BIGINT인지 TIMESTAMP WITH TIME ZONE인지에 따라 두 가지 변형이 있어요.

파라미터 이름	파라미터 타입	명명된 파라미터
`catalog`	`VARCHAR`	no
`schema_name`	`VARCHAR`	no
`table_name`	`VARCHAR`	no
`start_snapshot`	`BIGINT` / `TIMESTAMP WITH TIME ZONE`	no
`end_snapshot`	`BIGINT` / `TIMESTAMP WITH TIME ZONE`	no

함수가 반환하는 테이블의 스키마는 테이블 table_name의 스키마와 동일해요.

`ducklake_table_deletions`

ducklake_table_deletions 함수는 주어진 테이블에서 주어진 버전 또는 타임스탬프의 스냅샷 사이에 삭제된 행을 반환해요. start_snapshot과 end_snapshot의 타입이 BIGINT인지 TIMESTAMP WITH TIME ZONE인지에 따라 두 가지 변형이 있어요.

파라미터 이름	파라미터 타입	명명된 파라미터
`catalog`	`VARCHAR`	no
`schema_name`	`VARCHAR`	no
`table_name`	`VARCHAR`	no
`start_snapshot`	`BIGINT` / `TIMESTAMP WITH TIME ZONE`	no
`end_snapshot`	`BIGINT` / `TIMESTAMP WITH TIME ZONE`	no

함수가 반환하는 테이블의 스키마는 테이블 table_name의 스키마와 동일해요.

`ducklake_table_changes`

ducklake_table_changes 함수는 주어진 테이블에서 주어진 버전 또는 타임스탬프의 스냅샷 사이에 변경된 행을 반환해요. start_snapshot과 end_snapshot의 타입이 BIGINT인지 TIMESTAMP WITH TIME ZONE인지에 따라 두 가지 변형이 있어요.

파라미터 이름	파라미터 타입	명명된 파라미터
`catalog`	`VARCHAR`	no
`schema_name`	`VARCHAR`	no
`table_name`	`VARCHAR`	no
`start_snapshot`	`BIGINT` / `TIMESTAMP WITH TIME ZONE`	no
`end_snapshot`	`BIGINT` / `TIMESTAMP WITH TIME ZONE`	no

함수가 반환하는 테이블의 스키마는 테이블 table_name의 스키마에 다음 세 컬럼을 더한 것이에요.

컬럼 이름	컬럼 타입	설명
`snapshot_id`	`BIGINT`
`rowid`	`BIGINT`
`change_type`	`VARCHAR`	변경 유형: `insert` 또는 `delete`

명령 (Commands)

`ducklake_cleanup_old_files`

ducklake_cleanup_old_files 함수는 catalog가 나타내는 DuckLake에서 오래된 파일을 정리해요. 성공하면 단일 컬럼(Success)과 0행의 테이블을 반환해요.

파라미터 이름	파라미터 타입	명명된 파라미터
`catalog`	`VARCHAR`	no
`cleanup_all`	`BOOLEAN`	yes
`dry_run`	`BOOLEAN`	yes
`older_than`	`TIMESTAMP WITH TIME ZONE`	yes

`ducklake_expire_snapshots`

ducklake_expire_snapshots 함수는 versions 파라미터로 지정된 버전 또는 older_than 파라미터보다 오래된 스냅샷을 만료시켜요. 성공하면 단일 컬럼(Success)과 0행의 테이블을 반환해요.

파라미터 이름	파라미터 타입	명명된 파라미터
`catalog`	`VARCHAR`	no
`versions`	`UBIGINT[]`	yes
`older_than`	`TIMESTAMP WITH TIME ZONE`	yes

`ducklake_merge_adjacent_files`

ducklake_merge_adjacent_files 함수는 스토리지에서 인접한 파일을 병합해요. 성공하면 단일 컬럼(Success)과 0행의 테이블을 반환해요.

파라미터 이름	파라미터 타입	명명된 파라미터	설명
`catalog`	`VARCHAR`	no

호환성 매트릭스 (Compatibility Matrix)

DuckLake 사양과 ducklake DuckDB 익스텐션은 현재 함께 출시돼요. 호환성 매트릭스를 참고해요.

더 알아보기 (Learn more)

DuckLake 웹사이트 — 익스텐션 전체 문서.
DuckLake 사양 — 카탈로그 테이블 형식.