BigLake metastore Iceberg REST 카탈로그 사용

BigLake metastore의 Apache Iceberg REST 카탈로그는 새 워크플로에 BigLake metastore를 사용하는 데 권장되는 방법입니다. 모든 Iceberg 데이터에 단일 소스를 제공하여 쿼리 엔진 간의 상호 운용성을 지원합니다. 이를 통해 Apache Spark와 같은 쿼리 엔진이 일관된 방식으로 Iceberg 테이블을 검색하고, 메타데이터를 읽고, 관리할 수 있습니다.

이 방법은 오픈소스 엔진을 사용하여 Cloud Storage의 데이터에 액세스하고 BigQuery를 비롯한 다른 엔진과의 상호 운용성이 필요한 경우에 적합합니다. 세분화된 액세스 제어를 위한 사용자 인증 정보 제공, 리전 간 복제 및 재해 복구와 같은 기능을 지원합니다.

반면 BigQuery용 커스텀 Iceberg 카탈로그는 이전 통합입니다. 기존 워크플로에서는 계속 사용할 수 있지만 REST 카탈로그는 더 표준화되고 기능이 풍부한 환경을 제공합니다.

시작하기 전에

계속하기 전에 BigLake metastore를 숙지하세요.

Verify that billing is enabled for your Google Cloud project.
Enable the BigLake API.
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 API

필요한 역할

BigLake metastore에서 Iceberg REST 카탈로그를 사용하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

카탈로그 사용자 액세스, 스토리지 액세스, 카탈로그의 사용자 인증 정보 제공 모드 관리와 같은 관리 작업을 실행합니다.
- 프로젝트에 대한 BigLake 관리자 (roles/biglake.admin)
- Cloud Storage 버킷에 대한 스토리지 관리자 (roles/storage.admin)
인증 정보 판매 모드에서 테이블 데이터 읽기: 프로젝트의 BigLake 뷰어 (roles/biglake.viewer)
인증 정보 제공 모드에서 테이블 데이터 쓰기: 프로젝트에 대한 BigLake 편집자 (roles/biglake.editor)
사용자 인증 정보 벤더 제공 모드가 아닌 모드에서 카탈로그 리소스 및 테이블 데이터 읽기:
- 프로젝트에 대한 BigLake 뷰어 (roles/biglake.viewer)
- Cloud Storage 버킷에 대한 스토리지 객체 뷰어 (roles/storage.objectViewer)
사용자 인증 정보 벤더 제공 모드가 아닌 모드에서 카탈로그 리소스를 관리하고 테이블 데이터를 작성합니다.
- 프로젝트에 대한 BigLake 편집자 (roles/biglake.editor)
- Cloud Storage 버킷에 대한 스토리지 객체 사용자 (roles/storage.objectUser)

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

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

제한사항

Iceberg REST 카탈로그에는 다음과 같은 제한사항이 적용됩니다.

인증 정보 벤더 제공 모드를 사용하는 경우 io-impl 속성을 org.apache.iceberg.gcp.gcs.GCSFileIO로 설정해야 합니다. 기본값인 org.apache.iceberg.hadoop.HadoopFileIO은 지원되지 않습니다.
Trino는 Compute Engine 2.3 이미지 버전 2.3.16 이상을 사용하는 경우 BigQuery 카탈로그 페더레이션에서만 지원됩니다.

카탈로그 리소스

BigLake metastore의 Apache Iceberg REST 카탈로그는 리소스 계층 구조를 사용하여 데이터를 구성합니다.

Apache Iceberg REST 카탈로그 리소스

다음 표에서는 BigLake metastore의 Apache Iceberg REST 카탈로그에서 사용되는 리소스를 간략하게 보여줍니다.

리소스	설명
카탈로그	최상위 컨테이너인 카탈로그를 사용하면 네임스페이스와 테이블을 여러 카탈로그로 분할하여 논리적 그룹으로 정리할 수 있습니다.
네임스페이스	카탈로그 내에서 테이블을 구성하는 데 사용되는 논리적 그룹으로, 데이터베이스, 스키마 또는 디렉터리와 같은 기능을 합니다.
표	테이블에는 쿼리할 수 있는 행과 열의 정의가 포함됩니다.

지원되는 카탈로그

클라이언트를 구성할 때 창고 위치를 지정합니다. 이 선택에 따라 카탈로그가 작동하고 다른 Google Cloud서비스와 통합되는 방식이 결정됩니다.

카탈로그 유형	설명
Cloud Storage 버킷	카탈로그의 모든 데이터는 단일 Cloud Storage 버킷에 저장됩니다. 여러 버킷에 공유된 데이터의 경우 여러 카탈로그가 필요합니다.
BigQuery 제휴	Iceberg REST 카탈로그를 사용하여 BigQuery에 표시되는 테이블을 관리하고 쿼리할 수 있습니다. 자세한 내용은 BigQuery에서 카탈로그 페더레이션 사용을 참고하세요.

카탈로그 창고 세부정보

권장

Cloud Storage 버킷 창고 (gs://): 카탈로그가 지정된 Cloud Storage 버킷에서 Iceberg 메타데이터와 데이터 파일을 직접 관리하는 표준 접근 방식입니다. 이 옵션을 사용하면 데이터 레이아웃을 직접 제어할 수 있으며 세분화된 액세스 제어를 위한 인증서 판매를 지원합니다. 이를 통해 Apache Iceberg용 BigLake 테이블을 만들고 관리할 수 있습니다.

중요: Cloud Storage 버킷을 창고로 사용하는 카탈로그의 경우 카탈로그 이름이 카탈로그 리소스의 식별자이기도 합니다.

예를 들어 카탈로그를 저장하기 위해 버킷을 만들고 이름을 iceberg-bucket로 지정한 경우 카탈로그 이름과 버킷 이름이 모두 iceberg-bucket입니다. 이는 나중에 BigQuery에서 P.C.N.T. 구문을 사용하여 카탈로그를 쿼리할 때 사용됩니다. 예를 들면 my-project.biglake-catalog-id.quickstart_namespace.quickstart_table입니다.

기존

BigQuery 페더레이션 (bq://): 이 방법을 사용하면 카탈로그 리소스를 만들지 않고도 Iceberg REST 카탈로그를 사용하여 BigQuery에 표시되는 테이블을 관리하고 쿼리할 수 있습니다. 자세한 내용은 BigQuery에서 카탈로그 페더레이션 사용을 참고하세요.

P.C.N.T 명명 구조

BigQuery에서 BigLake metastore 테이블을 쿼리할 때는 P.C.N.T라고도 하는 4부분 이름 지정 구조를 사용합니다.

Project: 카탈로그를 소유하는 Google Cloud 프로젝트 ID입니다.
Catalog: BigLake metastore 카탈로그의 이름입니다.
Namespace: Iceberg 네임스페이스 (BigQuery 데이터 세트와 동일)입니다.
Table: 테이블의 이름입니다.

예를 들면 my-project.biglake-catalog-id.my-namespace.my-table입니다.

Iceberg REST 카탈로그 설정

BigLake metastore에서 Apache Iceberg REST 카탈로그를 사용할 때 따라야 하는 일반적인 단계는 다음과 같습니다.

Cloud Storage 또는 BigQuery 중에서 카탈로그 데이터 웨어하우스 위치를 이해하고 선택합니다.
Cloud Storage gs:// 창고를 사용하는 경우 창고 위치를 가리키는 카탈로그를 만듭니다.
Iceberg REST 카탈로그를 사용하도록 클라이언트 애플리케이션을 구성합니다.
테이블을 정리할 네임스페이스 또는 스키마를 만듭니다.
구성된 클라이언트를 사용하여 테이블을 만들고 쿼리합니다.

카탈로그 만들기

최종 사용자 사용자 인증 정보 또는 사용자 인증 정보 제공 모드를 사용하는 카탈로그를 만들 수 있습니다.

최종 사용자 인증 정보를 사용하면 카탈로그에서 액세스하는 최종 사용자의 ID를 승인 확인을 위해 Cloud Storage에 전달합니다.
사용자 인증 정보 제공은 BigLake Metastore 관리자가 BigLake Metastore 리소스에 대한 권한을 직접 제어할 수 있도록 하는 스토리지 액세스 위임 메커니즘으로, 카탈로그 사용자가 Cloud Storage 버킷에 직접 액세스할 필요가 없습니다. BigLake 관리자가 특정 데이터 파일에 대한 사용자 권한을 부여할 수 있습니다.

최종 사용자 인증 정보

콘솔

Google Cloud 콘솔에서 BigLake 페이지를 엽니다.

BigLake로 이동
카탈로그 만들기를 클릭합니다.
Cloud Storage 버킷 선택 필드에 카탈로그와 함께 사용할 Cloud Storage 버킷의 이름을 입력합니다. 또는 찾아보기를 클릭하여 기존 버킷을 선택하거나 새 버킷을 만듭니다. Cloud Storage 버킷당 하나의 카탈로그만 있을 수 있습니다.
Authentication method(인증 방법)에서 End-user credentials(최종 사용자 인증 정보)을 선택합니다.
만들기를 클릭합니다.

gcloud

gcloud beta biglake iceberg catalogs create 명령어를 사용합니다.

gcloud beta biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

다음을 바꿉니다.

CATALOG_NAME: 카탈로그 이름입니다. Apache Iceberg용 관리형 BigLake 테이블의 경우 이 이름이 REST 카탈로그와 함께 사용되는 Cloud Storage 버킷 ID와 일치하는 경우가 많습니다. 예를 들어 버킷이 gs://bucket-id인 경우 카탈로그 이름은 bucket-id일 수 있습니다. 이 이름은 BigQuery에서 이러한 테이블을 쿼리할 때 카탈로그 식별자로도 사용됩니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

사용자 인증 정보 벤더 제공 모드

카탈로그 관리자는 카탈로그를 만들거나 업데이트할 때 사용자 인증 정보 판매를 사용 설정합니다. 카탈로그 사용자는 Iceberg REST 카탈로그를 구성할 때 액세스 위임을 지정하여 범위가 축소된 스토리지 사용자 인증 정보를 반환하도록 Iceberg REST 카탈로그에 지시할 수 있습니다.

콘솔

Google Cloud 콘솔에서 BigLake 페이지를 엽니다.

BigLake로 이동
카탈로그 만들기를 클릭합니다. 카탈로그 만들기 페이지가 열립니다.
Cloud Storage 버킷 선택에 카탈로그와 함께 사용할 Cloud Storage 버킷의 이름을 입력합니다. 또는 찾아보기를 클릭하여 기존 버킷 목록에서 선택하거나 새 버킷을 만듭니다. Cloud Storage 버킷당 하나의 카탈로그만 있을 수 있습니다.
인증 방법에서 사용자 인증 정보 벤더 제공 모드를 선택합니다.
만들기를 클릭합니다.

카탈로그가 생성되고 카탈로그 세부정보 페이지가 열립니다.
인증 방법에서 버킷 권한 설정을 클릭합니다.
대화상자에서 확인을 클릭합니다.

이렇게 하면 카탈로그의 서비스 계정에 스토리지 버킷에 대한 스토리지 객체 사용자 역할이 있는지 확인됩니다.

클라이언트 애플리케이션 구성

카탈로그를 만든 후 이를 사용하도록 클라이언트 애플리케이션을 구성합니다. 이 예에서는 사용자 인증 정보 판매를 사용하거나 사용하지 않고 구성하는 방법을 보여줍니다.

클러스터

Dataproc에서 Iceberg REST 카탈로그와 함께 Spark를 사용하려면 먼저 Iceberg 구성요소가 포함된 클러스터를 만드세요.

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REGION: Dataproc 클러스터의 리전입니다.
DATAPROC_VERSION: Dataproc 이미지 버전(예: 2.2)

클러스터를 만든 후 Iceberg REST 카탈로그를 사용하도록 Spark 세션을 구성합니다.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

다음을 바꿉니다.

CATALOG_NAME: Iceberg REST 카탈로그의 이름입니다.
APP_NAME: Spark 세션의 이름입니다.
WAREHOUSE_PATH: 창고의 경로입니다. gs://CLOUD_STORAGE_BUCKET_NAME를 사용합니다. BigQuery 카탈로그 제휴를 사용하려면 BigQuery에서 카탈로그 제휴 사용을 참고하세요.
PROJECT_ID: Iceberg REST 카탈로그 사용 요금이 청구되는 프로젝트입니다. Cloud Storage 버킷을 소유한 프로젝트와 다를 수 있습니다. REST API를 사용할 때의 프로젝트 구성에 관한 자세한 내용은 시스템 매개변수를 참조하세요.

사용자 인증 정보 판매로 구성

인증 정보 판매를 사용하려면 인증 정보 판매 모드의 카탈로그를 사용하고 SparkSession 빌더에 다음 줄을 추가하여 값이 vended-credentials인 X-Iceberg-Access-Delegation 헤더를 Iceberg REST 카탈로그 요청에 추가해야 합니다.

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

사용자 인증 정보 벤더 제공이 포함된 예

다음 예에서는 사용자 인증 정보 판매를 사용하여 쿼리 엔진을 구성합니다.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

자세한 내용은 Iceberg 문서의 RESTCatalog의 헤더 섹션을 참고하세요.

Dataproc 클러스터는 다음 출시에서 Iceberg용 Google 승인 흐름을 지원합니다.

Compute Engine 기반 Dataproc 2.2 이미지 버전 2.2.65 이상
Compute Engine 2.3 이미지 버전 2.3.11 이상의 Dataproc

서버리스

다음 구성으로 PySpark 일괄 워크로드를 Google Cloud Apache Spark용 서버리스에 제출합니다.

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

다음을 바꿉니다.

PYSPARK_FILE: PySpark 애플리케이션 파일의 gs:// Cloud Storage 경로입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REGION: Dataproc 일괄 워크로드의 리전입니다.
RUNTIME_VERSION: Apache Spark용 서버리스 런타임 버전(예: 2.2)
CATALOG_NAME: Iceberg REST 카탈로그의 이름입니다.
WAREHOUSE_PATH: 창고의 경로입니다. gs://CLOUD_STORAGE_BUCKET_NAME를 사용합니다. BigQuery 카탈로그 제휴를 사용하려면 BigQuery에서 카탈로그 제휴 사용을 참고하세요.

사용자 인증 정보 판매로 구성

사용자 인증 정보 판매를 사용하려면 사용자 인증 정보 판매 모드의 카탈로그를 사용하고 Apache Spark용 서버리스 구성에 다음 줄을 추가하여 값이 vended-credentials인 X-Iceberg-Access-Delegation 헤더를 Iceberg REST 카탈로그 요청에 추가해야 합니다.

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

사용자 인증 정보 벤더 제공이 포함된 예

다음 예에서는 사용자 인증 정보 판매를 사용하여 쿼리 엔진을 구성합니다.

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

자세한 내용은 Iceberg 문서의 RESTCatalog의 헤더 섹션을 참고하세요.

Apache Spark용 서버리스는 다음 런타임 버전에서 Iceberg용 Google 승인 흐름을 지원합니다.

Apache Spark용 서버리스 2.2 런타임 2.2.60 이상
Apache Spark용 서버리스 2.3 런타임 2.3.10 이상

Trino

Iceberg REST 카탈로그와 함께 Trino를 사용하려면 Trino 구성요소가 있는 Dataproc 클러스터를 만들고 gcloud dataproc clusters create --properties 플래그를 사용하여 카탈로그 속성을 구성합니다. 다음 예시에서는 CATALOG_NAME이라는 Trino 카탈로그를 만듭니다.

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

다음을 바꿉니다.

CLUSTER_NAME: 클러스터 이름입니다.
REGION: Dataproc 클러스터 리전입니다.
DATAPROC_VERSION: Dataproc 이미지 버전(예: 2.2)
NETWORK_ID: 클러스터 네트워크 ID입니다. 자세한 내용은 Dataproc 클러스터 네트워크 구성을 참고하세요.
CATALOG_NAME: Iceberg REST 카탈로그를 사용하는 Trino 카탈로그의 이름입니다.
WAREHOUSE_PATH: 창고의 경로입니다. gs://CLOUD_STORAGE_BUCKET_NAME를 사용합니다.
PROJECT_ID: BigLake Metastore에 사용할 Google Cloud 프로젝트 ID입니다.

클러스터를 만든 후 기본 VM 인스턴스에 연결하고 Trino CLI를 사용합니다.

trino --catalog=CATALOG_NAME

Dataproc Trino는 다음 출시에서 Iceberg용 Google 승인 흐름을 지원합니다.

Compute Engine 기반 Dataproc 2.2 런타임 버전 2.2.65 이상
Compute Engine 기반 Dataproc 2.3 런타임 버전 2.3.11 이상
Compute Engine 기반 Dataproc 3.0은 지원되지 않습니다.

사용자 인증 정보 판매로 구성

Dataproc Trino에서는 사용자 인증 정보 판매가 지원되지 않습니다.

Iceberg 1.10 이상

오픈소스 Iceberg 1.10 이상 버전에는 GoogleAuthManager에서 Google 승인 흐름을 기본적으로 지원합니다. 다음은 BigLake metastore Iceberg REST 카탈로그를 사용하도록 Apache Spark를 구성하는 방법의 예입니다.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

다음을 바꿉니다.

CATALOG_NAME: Iceberg REST 카탈로그의 이름입니다.
APP_NAME: Spark 세션의 이름입니다.
WAREHOUSE_PATH: 창고의 경로입니다. gs://CLOUD_STORAGE_BUCKET_NAME를 사용합니다. BigQuery 카탈로그 제휴를 사용하려면 BigQuery에서 카탈로그 제휴 사용을 참고하세요.
PROJECT_ID: Iceberg REST 카탈로그 사용 요금이 청구되는 프로젝트입니다. Cloud Storage 버킷을 소유한 프로젝트와 다를 수 있습니다. REST API를 사용할 때의 프로젝트 구성에 관한 자세한 내용은 시스템 매개변수를 참조하세요.

사용자 인증 정보 판매로 구성

위 예시에서는 사용자 인증 정보 판매가 사용되지 않습니다. 인증 정보 제공을 사용하려면 인증 정보 제공 모드의 카탈로그를 사용하고 SparkSession 빌더에 다음 줄을 추가하여 값이 vended-credentials인 X-Iceberg-Access-Delegation 헤더를 Iceberg REST 카탈로그 요청에 추가해야 합니다.

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

사용자 인증 정보 벤더 제공이 포함된 예

다음 예에서는 사용자 인증 정보 판매를 사용하여 쿼리 엔진을 구성합니다.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

자세한 내용은 Iceberg 문서의 RESTCatalog의 헤더 섹션을 참고하세요.

이전 Iceberg 출시

1.10 이전의 오픈소스 Iceberg 버전의 경우 다음을 사용하여 세션을 구성하여 표준 OAuth 인증을 구성할 수 있습니다.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

다음을 바꿉니다.

CATALOG_NAME: Iceberg REST 카탈로그의 이름입니다.
APP_NAME: Spark 세션의 이름입니다.
WAREHOUSE_PATH: 창고의 경로입니다. gs://CLOUD_STORAGE_BUCKET_NAME를 사용합니다. BigQuery 카탈로그 제휴를 사용하려면 BigQuery에서 카탈로그 제휴 사용을 참고하세요.
PROJECT_ID: Iceberg REST 카탈로그 사용 요금이 청구되는 프로젝트입니다. Cloud Storage 버킷을 소유한 프로젝트와 다를 수 있습니다. REST API를 사용할 때의 프로젝트 구성에 관한 자세한 내용은 시스템 매개변수를 참조하세요.
TOKEN: 1시간 동안 유효한 인증 토큰(예: gcloud auth application-default print-access-token을 사용하여 생성된 토큰)

사용자 인증 정보 판매로 구성

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

사용자 인증 정보 벤더 제공이 포함된 예

다음 예에서는 사용자 인증 정보 판매를 사용하여 쿼리 엔진을 구성합니다.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

자세한 내용은 Iceberg 문서의 RESTCatalog의 헤더 섹션을 참고하세요.

네임스페이스 또는 스키마 만들기

클라이언트를 구성한 후 네임스페이스 또는 스키마를 만들어 테이블을 정리합니다. 네임스페이스 또는 스키마를 만드는 구문은 쿼리 엔진에 따라 다릅니다. 다음 예에서는 Spark와 Trino를 사용하여 이를 만드는 방법을 보여줍니다.

Spark

Cloud Storage 웨어하우스

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

NAMESPACE_NAME을 네임스페이스 이름으로 바꿉니다.

Trino

Cloud Storage 웨어하우스

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

다음을 바꿉니다.

CATALOG_NAME: Iceberg REST 카탈로그를 사용하는 Trino 카탈로그의 이름입니다.
SCHEMA_NAME: 스키마의 이름입니다.

BigQuery에서 테이블 쿼리

BigQuery의 Iceberg REST 카탈로그를 통해 만든 테이블을 쿼리하는 방법은 Cloud Storage 버킷 웨어하우스 또는 BigQuery 페더레이션을 사용하는지 여부에 따라 다릅니다.

Cloud Storage 버킷 웨어하우스: gs:// 웨어하우스 경로로 클라이언트를 구성한 경우 4부분 이름 (P.C.N.T) project.catalog.namespace.table를 사용하여 BigQuery에서 테이블을 쿼리합니다. catalog 구성요소는 BigLake metastore 카탈로그 리소스의 이름입니다. 자세한 내용은 테이블 쿼리를 참고하세요.
BigQuery 페더레이션: bq:// 웨어하우스 경로로 클라이언트를 구성한 경우 생성한 테이블이 BigQuery에 표시되며 표준 BigQuery SQL을 사용하여 직접 쿼리할 수 있습니다.
```
SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;
```
다음을 바꿉니다.
- NAMESPACE_NAME: 네임스페이스의 이름입니다.
- TABLE_NAME: 테이블의 이름

BigQuery에서 카탈로그 페더레이션 사용

Iceberg REST 카탈로그 인터페이스를 사용하여 BigQuery에 표시되는 테이블을 관리하고 쿼리할 수 있습니다. BigQuery 제휴 카탈로그는 카탈로그 리소스를 만들 필요가 없으며 BigQuery API가 사용 설정된 모든 프로젝트에서 사용할 수 있습니다. 그러면 다음과 같은 이점을 얻을 수 있습니다.

BigQuery에서 외부 Iceberg 테이블을 만들고 관리합니다.
Iceberg REST 카탈로그를 사용하여 BigQuery의 Apache Iceberg용 BigLake 테이블을 쿼리합니다.

이러한 리소스는 BigQuery에서 관리하므로 해당 필요한 권한이 있어야 합니다. 제휴 카탈로그에는 사용자 인증 정보 제공이 지원되지 않습니다.

연합을 사용 설정하려면 Iceberg REST 카탈로그 사용의 클라이언트 구성 예에 있는 WAREHOUSE_PATH 필드에서 bq://projects/PROJECT_ID 창고 형식으로 클라이언트를 구성합니다. bq://projects/PROJECT_ID/locations/LOCATION 형식을 사용하여 향후 요청을 단일 위치로 제한하기 위해 BigQuery 위치를 포함할 수도 있습니다.

제휴를 위해 클라이언트를 구성한 후 제휴 테이블의 네임스페이스를 만들 수 있습니다.

Spark

BigQuery 카탈로그 페더레이션을 사용하려면 LOCATION 및 DBPROPERTIES 절을 포함하세요.

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

다음을 바꿉니다.

NAMESPACE_NAME: 네임스페이스 이름
BUCKET_NAME: 카탈로그와 함께 사용하는 Cloud Storage 버킷입니다.
LOCATION: BigQuery 위치입니다. 기본값은 US 멀티 리전입니다.

Trino

BigQuery 카탈로그 페더레이션을 사용하려면 LOCATION 및 gcp-region 속성을 포함하세요.

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

다음을 바꿉니다.

CATALOG_NAME: Iceberg REST 카탈로그를 사용하는 Trino 카탈로그의 이름입니다.
SCHEMA_NAME: 스키마의 이름입니다.
BUCKET_NAME: 카탈로그와 함께 사용하는 Cloud Storage 버킷입니다.
LOCATION: BigQuery 위치입니다. 기본값은 US 멀티 리전입니다.

가격 책정

자세한 가격 정보는 BigLake 가격 책정을 참고하세요.

다음 단계

Google Cloud 콘솔에서 카탈로그를 관리하는 방법을 알아보세요.
Apache Iceberg용 BigLake 테이블에 대해 알아봅니다.

BigLake metastore Iceberg REST 카탈로그 사용 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

제한사항

카탈로그 리소스

Apache Iceberg REST 카탈로그 리소스

지원되는 카탈로그

카탈로그 창고 세부정보

P.C.N.T 명명 구조

Iceberg REST 카탈로그 설정

카탈로그 만들기

최종 사용자 인증 정보

콘솔

gcloud

사용자 인증 정보 벤더 제공 모드

콘솔

클라이언트 애플리케이션 구성

클러스터

사용자 인증 정보 판매로 구성

사용자 인증 정보 벤더 제공이 포함된 예

서버리스

사용자 인증 정보 판매로 구성

사용자 인증 정보 벤더 제공이 포함된 예

Trino

사용자 인증 정보 판매로 구성

Iceberg 1.10 이상

사용자 인증 정보 판매로 구성

사용자 인증 정보 벤더 제공이 포함된 예

이전 Iceberg 출시

사용자 인증 정보 판매로 구성

사용자 인증 정보 벤더 제공이 포함된 예

네임스페이스 또는 스키마 만들기

Spark

Cloud Storage 웨어하우스

Trino

Cloud Storage 웨어하우스

BigQuery에서 테이블 쿼리

BigQuery에서 카탈로그 페더레이션 사용

Spark

Trino

가격 책정

다음 단계

BigLake metastore Iceberg REST 카탈로그 사용