표 옵션 구성

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

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

레이크하우스 런타임 카탈로그에서 테이블을 사용할 때는 다양한 테이블 유형과 선택 기능을 이해하는 것이 좋습니다. 특히 Apache Iceberg 테이블 사용에 대한 자세한 내용은 Apache Iceberg 테이블 개요를 참고하세요.

시작하기 전에

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

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

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한을 이미 보유하고 있을 가능성이 높습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법을 알아보세요.

    API 사용 설정하기

  3. Apache Iceberg REST 카탈로그 엔드포인트로 레이크하우스 런타임 카탈로그를 설정합니다.

필요한 역할

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

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

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

구성 시 고려사항

테이블 옵션을 구성할 때는 다음 요구사항 및 기본 동작을 고려하세요.

지원되는 Iceberg 테이블

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

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

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

BigQuery DML 사용 설정

BigQuery DML 문을 사용 설정하면 오픈소스 엔진을 사용하여 만든 Apache Iceberg 테이블에서 BigQuery의 쓰기 상호 운용성이 잠금 해제됩니다.

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

새 테이블에 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을 기반으로 만료됩니다. 삭제된 스냅샷에 대한 참조가 더 이상 포함되지 않는 새 메타데이터 파일로 매니페스트되는 추가 스냅샷 정의를 하나 더 만들어 만료된 스냅샷 항목을 삭제합니다.

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

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

  • 결합 (압축): 결합은 작은 파일을 더 큰 파일로 병합하여 데이터의 모양을 유지하는 역할을 합니다. 결합은 데이터 변경 후 백그라운드에서 자동으로 실행됩니다. 압축되지 않은 파일의 평균 크기가 대상 파일 크기인 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 카탈로그 엔드포인트를 사용하여 레이크하우스 런타임 카탈로그에서 만든 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 버킷 위치가 필요합니다.
  • BigQuery 클러스터링은 레이크하우스 런타임 카탈로그에서 관리하는 Apache Iceberg 테이블에서 지원되지 않습니다.
  • BigQuery에서 NUMERIC 데이터 유형으로 테이블을 만들면 Spark에서 NUMERIC을 NUMERIC(38,9)으로 읽기 때문에 Spark의 스키마 업데이트가 실패합니다. 해결 방법으로 BigQuery에서 NUMERIC 유형으로 테이블을 만들 때는 정밀도를 NUMERIC(38,9)으로 명시적으로 설정합니다.
  • 알려진 문제: DDL(ALTER TABLE ... DROP COLUMN)을 사용하여 BigQuery에서 열을 삭제한 후 즉시 동일한 이름으로 열을 다시 추가하는 것은 지원되지 않습니다.

시간 이동 제한사항

테이블 관리 제한사항

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

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

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

파티셔닝 제한사항

  • 오픈소스 엔진에서 테이블을 만들거나 등록할 때 관리형 기능은 hour, day, month, year 변환(DATE 필드의 hour 변환 제외) 및 INTEGER 필드 유형이 있는 DATE, DATETIME, TIMESTAMP 필드 유형의 파티셔닝만 지원합니다.
  • 관리형 기능은 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 레이크하우스 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일 (604,800,000ms)까지 권장됩니다. 테이블 관리 작업은 지정된 기간보다 오래된 스냅샷을 삭제합니다.
history.expire.min-snapshots-to-keep 1 양의 정수로 구성할 수 있습니다. 테이블 관리 작업은 최소한 이 스냅샷 수를 보관합니다.

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

다음 단계