2026년 4월 20일부터 BigLake의 이름이 Lakehouse로 변경되었습니다. BigLake metastore가 Lakehouse 런타임 카탈로그로 변경되었습니다. Lakehouse API, 클라이언트 라이브러리, CLI 명령어, IAM 이름은 변경되지 않으며 여전히 BigLake를 참조합니다.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

표 옵션 구성

레이크하우스 런타임 카탈로그의 테이블 옵션을 사용하여 Apache Iceberg 테이블에 BigQuery DML 쓰기 상호 운용성 및 테이블 관리 (자동 스토리지 최적화)를 선택할 수 있습니다.

Lakehouse 런타임 카탈로그에서 지원되는 테이블 형식과 선택 기능에 대한 자세한 내용은 테이블 유형 비교 및 Apache Iceberg 테이블 개요를 참조하세요.

시작하기 전에

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
BigLake API가 아직 사용 설정되지 않았으면 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기
API 사용 설정하기
Apache Iceberg REST 카탈로그 엔드포인트를 사용하여 Lakehouse 런타임 카탈로그를 설정합니다.

필요한 역할

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

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

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

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

구성 고려사항

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

지원되는 Iceberg 테이블

레이크하우스 런타임 카탈로그는 Apache Iceberg V2 (정식 버전) 및 V3 (프리뷰) 테이블을 지원하지만 관리형 기능 (BigQuery DML 및 테이블 관리)은 Iceberg V2 테이블에만 지원됩니다. Iceberg V1 테이블은 지원되지 않습니다. 기존 V1 테이블을 업그레이드하려면 Iceberg V1 테이블을 V2로 업그레이드를 참조하세요.

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

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

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에 따라 만료됩니다. 삭제된 스냅샷에 대한 참조를 생략하는 새 메타데이터 파일에 추가 스냅샷 정의를 만들어 만료된 스냅샷 항목을 삭제합니다.
- 제한사항: 테이블에서 태그 또는 브랜치를 사용하는 경우 스냅샷 만료 및 관련 가비지 컬렉션이 건너뛰어집니다. 자세한 내용은 제한사항을 참조하세요.
- 제한사항: 분리된 파일 삭제는 테이블 관리에서 처리되지 않습니다. 자세한 내용은 제한사항을 참조하세요.
Coalesce (압축): Coalesce는 작은 파일을 더 큰 파일로 병합하여 데이터 형태를 유지합니다. Coalesce는 데이터 변형 후 백그라운드에서 자동으로 실행됩니다. 압축되지 않은 평균 크기가 목표 파일 크기인 256MB의 50% 미만인 경우 압축을 위해 파일이 선택됩니다. 각 병합 작업은 새 테이블 스냅샷을 생성합니다. 병합 작업은 일반적으로 실행 중인 DML 작업 후에 양보하고 다시 시도합니다. 하지만 스토리지 최적화가 무기한 중단되는 것을 방지하기 위해 데이터가 병합에 적합한 경우 24시간마다 병합 작업이 강제로 트리거됩니다.
테이블 관리 작업 모니터링: 모든 백그라운드 테이블 관리 작업은 BigQuery의 INFORMATION_SCHEMA.JOBS 뷰에 로깅됩니다. 이 뷰를 쿼리하여 다른 BigQuery 작업을 모니터링하는 방법과 유사하게 이러한 작업을 추적할 수 있습니다. 작업 정보 쿼리에 대한 자세한 내용은 Iceberg 스토리지 최적화 작업 가져오기를 참조하세요.

테이블 관리 작업의 빈도는 데이터 변형 활동과 직접적인 상관관계가 있습니다. 작은 삽입 또는 업데이트가 자주 발생하면 백그라운드 태스크가 더 자주 트리거됩니다. 테이블에 쓰기가 없으면 백그라운드 작업이 없는 기간이 표시될 수 있습니다. 반대로 쓰기 볼륨이 높으면 INFORMATION_SCHEMA에서 작업 활동이 더 많이 표시될 수 있습니다.

표 관리 사용 설정 여부 선택

Lakehouse 런타임 카탈로그에서 관리하고 Apache Iceberg REST 카탈로그 엔드포인트를 통해 제공되는 Apache Iceberg 테이블의 경우 테이블 관리를 사용 설정하거나 오픈소스 또는 서드 파티 엔진을 사용하여 테이블 유지보수 (예: 압축 및 스냅샷 만료)를 직접 관리할 수 있습니다.

다음 조건이 모두 적용되는 경우 테이블 관리 (gcp.biglake.table-management.enabled = true)를 사용 설정합니다.

DML 또는 오픈소스 스트리밍 쓰기 후 자동 백그라운드 파일 압축 (병합)과 자동 스냅샷 만료 및 가비지 컬렉션이 필요합니다.
카탈로그에서 사용자 인증 정보 벤더 제공 모드를 사용합니다.
최대 7일 (기본값 5일)의 스냅샷 보관 및 시간 이동 기간이 요구사항을 충족합니다.
테이블이 관리형 기능의 요구사항을 충족합니다 (제한사항 참조).

다음 조건 중 하나가 적용되는 경우 테이블 관리를 사용 중지된 상태로 유지하고 (오픈소스 엔진에서 생성된 테이블의 기본값 또는 gcp.biglake.table-management.enabled = false 설정) 테이블 유지보수를 직접 관리합니다.

특히 테이블이 병합에서 보존되지 않는 Z 순서 또는 선형 정렬 레이아웃을 사용하는 경우 Apache Spark, Apache Flink 또는 Trino와 같은 오픈소스 엔진에서 커스텀 압축 또는 유지보수 절차를 실행합니다.
테이블에서 Apache Iceberg 스냅샷 태그 또는 브랜치를 사용하거나 (테이블 관리에서 스냅샷 만료를 건너뜀) 스냅샷 보관 및 시간 이동이 7일보다 길어야 합니다.
카탈로그는 사용자 인증 정보 자동 판매 모드 대신 최종 사용자 인증 정보 (직접 Cloud Storage Identity and Access Management (IAM) 권한)를 사용합니다.
테이블에서 Apache Iceberg 형식 버전 3, 읽기 시 병합 모드, 다중 열 또는 IDENTITY 파티셔닝, 커스텀 데이터 및 메타데이터 스토리지 경로와 같이 관리형 기능에서 지원되지 않는 기능을 사용합니다. 이 경우 테이블 관리와 BigQuery DML을 모두 사용 중지된 상태로 유지해야 합니다. 지원되지 않는 기능의 전체 목록은 제한사항을 참조하세요.

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

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

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

테이블 관리 사용 중지

테이블 관리를 사용 중지하면 활성 상태의 진행 중인 작업은 완료되지만 향후 백그라운드 최적화 작업이 큐에 추가되지 않습니다. 테이블 관리를 사용 중지해도 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 버킷 위치가 필요합니다.
Lakehouse 런타임 카탈로그에서 관리하는 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 프로시져 사용).

경고: 분리된 파일 삭제를 실행하면 쿼리가 older_than 기준점 (기본값은 3일)보다 오래 실행되는 경우 활성 상태의 장기 실행 쿼리에서 파일이 삭제될 수 있습니다. older_than 매개변수를 가장 오래 실행되는 쿼리보다 긴 값으로 설정합니다.
Coalesce는 z 순서 지정 및 선형 정렬을 지원하지 않습니다. 테이블에 이러한 속성이 포함된 경우 병합 실행 후 레이아웃이 유지된다고 보장할 수 없습니다. 테이블에 이러한 속성이 포함된 경우 테이블 관리를 사용 설정하지 마세요.

파티셔닝 제한사항

오픈소스 엔진에서 테이블을 만들거나 등록할 때 관리형 기능은 hour, day, month, year 변환(DATE 필드의 hour 변환 제외)이 있는 DATE, DATETIME, TIMESTAMP 필드 유형과 INTEGER 필드 유형의 파티션 나누기만 지원합니다.
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`	Apache Iceberg REST 카탈로그 엔드포인트에 구성된 기본 Cloud Storage 버킷 경로가 데이터 파일을 작성하는 데 사용됩니다.
`write.metadata.path`	`table location + /metadata`	Apache Iceberg 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 쓰기 및 테이블 관리 작업은 이를 준수하지 않을 수 있습니다.

다음 단계

BigQuery DML로 데이터를 수정하는 방법 알아보기
테이블을 쿼리하는 방법 알아보기

표 옵션 구성 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

구성 고려사항

지원되는 Iceberg 테이블

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

BigQuery DML 사용 설정

새 테이블에 BigQuery DML 사용 설정

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

BigQuery DML 사용 중지

테이블 관리 사용 설정

표 관리 사용 설정 여부 선택

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

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

Spark SQL

BigQuery

테이블 관리 사용 중지

Spark SQL

BigQuery

제한사항

일반 제한

시간 이동의 제한사항

테이블 관리 제한사항

파티셔닝 제한사항

커스텀 Iceberg 테이블 속성의 제한사항

다음 단계

표 옵션 구성