표 옵션 구성

테이블 옵션을 구성하면 레이크하우스 런타임 카탈로그에서 Apache Iceberg 테이블의 BigQuery 쓰기 상호 운용성 또는 테이블 관리 (자동 스토리지 최적화)를 선택할 수 있습니다. 이러한 옵션은 테이블에 대한 작업의 기능을 확장하는 기본 설정으로 사용됩니다.

특정 테이블 속성을 구성하면 BigQuery DML과의 쓰기 상호 운용성을 사용 설정하거나 자동 테이블 관리 (스토리지 최적화)를 사용 설정할 수 있습니다.

Lakehouse 런타임 카탈로그에서 테이블을 사용할 때는 다양한 테이블 유형과 선택 기능을 이해하는 것이 좋습니다. Apache Iceberg 테이블 사용에 관해 자세히 알아보려면 Apache Iceberg 테이블 개요를 참고하세요.

시작하기 전에

  1. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  2. BigLake API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

    API 사용 설정하기

  3. Apache Iceberg REST 카탈로그 엔드포인트로 Lakehouse 런타임 카탈로그를 설정합니다.

필요한 역할

표 옵션을 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트 및 스토리지 버킷에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

  • 사용자 인증 정보 제공 모드에서 테이블 속성을 구성합니다. BigLake 편집기 (roles/biglake.editor) - 프로젝트
  • 인증 정보 제공 모드가 아닌 모드에서 테이블 속성을 구성합니다.
    • BigLake 편집자 (roles/biglake.editor) - 프로젝트
    • 스토리지 객체 사용자 (roles/storage.objectUser) - Cloud Storage 버킷

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

구성 고려사항

표 옵션을 구성할 때는 다음 요구사항과 기본 동작을 고려하세요.

지원되는 Iceberg 테이블

Apache Iceberg V2 (GA) 및 V3 (프리뷰) 테이블만 지원됩니다. Iceberg V1 테이블은 지원되지 않습니다. 기존 V1 테이블을 업그레이드하려면 Iceberg V1 테이블을 V2로 업그레이드를 참고하세요.

사용자 인증 정보 벤더 제공 요구사항

자동 테이블 관리를 선택하려면 레이크하우스 런타임 카탈로그에서 카탈로그 수준으로 인증 정보 판매가 사용 설정되어 있어야 합니다. 표 관리 백그라운드 작업은 사용자 인증 정보 판매 서비스 계정을 사용하여 기본 스토리지 데이터 파일을 인증하고 업데이트합니다.

BigQuery DML 사용 설정

BigQuery 데이터 조작 언어 (DML) 문을 사용 설정하면 오픈소스 엔진을 사용하여 생성된 Apache Iceberg 테이블에서 BigQuery의 쓰기 상호 운용성이 지원됩니다.

지원되는 문에는 INSERT, UPDATE, DELETE, MERGE와 CREATE TABLE, ALTER TABLE, DROP TABLE과 같은 표준 DDL 문이 포함되며, BigQuery의 Apache Iceberg 테이블에서 지원되지 않는 문은 제외됩니다.

새 테이블에 BigQuery DML 사용 설정

BigQuery에서 테이블을 만들 때 BigQuery DML 및 자동 테이블 관리가 기본적으로 사용 설정됩니다. 오픈소스 엔진에서 테이블을 만들 때는 엔진의 DDL 구문을 사용하여 gcp.biglake.bigquery-dml.enabled = true 테이블 속성을 구성합니다.

예를 들어 Spark SQL의 경우:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

기존 테이블에 BigQuery DML 사용 설정

기존 테이블에서 BigQuery DML을 사용 설정하려면 테이블 속성을 업데이트하세요.

예를 들어 Spark SQL의 경우:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

BigQuery DML 사용 중지

BigQuery DML을 사용 중지하면 BigQuery에서 테이블이 읽기 전용이 되고 자동 테이블 관리가 중지됩니다.

예를 들어 Spark SQL의 경우:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

표 관리 사용 설정

테이블 관리는 압축 및 가비지 컬렉션과 같은 스토리지 최적화 및 데이터와 메타데이터 수명 주기를 관리하기 위해 백그라운드 프로세스를 자동화합니다.

표 관리를 사용하면 다음 작업을 수행할 수 있습니다.

  • 스냅샷 만료 및 가비지 컬렉션: 스냅샷 만료는 테이블 스냅샷에서 데이터 및 메타데이터 파일의 보관 및 삭제를 관리합니다. 이는 데이터 변형 후 백그라운드에서 자동으로 실행됩니다. 스냅샷은 테이블에서 사용자 구성 Iceberg 테이블 속성 history.expire.max-snapshot-age-ms 및 history.expire.min-snapshots-to-keep에 따라 만료됩니다. 만료된 스냅샷 항목을 metadata.json 파일에서 삭제한 후 만료된 스냅샷에만 속하고 더 이상 라이브 스냅샷에서 참조하지 않는 데이터 및 메타데이터 파일을 물리적으로 삭제합니다.

    • 제한사항: 테이블에서 태그나 브랜치를 사용하는 경우 스냅샷 만료 및 관련 가비지 수집이 건너뛰어집니다. 자세한 내용은 제한사항을 참조하세요.

    • 제한사항: 고아 파일 삭제는 자동 테이블 관리에서 처리되지 않습니다. 자세한 내용은 제한사항을 참고하세요.

  • 병합 (압축): 병합은 작은 파일을 더 큰 파일로 병합하여 데이터의 모양을 유지하는 역할을 합니다. 병합은 데이터 변형 후 백그라운드에서 자동으로 실행됩니다. 압축되지 않은 평균 크기가 타겟 파일 크기인 256MB의 50% 미만인 파일은 압축 대상으로 선택됩니다. 각 병합 작업은 새 테이블 스냅샷을 생성합니다. 병합 작업은 일반적으로 실행 중인 DML 작업 후에 양보하고 재시도합니다. 하지만 스토리지 최적화가 무기한으로 중단되는 것을 방지하기 위해 데이터가 병합될 수 있는 경우 병합 작업이 24시간마다 강제로 트리거됩니다.

  • 테이블 관리 작업 모니터링: 모든 백그라운드 테이블 관리 작업은 BigQuery의 INFORMATION_SCHEMA.JOBS 뷰에 로깅됩니다. 이 뷰를 쿼리하여 다른 BigQuery 작업을 모니터링하는 것과 유사한 방식으로 이러한 작업을 추적할 수 있습니다. 작업 정보 쿼리에 관한 자세한 내용은 Iceberg 스토리지 최적화 작업 가져오기를 참고하세요.

    표 관리 작업의 빈도는 데이터 변형 활동과 직접적인 상관관계가 있습니다. 빈번한 소규모 삽입 또는 업데이트는 더 빈번한 백그라운드 작업을 트리거합니다. 테이블에 쓰기가 없으면 백그라운드 작업이 없는 기간이 관찰될 수 있습니다. 반대로 쓰기 볼륨이 높으면 INFORMATION_SCHEMA에서 작업 활동이 더 많이 표시될 수 있습니다.

새 테이블에 테이블 관리 사용 설정

BigQuery에서 테이블을 만들 때 DML 및 자동 테이블 관리가 기본적으로 사용 설정됩니다. 오픈소스 엔진에서 테이블을 만들 때는 gcp.biglake.table-management.enabled 속성을 구성합니다. 테이블 관리를 사용 설정하면 아직 사용 설정되지 않은 경우 BigQuery DML이 자동으로 사용 설정됩니다.

예를 들어 Spark SQL의 경우:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

기존 테이블의 테이블 관리 사용 설정

기존 테이블에서 테이블 관리를 사용 설정하려면 테이블 속성을 업데이트하세요.

예를 들어 Spark SQL의 경우:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

표 관리 사용 중지

표 관리를 사용 중지하면 진행 중인 활성 작업은 완료되지만 향후 백그라운드 최적화 작업이 대기열에 추가되지 않습니다. 테이블 관리를 사용 중지해도 BigQuery DML은 사용 중지되지 않습니다.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

제한사항

관리형 기능 (예: BigQuery 쓰기 상호 운용성 및 자동 테이블 관리)의 제한사항은 다음과 같습니다.

일반 제한

  • 관리 기능은 Apache Iceberg REST 카탈로그 엔드포인트를 사용하여 Lakehouse 런타임 카탈로그에서 생성된 Apache Iceberg 테이블에서만 지원됩니다.
  • 관리 기능이 사용 설정된 작업에는 BigQuery에서 관리하는 Apache Iceberg 테이블의 기존 제한사항이 모두 적용됩니다.
  • Apache Iceberg 형식 버전 3이 적용된 테이블에는 관리형 기능이 지원되지 않습니다. 관리 기능은 형식 버전 2 (Iceberg v2 사양) 테이블만 선택할 수 있습니다.
  • STRING별 파티셔닝, 다중 열 파티셔닝 또는 파티션 진화와 같은 고급 파티셔닝이 있는 테이블에는 관리 기능이 지원되지 않습니다.
  • 관리형 기능은 정렬 순서로 구성된 테이블 (예: WRITE ORDER BY 절차 사용 또는 write.distribution.mode = range 설정)에는 지원되지 않습니다.
  • 읽기 시 병합 모드를 사용하는 Iceberg v2 테이블에는 관리형 기능이 지원되지 않습니다. 쓰기 시 복사 업데이트, 삭제, 병합 모드를 사용하는 테이블만 관리 기능을 선택할 수 있습니다.
  • 관리 기능은 gzip, lz4 또는 brotli 코덱 (write.parquet.compression.codec)을 사용하여 압축된 데이터 파일을 지원하지 않습니다. 데이터 파일에는 zstd 및 snappy 압축 유형만 지원됩니다.
  • 스키마에 구조의 중첩 경로 또는 필드를 참조하는 중첩 기본 키 식별자 (identifier-field-ids)가 포함된 경우 테이블에 관리 기능이 지원되지 않습니다.
  • 관리형 기능은 맞춤 데이터 또는 메타데이터 위치 (write.data.path 및 write.metadata.path)가 있는 테이블에서 지원되지 않습니다. 데이터 및 메타데이터 파일을 보유하려면 기본 Cloud Storage 버킷 위치가 필요합니다.
  • 레이크하우스 런타임 카탈로그에서 관리하는 Apache Iceberg 테이블에는 BigQuery 클러스터링이 지원되지 않습니다.
  • BigQuery에서 NUMERIC 데이터 유형으로 테이블을 만든 경우 Spark에서 NUMERIC를 NUMERIC(38,9)로 읽기 때문에 Spark의 스키마 업데이트가 실패합니다. 해결 방법으로 BigQuery에서 NUMERIC 유형으로 테이블을 만들 때 정밀도를 NUMERIC(38,9)으로 명시적으로 설정하세요.
  • 알려진 문제: DDL(ALTER TABLE ... DROP COLUMN)을 사용하여 BigQuery에서 열을 삭제한 후 즉시 동일한 이름의 열을 다시 추가하는 것은 지원되지 않습니다.

시간 이동의 제한사항

  • 표 관리가 사용 설정된 경우 history.expire.max-snapshot-age-ms 속성의 최대 권장 값은 7일입니다.
  • 시간 이동을 위한 BigQuery 프로젝트 수준 또는 데이터 세트 수준 구성은 적용되지 않습니다. Iceberg 테이블 속성 및 기본값만 활성화됩니다.

표 관리 제한사항

  • 테이블에 태그 또는 브랜치가 있는 스냅샷이 포함된 경우 전체 테이블에 대해 스냅샷 만료가 건너뜁니다. ALTER... RETAIN x DAYS을 사용하여 설정된 맞춤 보관 기간이 무시되고 history.expire.max-ref-age-ms 속성에 설정된 모든 값이 무시됩니다. 오픈소스 엔진은 여전히 스냅샷 만료를 실행할 수 있습니다.
  • 자동 테이블 관리에서는 스키마 또는 파티션 사양이 만료되지 않습니다. metadata.json 파일은 스냅샷이 이러한 스키마 ID를 참조하지 않더라도 스키마 및 파티션 사양의 전체 기록을 유지합니다.

  • BigQuery 또는 오픈소스 엔진에서 생성된 고아 파일은 자동 테이블 관리에서 정리하지 않습니다. 오픈소스 엔진은 고아 파일 정리 (예: prefix_listing 옵션이 true으로 설정된 Spark remove_orphan_files 절차 사용)를 실행할 수 있습니다.

  • 병합은 z 순서 지정 및 선형 정렬을 지원하지 않습니다. 테이블에 이러한 속성이 포함되어 있으면 병합이 실행된 후 레이아웃이 유지된다고 보장할 수 없습니다. 테이블에 이러한 속성이 포함되어 있는 경우 테이블 관리를 사용 설정하지 않는 것이 좋습니다.

파티셔닝 관련 제한사항

  • 오픈소스 엔진에서 테이블을 만들거나 등록할 때 관리 기능은 hour, day, month, year 변환이 있는 DATE, TIMESTAMP, TIMESTAMPTZ 필드 유형의 파티셔닝만 지원합니다(DATE 필드의 hour 변환 제외).
  • 관리 기능은 IDENTITY 변환이 있는 테이블에서 지원되지 않습니다. 사용자는 변환을 명시적으로 지정해야 합니다.
  • 관리 기능이 있는 테이블의 CREATE OR REPLACE 명령어는 동일한 파티션 사양을 사용하는 경우에만 지원됩니다. 다음 대체는 지원되지 않습니다.
    • 파티션을 나누지 않은 테이블을 파티션을 나눈 테이블로 대체
    • 파티션을 나눈 테이블을 파티션을 나누지 않은 테이블로 대체
    • 파티션을 나눈 테이블을 다른 파티션 나누기 사양을 사용하는 테이블로 대체
  • 맞춤 파티션 필드 이름 지정은 지원되지 않습니다. 오픈소스 엔진에서 생성되거나 등록된 테이블은 엔진의 기본 파티션 필드 명명 규칙(_ 및 변환 이름(예: _hour, _day, _month, _year) 추가)을 따라야 합니다. 예를 들어 DAY 변환을 사용하는 time_date이라는 필드의 경우 예상되는 파티션 필드 값은 다음과 같습니다. json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

맞춤 Iceberg 테이블 속성의 제한사항

관리형 기능을 사용 설정한 경우 다음 표 동작 속성을 기본값이 아닌 값으로 구성할 수 없습니다. 관리 기능이 사용 설정된 경우 기본값은 하드코딩됩니다.

속성 기본값 세부정보
format-version 2 관리형 기능은 Iceberg v2 테이블만 지원합니다.
write.format.default parquet 표는 Parquet 형식의 데이터 파일만 지원합니다.
write.data.path table location + /data 레이크하우스 REST 카탈로그에 구성된 기본 Cloud Storage 버킷 경로가 데이터 파일을 쓰는 데 사용됩니다.
write.metadata.path table location + /metadata Lakehouse REST 카탈로그에 구성된 기본 Cloud Storage 버킷 경로가 메타데이터 파일을 쓰는 데 사용됩니다.
write.delete.mode copy-on-write BigQuery 쓰기 및 테이블 관리 작업은 쓰기 시 복사만 지원합니다.
write.update.mode copy-on-write BigQuery 쓰기 및 테이블 관리 작업은 쓰기 시 복사만 지원합니다.
write.merge.mode copy-on-write BigQuery 쓰기 및 테이블 관리 작업은 쓰기 시 복사만 지원합니다.
write.delete.isolation-level 엄격한 충돌 감지 metadata.json 파일을 수정하는 변경사항 (데이터 충돌, 메타데이터 충돌, 팬텀 읽기 또는 충돌하지 않는 동시 쓰기 포함)으로 인해 동시 트랜잭션이 실패하고 재시도됩니다.
write.update.isolation-level 엄격한 충돌 감지 write.delete.isolation-level과 동일한 동작입니다.
write.merge.isolation-level 엄격한 충돌 감지 write.delete.isolation-level과 동일한 동작입니다.

오픈소스 엔진에서 테이블을 만들거나 변경할 때 다음 속성을 구성할 수 있습니다.

속성 기본값 세부정보
write.parquet.compression-codec zstd BigQuery 쓰기 및 스토리지 최적화는 zstd 및 snappy 압축 형식만 지원합니다. 다른 압축 형식 (예: gzip, brotli, lz4)은 지원되지 않습니다.
write.metadata.compression-codec null null 또는 gzip로 구성할 수 있습니다.
history.expire.max-snapshot-age-ms 432000000 (5일) 양의 정수로 구성할 수 있지만 테이블 관리가 사용 설정된 경우 최대 7일 (604800000ms)이 권장됩니다. 표 관리 작업은 지정된 기간보다 오래된 스냅샷을 삭제합니다.
history.expire.min-snapshots-to-keep 1 양의 정수로 구성할 수 있습니다. 표 관리 작업은 이 스냅샷 수를 최소한으로 유지합니다.

write.target-file-size-bytes 및 write.parquet.page-size-bytes과 같은 기타 Apache Iceberg 쓰기 속성은 오픈소스 엔진에서 구성할 수 있지만 BigQuery 쓰기 및 테이블 관리 작업은 이를 준수하지 않을 수 있습니다.

다음 단계