액세스 방법 선택
테이블 함수
icebergAzure, icebergLocal 및 다른 포맷의 대응 항목)이 있습니다. 전체 목록은 직접 쿼리하기를 참조하십시오.
Paimon은 테이블 함수만 제공합니다.
테이블 엔진
DataLakeCatalog 데이터베이스 엔진
다중 부분 테이블 이름에 사용하는 백틱카탈로그는 흔히
database.table 명명 방식을 사용합니다. 위 예시와 같이 데이터베이스가 포함된 이름은 백틱으로 감싸십시오.필수 설정
CREATE DATABASE가 권한 오류로 실패하는 경우 서비스 버전을 확인하십시오.
카탈로그 연결의 경우 카탈로그 유형마다 별도의 플래그가 있습니다. 개요는 카탈로그 연결하기를, 설정 세부 정보는 DataLakeCatalog 참고를 참조하십시오. 카탈로그별 설정 방법은 카탈로그 가이드에 나와 있습니다.
쓰기의 경우 Iceberg에는 allow_insert_into_iceberg가 필요합니다(25.7+, 26.2부터 베타). 자세한 내용은 데이터 레이크에 쓰기를 참조하십시오. Delta Lake에는 allow_delta_lake_writes가 필요합니다(25.9+). 지원 매트릭스에는 각 포맷과 작업에 적용되는 플래그가 정리되어 있습니다.
쿼리 성능 개선
쿼리 작성 습관
WHERE 절에서는 파티션 컬럼을 기준으로 필터링하세요. Iceberg와 Delta Lake는 쿼리 계획 단계에서 ClickHouse가 관련 없는 파일을 건너뛸 수 있도록 파티션 메타데이터를 저장합니다. 필터 대상이 파티션 사양에 포함되지 않은 컬럼이면 ClickHouse는 해당하는 모든 파일을 스캔합니다.
숨겨진 파티셔닝을 사용하는 Iceberg 테이블에서는 별도의 파티션 컬럼이나 변환된 필드 이름이 아니라 테이블 스키마의 원본 컬럼을 기준으로 필터링하세요. 예를 들어 테이블이 day(event_time)로 파티셔닝되어 있다면 event_time에 프레디케이트를 추가하세요. 그러면 ClickHouse는 Iceberg 파티션 사양을 사용해 해당 필터로부터 파티션 프루닝을 수행합니다. 자세한 내용은 Partition pruning 및 Iceberg spec을 참고하세요.
SELECT * 대신 필요한 컬럼만 나열하십시오. ClickHouse는 객체 스토리지에서 Parquet를 컬럼별로 읽기 때문에, 조회하는 컬럼이 적을수록 전송 및 압축 해제되는 바이트 수가 줄어듭니다.
선택도가 높은 필터는 WHERE에 두십시오. ClickHouse 26.2+부터는 PREWHERE도 Iceberg 및 기타 데이터 레이크 테이블 읽기에서 지원되며, 나머지 컬럼을 읽기 전에 Parquet 레이어에서 먼저 필터링합니다. 파티션 프루닝은 여전히 PREWHERE만으로는 결정되지 않으며, 파티션 소스 컬럼을 필터링해야 합니다.
Position deletes 또는 equality deletes가 많은 Iceberg 테이블은 스캔 중에 merge-on-read 필터링을 적용합니다. 매니페스트 프루닝만 기준으로 예상하는 것보다 파일당 더 많은 작업이 필요할 수 있습니다.
여러 노드로 구성된 배포에서는 파일 읽기를 레플리카 전체에 분산하기 위해 cluster 테이블 함수를 사용하십시오.
다중 노드 클러스터에서의 병렬 읽기
'default'). 지원되는 모든 포맷에 대해 클러스터용 변형이 제공됩니다:
클러스터 읽기는 다른 성능 설정과 함께 사용할 수도 있습니다.
배치 읽기를 스냅샷 범위로 제한
- Iceberg의 경우 iceberg_snapshot_id 또는 iceberg_timestamp_ms (25.4+)를 사용해 특정 시점의 뷰를 읽으십시오. 추가 전용 테이블에서는 스냅샷 설정을
WHERE의 파티션 필터와 함께 사용하십시오. 실행 사이의 스냅샷 ID를 조회하려면 system.iceberg_history (25.6+)를 사용하십시오. - Delta Lake의 경우 delta_lake_snapshot_start_version 및 delta_lake_snapshot_end_version (25.12+)를 사용해 두 버전 사이의 변경 사항을 읽으십시오. 단일 스냅샷을 읽으려면 delta_lake_snapshot_version (25.8+)을 사용하십시오. CDF 예시는 Delta change data feed를 참조하십시오.
Parquet 파일을 로컬에 캐시하기
enable_filesystem_cache = 0으로 설정하십시오.
Apache Iceberg
읽기 설정
카탈로그 지연 시간 줄이기
- 테이블 생성 시 iceberg_metadata_async_prefetch_period_ms를 설정하여 백그라운드에서 메타데이터를 프리페치합니다.
- 쿼리에서 iceberg_metadata_staleness_ms(26.3+)를 설정하여 카탈로그 왕복을 생략하는 대신 약간 오래된 메타데이터를 허용합니다.
0이면 항상 최신 메타데이터를 가져옵니다. 테이블이 자주 변경되지 않는 읽기 비중이 높은 워크로드에서는 윈도우를 늘리십시오.
ClickHouse가 잘못된 메타데이터 파일을 선택하는 경우(테이블 경로에 .metadata.json 파일이 여러 개 있는 경우), 테이블 생성 시 iceberg_metadata_file_path (25.4+) 또는 iceberg_metadata_table_uuid를 사용해 해상도를 고정하십시오. Metadata file resolution을 참조하십시오.
시간 여행
Iceberg 쓰기
데이터 레이크에 쓰기 및 Iceberg 엔진 참고를 참조하십시오.
Delta Lake
Delta Kernel
읽기 설정
삭제 벡터가 있는 테이블(26.2+)은 읽기 중에 행 수준 필터링을 적용합니다. ClickHouse가 이를 자동으로 처리하지만, DV가 많은 테이블을 스캔할 때는 파일당 처리 작업이 더 늘어납니다.
Delta 변경 데이터 피드
delta.enableChangeDataFeed)가 활성화되어 있어야 합니다. 쿼리 설정에 시작 버전과 종료 버전을 모두 지정하십시오. 종료 버전만 설정하면 오류가 발생합니다.
_change_type, _commit_version, _commit_timestamp)이 포함됩니다. 대상 테이블(target table)에 로드하기 전에 이 컬럼들을 처리하십시오. 일반적인 스냅샷 패턴은 배치 읽기를 스냅샷에 고정하기를 참조하십시오.
Delta Lake 쓰기
레이크 쿼리 디버깅
카탈로그 연결 확인
DataLakeCatalog로 CREATE DATABASE를 실행해도 자격 증명은 검증되지 않습니다. 카탈로그 연결이 끊어진 상태에서도 데이터베이스는 존재할 수 있습니다. ClickHouse 26.4부터는 경량 상태 점검을 실행하십시오:
SHOW TABLES FROM my_lake로 연결 상태를 확인하고 오류 메시지를 살펴보십시오. 확인된 스토리지 경로와 엔진 유형을 검증하려면 백틱으로 묶은 테이블 이름과 함께 SHOW CREATE TABLE을 사용하십시오:
system.tables에 보이지 않으면 show_remote_databases_in_system_tables를 활성화하십시오(25.8+). 카탈로그 테이블은 기본적으로 시스템 내부 검사에서 숨겨집니다. 26.6 이전 버전에서는 이전 이름인 show_data_lake_catalogs_in_system_tables를 사용하십시오.
읽히는 파일 확인
_path, _file, _size, _time, _etag)을 노출합니다. _path로 그룹화하여 파티션 프루닝이 제대로 작동하는지, 또는 쿼리가 예상보다 더 많은 파일을 스캔하는지 확인하십시오. 숨겨진 파티셔닝이 있는 Iceberg 테이블에서는 별도의 파티션 컬럼이 아니라 원본 컬럼(예: event_time)에 필터를 적용하십시오:
스캔량 확인
read_rows와 read_bytes를 비교하십시오. ReadBufferFromS3Bytes 및 CachedReadBufferReadFromCacheBytes 같은 ProfileEvents는 객체 스토리지와 로컬 캐시에서 각각 얼마나 많은 데이터를 읽어 왔는지 보여줍니다. query_log와 EXPLAIN에 대한 전체 설명은 쿼리 최적화를 참조하십시오.
벤치마크할 때는 실행 간 차이가 캐시 적중으로 가려지지 않도록 enable_filesystem_cache를 비활성화하십시오.
메타데이터 로그
로깅을 활성화한 상태로 쿼리를 실행하고, 로그를 플러시한 다음, 해당
query_id의 항목을 확인하십시오:
clusterAllReplicas를 사용하십시오.
Verbose Iceberg 로그 레벨은 manifest 목록과 파일의 메타데이터 캐싱을 비활성화하므로, 동일한 테이블에 대한 후속 쿼리가 느려집니다. 높은 상세 수준은 실제로 조사 중일 때만 사용하십시오. Delta Lake 프레디케이트 문제의 경우, 커널이 filter를 푸시다운하지 못할 때 즉시 실패하도록 delta_lake_throw_on_engine_predicate_error (25.8+)를 활성화하십시오.
컬럼 세부 정보와 상세 수준 옵션은 iceberg_metadata_log 및 delta_lake_metadata_log 참고 페이지를 참조하십시오.
다음 단계
- 시작하기 — 직접 쿼리부터 데이터 다시 쓰기까지 전 과정을 안내합니다
- 직접 쿼리하기 — 4가지 포맷 전체에 대한 테이블 함수, 엔진, 클러스터 변형
- 카탈로그 연결하기 — Unity Catalog를 사용하는
DataLakeCatalog설정 - 데이터 레이크에 쓰기 — Iceberg와 Delta Lake에 데이터를 다시 씁니다
- 지원 매트릭스 — 포맷, 카탈로그, 스토리지 백엔드 전반의 기능 비교