Apache Iceberg 외부 테이블 만들기

Apache Iceberg 외부 테이블을 사용하면 읽기 전용 형식의 세분화된 액세스 제어로 Apache Iceberg 테이블에 액세스할 수 있습니다. 이 기능은 BigQuery의 Apache Iceberg용 BigLake 테이블과 대조적으로 쓰기 가능한 형식으로 BigQuery에서 Iceberg 테이블을 만들 수 있습니다.

Iceberg는 페타바이트급 확장 데이터 테이블을 지원하는 오픈소스 테이블 형식입니다. Iceberg 개방형 사양을 사용하면 객체 저장소에 저장된 단일 데이터 사본에서 여러 쿼리 엔진을 실행할 수 있습니다. Apache Iceberg 외부 테이블 (이하 Iceberg 외부 테이블)은 병합 후 읽기를 포함한 Iceberg 사양 버전 2를 지원합니다.

BigQuery 관리자는 테이블에 데이터 마스킹을 포함한 행 및 열 수준 액세스 제어를 적용할 수 있습니다. 테이블 수준에서 액세스 제어를 설정하는 방법은 액세스 제어 정책 설정을 참조하세요. Dataproc 및 서버리스 Spark에서 BigQuery Storage API를 테이블의 데이터 소스로 사용하는 경우에도 테이블 액세스 정책이 적용됩니다.

다음과 같은 방법으로 Iceberg 외부 테이블을 만들 수 있습니다.

• BigLake metastore 사용 ( Google Cloud에 권장). BigLake metastore는 BigQuery 카탈로그를 기반으로 하며 BigQuery와 직접 통합됩니다. BigLake metastore의 테이블은 여러 오픈소스 엔진에서 변경할 수 있으며 동일한 테이블을 BigQuery에서 쿼리할 수 있습니다. BigLake metastore는 Apache Spark와의 직접 통합도 지원합니다. BigLake metastore를 사용하는 Iceberg 외부 테이블을 BigLake Iceberg 테이블이라고도 합니다.

• AWS Glue Data Catalog 사용(AWS에 권장). AWS Glue는 다양한 AWS 서비스에 저장된 데이터의 구조와 위치를 정의하고 자동 스키마 검색 및 AWS 분석 도구와의 통합과 같은 기능을 제공하는 중앙 집중식 메타데이터 저장소이므로 AWS에 권장되는 방법입니다.

• Iceberg JSON 메타데이터 파일 사용(Azure에 권장) Iceberg JSON 메타데이터 파일을 사용하는 경우 테이블 업데이트가 있을 때마다 최신 메타데이터 파일을 수동으로 업데이트해야 합니다. Apache Spark용 BigQuery 저장 프로시져를 사용하여 Iceberg 메타데이터 파일을 참조하는 Iceberg 외부 테이블을 만들 수 있습니다.

제한사항의 전체 목록은 제한사항을 참조하세요.

시작하기 전에

Enable the BigQuery Connection and BigQuery Reservation APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

• BigQuery의 Spark용 저장 프로시져를 사용하여 Iceberg 외부 테이블을 만드는 경우 다음 단계를 따라야 합니다.

  1. Spark 연결을 만듭니다.
  2. 해당 연결에 대해 액세스 제어를 설정합니다.

• Iceberg 외부 테이블 메타데이터와 데이터 파일을 Cloud Storage에 저장하려면 Cloud Storage 버킷을 만듭니다. 메타데이터 파일에 액세스하려면 Cloud Storage 버킷에 연결해야 합니다. 단계별 절차는 다음과 같습니다.

  1. 클라우드 리소스 연결을 만듭니다.
  2. 해당 연결에 대한 액세스를 설정합니다.

필요한 역할

Iceberg 외부 테이블을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• BigQuery 관리자(roles/bigquery.admin)
• 스토리지 객체 관리자(roles/storage.objectAdmin)

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

이러한 사전 정의된 역할에는 Iceberg 외부 테이블을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

Iceberg 외부 테이블을 만들려면 다음 권한이 필요합니다.

• bigquery.tables.create
• bigquery.connections.delegate
• bigquery.jobs.create

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

BigLake metastore로 테이블 만들기

BigLake metastore를 사용하여 Iceberg 외부 테이블을 만드는 것이 좋습니다. Apache Spark를 사용하여 이러한 테이블을 만들 수 있습니다. 이를 수행하는 편리한 방법은 BigQuery 저장 프로시저를 사용하는 것입니다. 예를 보려면 저장 프로시저 만들기 및 실행을 참고하세요.

메타데이터 파일로 테이블 만들기

JSON 메타데이터 파일로 Iceberg 외부 테이블을 만들 수 있습니다. 하지만 이 방법은 Iceberg 외부 테이블을 최신 상태로 유지하기 위해 JSON 메타데이터 파일의 URI를 수동으로 업데이트해야 하므로 권장되는 방법은 아닙니다. URI가 최신 상태로 유지되지 않으면 BigQuery의 쿼리가 실패하거나 Iceberg 카탈로그를 직접 사용하는 다른 쿼리 엔진과 다른 결과를 제공할 수 있습니다.

Iceberg 테이블 메타데이터 파일은 Spark를 사용하여 Iceberg 테이블을 만들 때 지정하는 Cloud Storage 버킷에 생성됩니다.

다음 옵션 중 하나를 선택합니다.

SQL

CREATE EXTERNAL TABLE 문을 사용합니다. 다음 예시에서는 myexternal-table이라는 Iceberg 외부 테이블을 만듭니다.

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

uris 값을 특정 테이블 스냅샷의 최신 JSON 메타데이터 파일로 바꿉니다.

require_partition_filter 플래그를 설정하여 파티션 필터 필요를 사용 설정할 수 있습니다.

bq

명령줄 환경에서 @connection 데코레이터와 함께 bq mk --table 명령어를 사용하면 --external_table_definition 매개변수 끝에서 사용할 연결을 지정할 수 있습니다. 파티션 필터 필요를 사용 설정하려면 --require_partition_filter를 사용합니다.

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

다음을 바꿉니다.

• TABLE_FORMAT: 만들려는 테이블의 이름

  이 경우 ICEBERG입니다.

• URI: 특정 테이블 스냅샷에 대한 최신 JSON 메타데이터 파일

  예를 들면 gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json입니다.

  URI는 Amazon S3 또는 Azure Blob Storage와 같은 외부 클라우드 위치를 가리킬 수도 있습니다.

  • AWS의 예: s3://mybucket/iceberg/metadata/1234.metadata.json
  • Azure의 예: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json

• CONNECTION_PROJECT_ID: Iceberg 외부 테이블을 만들기 위한 연결이 포함된 프로젝트(예: myproject)

• CONNECTION_REGION: Iceberg 외부 테이블을 만들기 위한 연결이 포함된 리전(예: us)

• CONNECTION_ID: 테이블 연결 ID(예: myconnection)

  Google Cloud 콘솔에서 연결 세부정보를 볼 때 연결 ID는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: projects/myproject/locations/connection_location/connections/myconnection).

• DATASET: 테이블을 만들려는 BigQuery 데이터 세트의 이름

  예를 들면 mydataset입니다.

• EXTERNAL_TABLE: 만들려는 테이블의 이름

  예를 들면 mytable입니다.

테이블 메타데이터 업데이트

JSON 메타데이터 파일을 사용하여 Iceberg 외부 테이블을 만드는 경우 테이블 정의를 최신 테이블 메타데이터로 업데이트합니다. 스키마 또는 메타데이터 파일을 업데이트하려면 다음 옵션 중 하나를 선택합니다.

bq

1. 테이블 정의 파일 만들기

   bq mkdef --source_format=ICEBERG \
   "URI" > TABLE_DEFINITION_FILE
   

2. --autodetect_schema 플래그와 함께 bq update 명령어를 사용합니다.

   bq update --autodetect_schema --external_table_definition=TABLE_DEFINITION_FILE
   PROJECT_ID:DATASET.TABLE
   

   다음을 바꿉니다.

   • URI: 최신 JSON 메타데이터 파일이 있는 Cloud Storage URI

     예를 들면 gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json입니다.

   • TABLE_DEFINITION_FILE: 테이블 스키마가 포함된 파일의 이름

   • PROJECT_ID: 업데이트할 테이블이 포함된 프로젝트 ID

   • DATASET: 업데이트할 테이블이 포함된 데이터 세트

   • TABLE: 스냅샷을 작성하려는 테이블

API

autodetect_schema 속성을 true로 설정하여 tables.patch 메서드를 사용합니다.

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

다음을 바꿉니다.

• PROJECT_ID: 업데이트할 테이블이 포함된 프로젝트 ID
• DATASET: 업데이트할 테이블이 포함된 데이터 세트
• TABLE: 스냅샷을 작성하려는 테이블

요청 본문에서 다음 필드에 업데이트된 값을 지정하세요.

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

URI를 최신 Iceberg 메타데이터 파일로 바꿉니다. 예를 들면 gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json입니다.

액세스 제어 정책 설정

열 수준 보안, 행 수준 보안, 데이터 마스킹을 통해 Iceberg 외부 테이블에 대한 액세스를 제어할 수 있습니다.

Iceberg 외부 테이블 쿼리

자세한 내용은 Iceberg 데이터 쿼리를 참조하세요.

이전 데이터 쿼리

FOR SYSTEM_TIME AS OF 절을 사용하여 Iceberg 메타데이터에 보관된 Iceberg 외부 테이블의 스냅샷에 액세스할 수 있습니다.

시간 이동 및 장애 안전 데이터 보관 기간은 외부 테이블에서 지원되지 않습니다.

데이터 매핑

BigQuery는 다음 표와 같이 Iceberg 데이터 유형을 BigQuery 데이터 유형으로 변환합니다.

Iceberg 데이터 유형	BigQuery 데이터 유형
boolean	BOOL
int	INT64
long	INT64
float	FLOAT64
double	FLOAT64
Decimal(P/S)	NUMERIC or BIG_NUMERIC depending on precision
date	DATE
time	TIME
timestamp	DATETIME
timestamptz	TIMESTAMP
string	STRING
uuid	BYTES
fixed(L)	BYTES
binary	BYTES
list<Type>	ARRAY<Type>
struct	STRUCT
map<KeyType, ValueType>	ARRAY<Struct<key KeyType, value ValueType>>

제한사항

Iceberg 외부 테이블에는 외부 테이블 제한사항과 다음 제한사항이 있습니다.

• 읽기 시 병합을 사용하는 테이블에는 다음과 같은 제한사항이 있습니다.

  • 각 데이터 파일은 최대 10,000개의 삭제 파일과 연결될 수 있습니다.
  • 데이터 파일에는 최대 100,000개의 동등성 삭제를 적용할 수 있습니다.
  • 삭제 파일을 자주 압축하거나 자주 변경되는 파티션을 방지하는 Iceberg 테이블 위에 뷰를 만들어 이러한 제한사항을 해결할 수 있습니다.

• BigQuery는 모든 Iceberg 파티션 변환 함수를 사용하여 매니페스트 프루닝을 지원합니다. 파티션을 프루닝하는 방법은 파티션을 나눈 테이블 쿼리를 참고하세요. Iceberg 외부 테이블을 참조하는 쿼리에는 파티션을 나눈 열과 비교하여 조건자에 리터럴이 포함되어야 합니다.

• Apache Parquet 데이터 파일만 지원됩니다.

읽기 시 병합 비용

읽기 시 병합 데이터의 주문형 결제는 다음 데이터의 스캔 합계입니다.

• 데이터 파일에서 읽은 모든 논리 바이트입니다 (위치 및 동등성 삭제로 삭제된 것으로 표시된 행 포함).
• 데이터 파일에서 삭제된 행을 찾기 위해 동등성 삭제 및 위치 삭제 파일을 로드하여 읽은 논리 바이트입니다.

파티션 필터 필요

Iceberg 테이블에 파티션 필터 필요 옵션을 사용 설정하여 조건자 필터를 반드시 사용하도록 지정할 수 있습니다. 이 옵션을 사용 설정하면 각 매니페스트 파일과 일치하는 WHERE 절을 지정하지 않고 테이블을 쿼리하려고 하면 다음과 같은 오류가 발생합니다.

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

각 매니페스트 파일에는 파티션 제거에 적합한 서술어가 하나 이상 필요합니다.

Iceberg 테이블을 만드는 동안 다음과 같은 방법으로 require_partition_filter를 사용 설정할 수 있습니다.

SQL

CREATE EXTERNAL TABLE 문을 사용합니다. 다음 예시에서는 파티션 필터 필요가 사용 설정된 TABLE이라는 Iceberg 외부 테이블을 만듭니다.

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

다음을 바꿉니다.

• TABLE: 만들려는 테이블 이름
• PROJECT_ID: 만들려는 테이블이 포함된 프로젝트 ID
• REGION: Iceberg 테이블을 만들 위치

• CONNECTION_ID: 연결 ID. 예를 들면 myconnection입니다.

• URI: 최신 JSON 메타데이터 파일이 있는 Cloud Storage URI

  예를 들면 gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json입니다.

  URI는 Amazon S3 또는 Azure Blob Storage와 같은 외부 클라우드 위치를 가리킬 수도 있습니다.

  • AWS의 예: s3://mybucket/iceberg/metadata/1234.metadata.json
  • Azure의 예: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json

bq

@connection 데코레이터와 함께 bq mk --table 명령어를 사용하여 --external_table_definition 매개변수 끝에 사용할 연결을 지정합니다. --require_partition_filter를 사용하여 파티션 필터 필요를 사용 설정합니다. 다음 예시에서는 파티션 필터 필요가 사용 설정된 TABLE이라는 Iceberg 외부 테이블을 만듭니다.

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

다음을 바꿉니다.

• URI: 특정 테이블 스냅샷에 대한 최신 JSON 메타데이터 파일

  예를 들면 gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json입니다.

  URI는 Amazon S3 또는 Azure Blob Storage와 같은 외부 클라우드 위치를 가리킬 수도 있습니다.

  • AWS의 예: s3://mybucket/iceberg/metadata/1234.metadata.json
  • Azure의 예: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json

• CONNECTION_PROJECT_ID: Iceberg 외부 테이블을 만들기 위한 연결이 포함된 프로젝트(예: myproject)

• CONNECTION_REGION: Iceberg 외부 테이블을 만들기 위한 연결이 포함된 리전 예를 들면 us입니다.

• CONNECTION_ID: 연결 ID. 예를 들면 myconnection입니다.

  Google Cloud 콘솔에서 연결 세부정보를 볼 때 연결 ID는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: projects/myproject/locations/connection_location/connections/myconnection).

• DATASET: 업데이트할 테이블이 포함된 BigQuery

  데이터 세트의 이름입니다. 예를 들면 mydataset입니다.

• EXTERNAL_TABLE: 만들려는 테이블의 이름

  예를 들면 mytable입니다.

Iceberg 테이블을 업데이트하여 파티션 필터 필요를 사용 설정할 수도 있습니다.

파티션을 나눈 테이블을 만들 때 파티션 필터 필요 옵션을 사용 설정하지 않았다면 테이블을 업데이트하여 해당 옵션을 추가할 수 있습니다.

bq

bq update 명령어를 사용하고 --require_partition_filter 플래그를 제공합니다.

예를 들면 다음과 같습니다.

기본 프로젝트에 있는 mydataset의 mypartitionedtable을 업데이트하려면 다음을 입력합니다.

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

다음 단계

• Spark용 저장 프로시저 알아보기
• 액세스 제어 정책에 대해 알아봅니다.
• BigQuery에서 쿼리 실행 알아보기
• BigQuery에서 지원되는 문 및 SQL 언어에 대해 알아보기