Iceberg 확장 함수·설정 참조

Iceberg 확장 함수·설정 참조 (Functions and Settings Reference)

이 페이지는 [iceberg 확장]({% link docs/current/core_extensions/iceberg/overview.md %})이 제공하는 모든 함수와 설정에 대한 참조예요. 작업 지향 문서는 [Overview]({% link docs/current/core_extensions/iceberg/overview.md %})(읽기), [Writing to Iceberg]({% link docs/current/core_extensions/iceberg/writing.md %}), [Iceberg REST Catalogs]({% link docs/current/core_extensions/iceberg/iceberg_rest_catalogs.md %}) 페이지를 참고해요.

테이블을 받는 함수는 테이블 메타데이터의 경로(예: 'data/iceberg/lineitem_iceberg') 또는, [카탈로그가 연결되어 있으면]({% link docs/current/core_extensions/iceberg/iceberg_rest_catalogs.md %}) 완전히 한정된 테이블 이름(예: my_catalog.default.my_table)을 받아요.

출처: 문서

본문

공통 파라미터

아래 읽기 및 메타데이터 테이블 함수는 다음 명명된 파라미터를 받아요:

파라미터	타입	기본값	설명
`allow_moved_paths`	`BOOLEAN`	`false`	이동된 Iceberg 테이블의 스캔을 허용해요
`metadata_compression_codec`	`VARCHAR`	`''`	gzip-압축 메타데이터 파일을 읽으려면 `'gzip'`으로 설정
`snapshot_from_id`	`UBIGINT`	`NULL`	특정 `id`를 가진 스냅샷에 접근
`snapshot_from_timestamp`	`TIMESTAMP`	`NULL`	특정 `timestamp` 시점의 스냅샷에 접근
`version`	`VARCHAR`	`'?'`	명시적 버전 문자열, 힌트 파일, 또는 추측용 `'?'`
`version_name_format`	`VARCHAR`	`'v%s%s.metadata.json,%s%s.metadata.json'`	버전을 메타데이터 파일 이름으로 변환하는 방법 제어

자세한 내용은 [Selecting Metadata Versions]({% link docs/current/core_extensions/iceberg/overview.md %}#selecting-metadata-versions)를 참고해요.

읽기 및 메타데이터 함수

함수	설명
`iceberg_scan(table, ⟨options⟩)`	Iceberg 테이블의 데이터를 읽어요. 테이블의 컬럼을 반환해요.
`iceberg_metadata(table, ⟨options⟩)`	매니페스트 항목당 한 행을 반환해요. 컬럼: `manifest_path`, `manifest_sequence_number`, `manifest_content`, `status`, `content`, `file_path`, `file_format`, `record_count`.
`iceberg_snapshots(table, ⟨options⟩)`	스냅샷당 한 행을 반환해요. 컬럼: `sequence_number`, `snapshot_id`, `timestamp_ms`, `manifest_list`.
`iceberg_column_stats(table, ⟨options⟩)`	데이터 파일별·컬럼별 통계를 반환해요. 컬럼: `file_path`, `column_name`, `column_type`, `lower_bound`, `upper_bound`, `value_count`, `null_value_count`, `nan_value_count`.
`iceberg_partition_stats(table, ⟨options⟩)`	파티션 필드별 통계를 반환해요. 컬럼: `partition_field_name`, `partition_source_columns`, `partition_field_transform`, `lower_bound`, `upper_bound`.
`iceberg_load_table_response(table)`	고급, REST-catalog 전용. 원시 카탈로그 `LoadTable` 응답을 반환해요: `metadata_location`, `metadata` (`VARIANT`), `config` (`MAP`), `storage_credentials`, `request_url`.

SELECT * FROM iceberg_snapshots('data/iceberg/lineitem_iceberg');
SELECT * FROM iceberg_column_stats('my_catalog.default.events');

테이블 및 스키마 프로퍼티 함수

이 함수들은 Iceberg 테이블 프로퍼티와 Iceberg 스키마(네임스페이스) 프로퍼티를 읽고 수정해요. 연결된 카탈로그가 필요해요. [Writing to Iceberg]({% link docs/current/core_extensions/iceberg/writing.md %}#table-properties)를 참고해요.

함수	설명
`iceberg_table_properties(table)`	테이블의 모든 프로퍼티를 반환해요.
`set_iceberg_table_properties(table, properties)`	테이블에 프로퍼티를 설정해요. `properties`는 `MAP(VARCHAR, VARCHAR)`예요.
`remove_iceberg_table_properties(table, property_list)`	테이블에서 나열된 프로퍼티(`VARCHAR[]`)를 제거해요.
`iceberg_schema_properties(schema)`	스키마(네임스페이스)의 모든 프로퍼티를 반환해요.
`set_iceberg_schema_properties(schema, properties)`	스키마에 프로퍼티를 설정해요.
`remove_iceberg_schema_properties(schema, property_list)`	스키마에서 나열된 프로퍼티를 제거해요.

DuckLake 상호운용성

함수	설명
`iceberg_to_ducklake(iceberg_catalog, ducklake_catalog, skip_tables := [...])`	연결된 Iceberg 카탈로그의 메타데이터 전용 복사를 [DuckLake]({% link docs/current/core_extensions/ducklake.md %}) 카탈로그로 수행해요. 선택적 `skip_tables` 파라미터(`VARCHAR[]`)는 테이블을 제외해요.

[Interoperability with DuckLake]({% link docs/current/core_extensions/iceberg/overview.md %}#interoperability-with-ducklake)를 참고해요.

파티션 변환 함수

이 스칼라 함수들은 Iceberg 파티션 변환을 구현해요. 주로 PARTITIONED BY 절에서 사용되지만([Partitioning]({% link docs/current/core_extensions/iceberg/writing.md %}#partitioning) 참고), 직접 호출할 수도 있어요.

함수	설명
`iceberg_bucket(num_buckets, value)`	`value`에 대한 Iceberg bucket 파티션 값(`INTEGER`)을 반환해요. 지원되는 `value` 타입: `INTEGER`, `BIGINT`, `DECIMAL`, `DATE`, `TIME`, `TIMESTAMP`, `TIMESTAMP WITH TIME ZONE`, `TIMESTAMP_NS`, `VARCHAR`, `BLOB`, `UUID`.
`iceberg_truncate(width, value)`	`value`와 같은 타입으로 `value`에 대한 Iceberg truncate 파티션 값을 반환해요. 지원되는 타입: `INTEGER`, `BIGINT`, `DECIMAL`, `VARCHAR`, `BLOB`.

SELECT iceberg_bucket(16, 'duckdb');
SELECT iceberg_truncate(10, 1234);

설정 (Settings)

설정	타입	기본값	설명
`unsafe_enable_version_guessing`	`BOOLEAN`	`false`	(가능하면) 파일시스템을 globbing해 최신 메타데이터 버전을 찾는 것을 활성화해요. 커밋되지 않은 버전을 읽을 수 있으므로 기본적으로 비활성화돼요.
`iceberg_use_metadata_log`	`BOOLEAN`	`true`	테이블의 선택적 `metadata-log`를 사용해 원자성 보장을 지켜요. 드문 경우에 추가 메타데이터 `GET`을 희생해요.
`ignore_target_file_size_for_partitioned_tables`	`BOOLEAN`	`false`	파티션 테이블에서 지원되지 않는 `write.target-file-size-bytes` 테이블 프로퍼티를 오류를 내는 대신 무시해요.
`ignore_row_group_size_for_partitioned_tables`	`BOOLEAN`	`false`	파티션 테이블에서 지원되지 않는 `write.parquet.row-group-size-bytes` 테이블 프로퍼티를 오류를 내는 대신 무시해요.
`iceberg_via_aws_sdk_for_catalog_interactions`	`BOOLEAN`	`false`	DuckDB의 HTTP 클라이언트 대신 레거시 AWS SDK 코드 경로를 사용해 AWS 기반 카탈로그와 상호작용해요.

더 알아보기 (Learn more)

Iceberg 확장의 전체 개요는 [Iceberg extension]({% link docs/current/core_extensions/iceberg/overview.md %}) 문서를 참고해요.