구성

구성 (Configuration)

아이스버그 테이블은 읽기·쓰기 동작을 설정하는 테이블 속성(table properties)을 지원해요. 이 문서에서는 읽기 속성, 쓰기 속성, 암호화 속성, 테이블 동작 속성, 예약 속성, 정보 속성, 호환성 플래그까지 테이블 구성에 필요한 모든 속성을 표로 정리해드릴게요. 각 속성의 기본값과 설명을 알면 테이블 동작을 원하는 대로 미세하게 조정할 수 있어요.

출처: 문서

본문

테이블 속성 (Table properties)

아이스버그 테이블은 읽기용 기본 스플릿 크기 같은 테이블 동작을 설정하는 테이블 속성을 지원해요.

읽기 속성 (Read properties)

속성 기본값 설명
read.split.target-size 134217728 (128 MB) 데이터 입력 스플릿을 결합할 때의 목표 크기
read.split.metadata-target-size 33554432 (32 MB) 메타데이터 입력 스플릿을 결합할 때의 목표 크기
read.split.planning-lookback 10 입력 스플릿을 결합할 때 고려할 빈(bin)의 개수
read.split.open-file-cost 4194304 (4 MB) 파일을 여는 데 드는 예상 비용. 스플릿 결합 시 최소 가중치로 사용돼요.
read.parquet.vectorization.enabled true Parquet 벡터화 읽기를 사용할지 여부를 제어해요
read.parquet.vectorization.batch-size 5000 Parquet 벡터화 읽기의 배치 크기
read.orc.vectorization.enabled false ORC 벡터화 읽기를 사용할지 여부를 제어해요
read.orc.vectorization.batch-size 5000 ORC 벡터화 읽기의 배치 크기

쓰기 속성 (Write properties)

속성 기본값 설명
write.format.default parquet 테이블의 기본 파일 포맷; parquet, avro 또는 orc
write.delete.format.default data file format 테이블의 기본 삭제 파일 포맷; parquet, avro 또는 orc
write.parquet.row-group-size-bytes 134217728 (128 MB) Parquet 행 그룹 크기
write.parquet.page-size-bytes 1048576 (1 MB) Parquet 페이지 크기
write.parquet.page-version v1 Parquet 데이터 페이지 버전: v1 (DataPage V1) 또는 v2 (DataPage V2)
write.parquet.page-row-limit 20000 Parquet 페이지 행 제한
write.parquet.dict-size-bytes 2097152 (2 MB) Parquet 딕셔너리 페이지 크기
write.parquet.compression-codec zstd Parquet 압축 코덱: zstd, brotli, lz4, gzip, snappy, uncompressed
write.parquet.compression-level null Parquet 압축 수준
write.parquet.shred-variants false true이면 variant 컬럼이 쿼리 성능 향상을 위해 분쇄된(shredded) Parquet 인코딩으로 쓰여져요
write.parquet.variant-inference-buffer-size 100 variant 분쇄가 활성화될 때 스키마 추론을 위해 버퍼링할 행 수
write.parquet.bloom-filter-enabled.column.col1 (not set) 'col1' 컬럼에 블룸 필터를 쓰도록 Parquet에 힌트
write.parquet.bloom-filter-max-bytes 1048576 (1 MB) 블룸 필터 비트셋의 최대 바이트 수
write.parquet.bloom-filter-fpp.column.col1 0.01 'col1'에 적용되는 블룸 필터의 오탐(false positive) 확률 (0.0보다 크고 1.0보다 작아야 해요)
write.parquet.bloom-filter-ndv.column.col1 (not set) 'col1'에 적용되는 블룸 필터의 예상 고유 값 개수 (0보다 커야 해요)
write.parquet.stats-enabled.column.col1 (not set) 'col1' 컬럼에 대한 Parquet 컬럼 통계 수집 여부를 제어해요
write.avro.compression-codec gzip Avro 압축 코덱: gzip(9단계 deflate), zstd, snappy, uncompressed
write.avro.compression-level null Avro 압축 수준
write.orc.stripe-size-bytes 67108864 (64 MB) 기본 ORC 스트라이프 크기(바이트) 정의
write.orc.block-size-bytes 268435456 (256 MB) ORC 파일의 기본 파일 시스템 블록 크기 정의
write.orc.compression-codec zlib ORC 압축 코덱: zstd, lz4, lzo, zlib, snappy, none
write.orc.compression-strategy speed ORC 압축 전략: speed, compression
write.orc.bloom.filter.columns (not set) 블룸 필터를 만들어야 하는 컬럼 이름의 쉼표 구분 목록
write.orc.bloom.filter.fpp 0.05 블룸 필터의 오탐 확률 (0.0보다 크고 1.0보다 작아야 해요)
write.location-provider.impl null LocationProvider를 위한 선택적 커스텀 구현
write.metadata.compression-codec none 메타데이터 압축 코덱; none 또는 gzip
write.metadata.metrics.max-inferred-column-defaults 100 통계(metrics)를 수집하는 최대 컬럼 수 정의. 컬럼은 스키마의 전위 순회(pre-order traversal)로 포함돼요: 최상위 필드 먼저; 그다음 첫 번째 중첩 struct의 모든 요소; 그다음 다음 중첩 struct 등등.
write.metadata.metrics.default truncate(16) 테이블의 모든 컬럼에 대한 기본 통계 모드; none, counts, truncate(length), 또는 full
write.metadata.metrics.column.col1 (not set) 컬럼별 튜닝을 위한 'col1' 컬럼의 통계 모드; none, counts, truncate(length), 또는 full
write.target-file-size-bytes 536870912 (512 MB) 생성되는 파일의 크기를 이 정도 바이트로 맞추도록 제어해요
write.delete.target-file-size-bytes 67108864 (64 MB) 생성되는 삭제 파일의 크기를 이 정도 바이트로 맞추도록 제어해요
write.distribution-mode not set, 엔진별 기본값 참조(예: Spark Writes) 쓰기 데이터의 분포 방식을 정의해요: none: 행을 셔플하지 않음; hash: 파티션 키로 해시 분포; range: 테이블에 SortOrder가 있으면 파티션 키 또는 정렬 키로 범위 분포
write.delete.distribution-mode (not set) 쓰기 삭제 데이터의 분포 방식 정의
write.update.distribution-mode (not set) 쓰기 갱신 데이터의 분포 방식 정의
write.merge.distribution-mode (not set) 쓰기 병합 데이터의 분포 방식 정의
write.wap.enabled false write-audit-publish 쓰기를 활성화해요
write.summary.partition-limit 0 변경된 파티션 개수가 이 한도보다 작으면 스냅샷 요약에 파티션 수준 요약 통계를 포함해요
write.metadata.delete-after-commit.enabled false 각 테이블 커밋 후 가장 오래된 추적 버전 메타데이터 파일을 삭제할지 제어해요. 자세한 내용은 기존 메타데이터 파일 제거(Remove old metadata files) 섹션을 참고해주세요
write.metadata.previous-versions-max 100 추적할 이전 버전 메타데이터 파일의 최대 개수
write.spark.fanout.enabled false 데이터를 클러스터링할 필요가 없는 스파크의 fanout 작성자를 활성화해요; 메모리를 더 사용해요
write.object-storage.enabled false 파일 경로에 해시 컴포넌트를 추가하는 객체 스토리지 위치 제공자를 활성화해요
write.object-storage.partitioned-paths true 파일 경로에 파티션 값을 포함해요
write.data.path table location + /data 데이터 파일의 기본 위치
write.metadata.path table location + /metadata 메타데이터 파일의 기본 위치
write.delete.mode copy-on-write 삭제 명령에 사용되는 모드: copy-on-write 또는 merge-on-read (v2 이상)
write.delete.isolation-level serializable 삭제 명령의 격리 수준: serializable 또는 snapshot
write.update.mode copy-on-write 갱신 명령에 사용되는 모드: copy-on-write 또는 merge-on-read (v2 이상)
write.update.isolation-level serializable 갱신 명령의 격리 수준: serializable 또는 snapshot
write.merge.mode copy-on-write 병합 명령에 사용되는 모드: copy-on-write 또는 merge-on-read (v2 이상)
write.merge.isolation-level serializable 병합 명령의 격리 수준: serializable 또는 snapshot
write.delete.granularity partition 생성되는 삭제 파일의 세분성 제어: partition 또는 file

암호화 속성 (Encryption properties)

속성 기본값 설명
encryption.key-id (not set) 테이블 마스터 키의 ID
encryption.data-key-length 16 (bytes) 테이블 파일 암호화에 사용되는 키의 길이. 유효한 값은 16, 24, 32바이트

자세한 내용은 암호화(Encryption) 문서를 참고해주세요.

테이블 동작 속성 (Table behavior properties)

속성 기본값 설명
commit.retry.num-retries 4 실패하기 전에 커밋을 재시도하는 횟수
commit.retry.min-wait-ms 100 커밋을 재시도하기 전에 기다리는 최소 시간(밀리초)
commit.retry.max-wait-ms 60000 (1 min) 커밋을 재시도하기 전에 기다리는 최대 시간(밀리초)
commit.retry.total-timeout-ms 1800000 (30 min) 커밋의 총 재시도 제한 시간(밀리초)
commit.status-check.num-retries 3 연결이 끊어진 후 알 수 없는 커밋 상태로 실패하기 전에 커밋 성공 여부를 확인하는 횟수
commit.status-check.min-wait-ms 1000 (1s) 상태 확인을 재시도하기 전에 기다리는 최소 시간(밀리초)
commit.status-check.max-wait-ms 60000 (1 min) 상태 확인을 재시도하기 전에 기다리는 최대 시간(밀리초)
commit.status-check.total-timeout-ms 1800000 (30 min) 커밋 상태 확인이 성공해야 하는 총 제한 시간(밀리초)
commit.manifest.target-size-bytes 8388608 (8 MB) 매니페스트 파일을 병합할 때의 목표 크기
commit.manifest.min-count-to-merge 100 병합하기 전에 누적해야 하는 매니페스트의 최소 개수
commit.manifest-merge.enabled true 쓰기 시 매니페스트를 자동으로 병합할지 제어해요
history.expire.max-snapshot-age-ms 432000000 (5 days) 스냅샷 만료 시 테이블과 모든 브랜치에 보관할 스냅샷의 기본 최대 수명
history.expire.min-snapshots-to-keep 1 스냅샷 만료 시 테이블과 모든 브랜치에 보관할 스냅샷의 기본 최소 개수
history.expire.max-ref-age-ms Long.MAX_VALUE (forever) main 브랜치를 제외한 스냅샷 참조에 대해, 스냅샷 만료 시 보관할 스냅샷 참조의 기본 최대 수명. main 브랜치는 만료되지 않아요.
gc.enabled true 스냅샷 만료와 고아 파일 제거 같은 가비지 컬렉션 연산을 허용해요

예약 테이블 속성 (Reserved table properties)

예약 테이블 속성은 테이블을 만들거나 업데이트할 때의 동작을 제어하는 데에만 사용돼요. 이 속성들의 값은 테이블 메타데이터의 일부로 영구 저장되지 않아요.

속성 기본값 설명
format-version 2 스펙에 정의된 테이블 포맷 버전. 1.4.0 버전부터 기본값은 2예요.

정보 속성 (Informational properties)

정보 속성은 테이블에 대한 추가 컨텍스트를 제공하기 위해 설정할 수 있어요. 문서화, 발견, 외부 도구와의 통합에 유용해요. 읽기·쓰기 동작이나 쿼리 의미론에는 영향을 주지 않아요.

속성 기본값 설명
comment (not set) 테이블 수준 설명. 비즈니스 의미와 사용 컨텍스트를 문서화해요.

호환성 플래그 (Compatibility flags)

속성 기본값 설명
compatibility.snapshot-id-inheritance.enabled false 명시적 스냅샷 ID 없이 스냅샷을 커밋할 수 있게 해요 (포맷 버전이 1보다 크면 항상 true)

더 알아보기 (Learn more)