Iceberg 함수

Iceberg 함수 (Iceberg Functions)

iceberg 익스텐션은 다음 함수를 제공해요. Iceberg 테이블을 스캔하고 메타데이터, 스냅샷, 프로퍼티를 조회하는 유용한 함수들이에요.

출처: 문서

본문

iceberg 익스텐션은 다음 함수를 제공해요:

이 페이지의 예시는 iceberg_data.zip 파일을 사용해요. 실행하려면 다운로드하고 압축을 풀어요.

iceberg_scan

iceberg_scan 함수는 연결된 카탈로그 없이 경로에서 Iceberg 테이블을 읽어요:

SELECT count(*)
FROM iceberg_scan('data/iceberg/lineitem_iceberg', allow_moved_paths = true);

경로는 메타데이터 파일을 직접 가리킬 수도 있고, S3나 Azure Blob Storage 같은 객체 스토어를 가리킬 수도 있어요. 이 함수가 받는 파라미터는 Iceberg Options 페이지를 참고해요.

iceberg_metadata

Iceberg 메타데이터에 접근하려면 iceberg_metadata 함수를 사용할 수 있어요:

SELECT *
FROM iceberg_metadata('data/iceberg/lineitem_iceberg', allow_moved_paths = true);

iceberg_snapshots

Iceberg 테이블의 스냅샷을 시각화하려면 iceberg_snapshots 함수를 사용해요:

SELECT *
FROM iceberg_snapshots('data/iceberg/lineitem_iceberg');

iceberg_snapshots는 allow_moved_paths, snapshot_from_id, snapshot_from_timestamp를 파라미터로 받지 않아요.

연결된 카탈로그의 메타데이터 연산 (Metadata Operations on Attached Catalogs)

iceberg_metadata와 iceberg_snapshots 함수는 연결된 Iceberg 카탈로그에서 정규화된 경로로도 사용할 수 있어요. 예:

SELECT * FROM iceberg_metadata(my_datalake.default.t)

-- 또는
SELECT * FROM iceberg_snapshots(my_datalake.default.t)

이 기능으로 사용자는 **시간 여행(time traveling)**을 할 수 있어요.

-- 스냅샷 id 사용
SELECT * FROM my_datalake.default.t AT (VERSION => ⟨SNAPSHOT_ID⟩)

-- 또는 타임스탬프 사용
SELECT * FROM my_datalake.default.t AT (TIMESTAMP => TIMESTAMP '2025-09-22 12:32:43.217')

테이블 프로퍼티 함수 (Table Properties Functions)

DuckDB는 Iceberg 테이블 프로퍼티를 보고 수정하는 함수를 제공해요:

ALTER TABLE ... SET와 ALTER TABLE ... RESET로 테이블 프로퍼티를 수정할 수 있어요

-- 테이블 프로퍼티 보기
SELECT *
FROM iceberg_table_properties(iceberg_catalog.default.my_table);

-- 테이블 프로퍼티 설정
ALTER TABLE iceberg_catalog.default.my_table SET (
    'write.update.mode'='merge-on-read', 
    'write.delete.mode'='merge-on-read',
    'format-version'=3
);

-- 테이블 프로퍼티 제거
ALTER TABLE iceberg_catalog.default.my_table RESET (
    'write.update.mode',
    'owner'
);

스키마 프로퍼티 함수 (Schema Properties Functions)

Iceberg 카탈로그는 임의의 키-값 프로퍼티를 스키마(namespace) 수준에서 연결할 수 있어요. 이 프로퍼티는 일반적으로 소유권, 설명, 기본 저장 위치, 또는 스키마의 모든 테이블에 적용되는 기타 메타데이터를 기록하는 데 사용돼요.

-- 스키마 프로퍼티 설정
CALL set_iceberg_schema_properties(iceberg_catalog.default, {
    'owner': 'analytics-team',
    'description': 'Default analytics schema'
});

-- 스키마 프로퍼티 읽기
SELECT * FROM iceberg_schema_properties(iceberg_catalog.default);

-- 스키마 프로퍼티 제거
CALL remove_iceberg_schema_properties(
    iceberg_catalog.default,
    ['description']
);

스키마 프로퍼티는 Iceberg REST Catalog를 통해 쓰여지므로, 같은 카탈로그에 연결된 다른 Iceberg 인식 엔진도 업데이트를 즉시 볼 수 있어요. remove_iceberg_schema_properties는 남은 스키마 프로퍼티 수를 반환해요.

iceberg_to_ducklake

DuckDB iceberg 익스텐션은 Iceberg 메타데이터를 DuckLake로 메타데이터 전용 복사를 하는 함수를 노출해요. 이를 통해 사용자는 Iceberg 테이블을 DuckLake 테이블처럼 쿼리할 수 있어요.

-- Iceberg 카탈로그가 iceberg_datalake로 별칭되어 연결되어 있다고 가정
ATTACH 'ducklake:my_ducklake.ducklake' AS my_ducklake;

CALL iceberg_to_ducklake('iceberg_datalake', 'my_ducklake');

skip_tables 파라미터를 제공해 테이블 집합을 건너뛸 수도 있어요.

CALL iceberg_to_ducklake('iceberg_datalake', 'my_ducklake', skip_tables := ['table_to_skip']);

더 알아보기 (Learn more)

• Iceberg Options — 스캔 옵션 상세.
• Iceberg 카탈로그 — 카탈로그 연결과 시간 여행.