이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Iceberg REST 카탈로그와 함께 BigLake metastore 사용

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

Iceberg REST 카탈로그와 함께 사용하는 Iceberg 테이블을 Apache Iceberg용 BigLake 테이블(프리뷰)이라고 합니다. 오픈소스 엔진에서 만들고 Cloud Storage에 저장하는 Iceberg 테이블입니다. 오픈소스 엔진이나 BigQuery에서 읽을 수 있습니다. 쓰기는 오픈소스 엔진에서만 지원됩니다. 이 문서에서는 이러한 테이블을 BigLake Iceberg 테이블이라고 합니다.

시작하기 전에

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
선택사항: 관리자에게 사용자 인증 정보 판매를 처음 설정해 달라고 요청합니다.
선택사항: BigQuery metastore의 작동 방식과 이를 사용해야 하는 이유를 알아봅니다.

필요한 역할

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)

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

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

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

인증 정보 판매 모드는 BigLake Metastore 관리자가 BigLake Metastore 리소스에 대한 권한을 직접 제어할 수 있도록 지원하는 스토리지 액세스 위임 메커니즘으로, 카탈로그 사용자가 Cloud Storage 버킷에 직접 액세스할 필요가 없습니다. BigLake 관리자가 특정 데이터 파일에 대한 사용자 권한을 부여할 수 있습니다.

카탈로그 관리자가 Iceberg REST 카탈로그 클라이언트에서 사용자 인증 정보 판매를 사용 설정합니다.

카탈로그 사용자는 Iceberg REST 카탈로그 API 사양의 일부인 액세스 위임을 지정하여 권한이 축소된 스토리지 사용자 인증 정보를 반환하도록 Iceberg REST 카탈로그에 지시할 수 있습니다. 자세한 내용은 Iceberg REST 카탈로그로 쿼리 엔진 구성을 참고하세요.

카탈로그를 초기화하고 사용자 인증 정보 벤더 제공 모드를 사용 설정하려면 다음 단계를 따르세요.

다음 명령어를 사용하여 카탈로그를 초기화합니다.

curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
CLOUD_STORAGE_BUCKET_NAME: Iceberg 테이블을 저장하는 Cloud Storage 버킷의 이름입니다.

curl 명령어 출력은 다음과 비슷합니다. 카탈로그 접두사 값은 응답의 overrides.prefix 필드에서 확인할 수 있습니다.

{
  "overrides": {
    "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
    "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
  },
  "endpoints": [
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}",
    "HEAD /v1/{prefix}/namespaces/{namespace}",
    "DELETE /v1/{prefix}/namespaces/{namespace}",
    "POST /v1/{prefix}/namespaces/{namespace}/properties",
    "GET /v1/{prefix}/namespaces/{namespace}/tables",
    "POST /v1/{prefix}/namespaces/{namespace}/tables",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
  ]
}

다음 명령어를 사용하여 사용자 인증 정보 판매 모드를 사용 설정하고 권한을 부여할 서비스 계정을 추출합니다.

curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

PREFIX을 이전 명령어 출력의 prefix 필드로 바꿉니다.

curl 명령어 출력에는 다음과 유사한 서비스 계정이 포함됩니다.

{
  "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
  "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
  "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
}

이전 단계에서 추출한 BigLake 서비스 계정에 사용자 인증 정보 판매 모드를 사용하는 데 필요한 권한이 있는지 확인하려면 관리자에게 스토리지 버킷에 대한 스토리지 객체 사용자(roles/storage.objectUser) 역할을 부여해 달라고 요청하세요.

중요: 이 역할은 사용자 계정이 아닌 이전 단계에서 추출한 BigLake 서비스 계정에 부여해야 합니다. 역할을 올바른 주 구성원에게 부여하지 않으면 권한 오류가 발생할 수 있습니다.

제한사항

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

멀티 리전 버킷, 이중 리전 버킷, 커스텀 리전 배치가 있는 버킷은 지원되지 않습니다.
인증 정보 벤더 제공 모드를 사용하는 경우 io-impl 속성을 org.apache.iceberg.gcp.gcs.GCSFileIO로 설정해야 합니다. 기본값인 org.apache.iceberg.hadoop.HadoopFileIO는 지원되지 않습니다.

Iceberg REST 카탈로그 구성

클러스터

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', '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}.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 세션의 이름입니다.
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg 테이블을 저장하는 Cloud Storage 버킷의 이름입니다.
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 기반 Dataproc 2.3 이미지 버전 2.3.11 이상

서버리스

다음 구성으로 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=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"

다음을 바꿉니다.

PYSPARK_FILE: PySpark 애플리케이션 파일의 gs:// Cloud Storage 경로입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REGION: Dataproc 일괄 워크로드의 리전입니다.
RUNTIME_VERSION: Apache Spark용 서버리스 런타임 버전(예: 2.2)
CATALOG_NAME: Iceberg REST 카탈로그의 이름입니다.
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg 테이블을 저장하는 Cloud Storage 버킷의 이름입니다.

인증 정보 제공을 사용하려면 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=gs://CLOUD_STORAGE_BUCKET_NAME,\
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 카탈로그의 이름입니다.
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg 테이블을 저장하는 Cloud Storage 버킷의 이름입니다.
PROJECT_ID: BigLake metastore에 사용할 Google Cloud 프로젝트 ID입니다.

클러스터를 만든 후 SSH를 사용하여 기본 VM 인스턴스에 연결한 다음 다음과 같이 Trino CLI를 사용합니다.

trino

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

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

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', '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}.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 세션의 이름입니다.
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg 테이블을 저장하는 Cloud Storage 버킷의 이름입니다.
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', '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}.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 세션의 이름입니다.
CLOUD_STORAGE_BUCKET_NAME: BigLake Iceberg 테이블을 저장하는 Cloud Storage 버킷의 이름입니다.
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('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', '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

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

spark.sql("USE NAMESPACE_NAME;")

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

Trino

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

다음을 바꿉니다.

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

테이블 만들기

Spark

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

다음을 바꿉니다.

NAMESPACE_NAME: 네임스페이스의 이름입니다.
TABLE_NAME: 테이블의 이름입니다.

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

TABLE_NAME을 테이블 이름으로 바꿉니다.

표 나열

Spark

spark.sql("SHOW TABLES").show()

Trino

SHOW TABLES;

데이터를 테이블에 삽입

다음 예시에서는 샘플 데이터를 테이블에 삽입합니다.

Spark

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

테이블 쿼리

다음 예시에서는 테이블에서 모든 데이터를 선택합니다.

Spark

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino

SELECT * FROM TABLE_NAME;

다음 예시에서는 BigQuery에서 동일한 테이블을 쿼리합니다.

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

다음을 바꿉니다.

CLOUD_STORAGE_BUCKET_NAME: Iceberg REST 카탈로그의 Cloud Storage 버킷 이름입니다. 예를 들어 URI가 gs://iceberg_bucket이면 iceberg_bucket을 사용합니다.
NAMESPACE_OR_SCHEMA_NAME: Spark를 사용하는 경우 테이블 네임스페이스, Trino를 사용하는 경우 테이블 스키마 이름입니다.
TABLE_NAME: 테이블의 이름입니다.

테이블 스키마 변경

다음 예시에서는 테이블에 열을 추가합니다.

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

다음을 바꿉니다.

NAMESPACE_NAME: 네임스페이스의 이름입니다.
TABLE_NAME: 테이블의 이름입니다.

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

다음을 바꿉니다.

SCHEMA_NAME: 스키마 이름
TABLE_NAME: 테이블의 이름입니다.

표 삭제

다음 예시에서는 지정된 네임스페이스에서 테이블을 삭제합니다.

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

가격 책정

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

다음 단계

BigLake metastore로 Iceberg 리소스를 관리하는 방법에 대해 자세히 알아봅니다.
추가 BigLake metastore 기능에 대해 알아봅니다.