Spark 및 Lakehouse 런타임 카탈로그를 사용하여 페더레이션 카탈로그 쿼리

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Lakehouse 런타임 카탈로그에서 크로스 클라우드 데이터 액세스를 설정한 후 파일을 마이그레이션하거나 별도의 클라우드 스토리지 사용자 인증 정보를 관리하지 않고도 Managed Service for Apache Spark에서 원격 Iceberg 테이블을 쿼리할 수 있습니다.

Lakehouse 런타임 카탈로그는 사용자 인증 정보 제공을 통해 메타데이터 동기화 및 보안 데이터 액세스를 처리합니다. Spark가 제휴 테이블을 쿼리하면 Lakehouse 런타임 카탈로그가 카탈로그 메타데이터를 변환하고 Spark가 Amazon S3 또는 Cloud Storage에서 데이터를 읽을 수 있도록 단기 범위 지정 사용자 인증 정보를 발급하여 테이블을Google Cloud 환경에 로컬인 것처럼 처리합니다.

지원되는 페더레이션 카탈로그 유형

Managed Service for Apache Spark는 Lakehouse 런타임 카탈로그 Iceberg REST 카탈로그 엔드포인트를 통해 다음 페더레이션 카탈로그 유형의 쿼리를 지원합니다.

페더레이션 카탈로그 유형	지원되는 스토리지 백엔드	Lakehouse 런타임 카탈로그의 설정 가이드
AWS Glue Data Catalog	Amazon S3 (s3:// - 기본 AWS 계정 카탈로그 또는 Amazon S3 테이블 버킷)	AWS Glue에 연결
Databricks Unity Catalog	Amazon S3 (s3://) 또는 Cloud Storage (gs://) 외부 위치	Databricks Unity Catalog에 연결
Snowflake Horizon Catalog	Amazon S3 (s3://) 또는 Cloud Storage (gs://)	Snowflake Horizon Catalog에 연결

각 저장소 제공업체의 카탈로그 준비 요구사항과 기본 Spark 파라미터 정의에 대한 자세한 내용은 Lakehouse 런타임 카탈로그에서 원격 데이터 쿼리 및 Spark 구성 파라미터를 참조하세요.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that you have the permissions required to complete this guide.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataproc, BigLake, and BigQuery APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that you have the permissions required to complete this guide.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataproc, BigLake, and BigQuery APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. 원격 카탈로그에 Iceberg 테이블이 있는지 확인합니다.
2. 원격 카탈로그 제공업체의 Lakehouse 런타임 카탈로그에서 크로스 클라우드 연결 및 페더레이션 카탈로그를 설정합니다.
   • AWS Glue Data Catalog
   • Databricks Unity Catalog
   • Snowflake Horizon Catalog

필요한 Identity and Access Management (IAM) 역할

이 페이지의 예시를 실행하려면 특정 IAM 역할이 필요합니다. 조직 정책에 따라 이러한 역할이 이미 부여되었을 수 있습니다. 역할 부여를 확인하려면 역할을 부여해야 하나요?를 참조하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

필요한 역할은 워크로드 실행 방식에 따라 다릅니다. Managed Service for Apache Spark 클러스터 및 Managed Service for Apache Spark 서버리스 런타임 2.3 이하 버전은 워크로드를 서비스 계정으로 실행합니다. Managed Service for Apache Spark 서버리스 런타임 3.0 이상은 기본적으로 최종 사용자 인증 정보 (EUC)를 사용하여 워크로드를 실행하므로 서비스 계정 대신 사용자 계정에 데이터 액세스 역할을 부여합니다. 3.0 이상 런타임에 커스텀 서비스 계정을 지정하면 워크로드가 서비스 계정 사용자 인증 정보로 실행됩니다. 자세한 내용은 서버리스 배포 역할을 참조하세요.

사용자 역할

Managed Service for Apache Spark 클러스터를 만들거나, 일괄 워크로드를 제출하거나, 대화형 세션을 만드는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 클러스터 또는 서버리스 런타임 2.3 이하를 사용합니다.
  • 프로젝트에 대한 Dataproc 편집자 역할 (roles/dataproc.editor)
  • Compute Engine 기본 서비스 계정 또는 커스텀 서비스 계정의 서비스 계정 사용자 (roles/iam.serviceAccountUser)
• 서버리스 런타임 3.0 이상 사용: 프로젝트에 대한 Dataproc Serverless 편집자 (roles/dataproc.serverlessEditor)
• 서버리스 런타임 3.0 이상에서 최종 사용자 인증 정보로 페더레이션 테이블 읽기: 페더레이션 카탈로그가 포함된 프로젝트에 대한 BigLake 뷰어 (roles/biglake.viewer)
• 서버리스 런타임 3.0 이상에서 서비스 계정 사용자 인증 정보 사용: 맞춤 서비스 계정에 대한 서비스 계정 사용자 (roles/iam.serviceAccountUser)

서비스 계정 역할

워크로드를 실행하는 서비스 계정에 다음 역할을 부여합니다. Managed Service for Apache Spark 서버리스 런타임 3.0 이상에서는 워크로드가 서비스 계정 사용자 인증 정보로 실행되는 경우에만 이러한 역할이 필요합니다.

Compute Engine 기본 서비스 계정 또는 커스텀 서비스 계정에 Managed Service for Apache Spark 작업을 실행하고 통합 테이블을 읽는 데 필요한 권한이 있는지 확인하려면 관리자에게 Compute Engine 기본 서비스 계정 또는 커스텀 서비스 계정에 다음 IAM 역할을 부여해 달라고 요청하세요.

중요: 이러한 역할을 사용자 계정이 아닌 Compute Engine 기본 서비스 계정 또는 커스텀 서비스 계정에 부여해야 합니다. 올바른 주체에 역할을 부여하지 않으면 권한 오류가 발생할 수 있습니다.

• 클러스터 또는 서버리스 런타임 2.3 이하에서 Managed Service for Apache Spark 작업 실행: 프로젝트에 대한 Dataproc 작업자 (roles/dataproc.worker)
• 서버리스 런타임 3.0 이상에서 Managed Service for Apache Spark 작업을 실행합니다.
  • 프로젝트에 대한 Dataproc Serverless 노드 (roles/dataproc.serverlessNode)
  • 프로젝트에 대한 Dataproc 리소스 관리자 노드 서비스 에이전트 (roles/dataprocrm.nodeServiceAgent)
• 런타임 시 제휴 테이블 메타데이터 검색 및 읽기: 제휴 카탈로그가 포함된 프로젝트의 BigLake 뷰어 (roles/biglake.viewer)

클러스터를 만들거나, 일괄 워크로드를 제출하거나, 대화형 세션을 만들 때 Managed Service for Apache Spark 서비스 에이전트 ([e-mail])에 dataproc.lakehouse.catalog. 간소화된 구성 속성을 확인하는 데 필요한 권한이 있는지 확인하려면 관리자에게 페더레이션 카탈로그가 포함된 프로젝트의 Managed Service for Apache Spark 서비스 에이전트 ([e-mail])에 BigLake 뷰어 (roles/biglake.viewer) IAM 역할을 부여해 달라고 요청하세요.

중요: 이 역할은 사용자 계정이 아닌 Managed Service for Apache Spark 서비스 에이전트 ([e-mail])에 부여해야 합니다. 역할을 올바른 주 구성원에게 부여하지 않으면 권한 오류가 발생할 수 있습니다.

Amazon S3의 아웃바운드 네트워크 연결 구성

Amazon S3로 지원되는 페더레이션 카탈로그를 쿼리할 때 Managed Service for Apache Spark 서버리스 일괄 워크로드 및 대화형 세션과 내부 IP Managed Service for Apache Spark 클러스터는 기본 네트워크 구성으로 Amazon S3 엔드포인트에 연결할 수 없습니다. 워크로드 VPC 네트워크에서 Cloud Router 및 Cloud NAT를 프로비저닝하여 Amazon S3로의 아웃바운드 트래픽을 허용합니다.

gcloud compute routers create lakehouse-router \
    --network=NETWORK_NAME \
    --region=REGION

gcloud compute routers nats create lakehouse-nat \
    --router=lakehouse-router \
    --auto-allocate-nat-external-ips \
    --nat-all-subnet-ip-ranges \
    --region=REGION

다음을 바꿉니다.

• NETWORK_NAME: Managed Service for Apache Spark 클러스터, 일괄 워크로드 또는 대화형 세션의 VPC 네트워크입니다(예: default).
• REGION: Managed Service for Apache Spark 클러스터, 일괄 워크로드 또는 대화형 세션의 Google Cloud리전입니다.

Managed Service for Apache Spark 구성 및 페더레이션 테이블 쿼리

Lakehouse 런타임 카탈로그의 페더레이션 카탈로그에 연결하도록 Managed Service for Apache Spark 클러스터, 서버리스 일괄 워크로드 또는 대화형 세션을 구성할 수 있습니다. 이러한 Managed Service for Apache Spark 리소스는 dataproc.lakehouse.catalog.CATALOG_NAME 간소화된 구성 속성 (권장)을 지원합니다. 이 속성은 Lakehouse 런타임 카탈로그에서 페더레이션 카탈로그 정의를 읽고 스토리지 io-impl 및 사용자 인증 정보 판매 헤더를 포함하여 필요한 Iceberg REST 카탈로그 Spark 속성을 생성합니다 (속성의 클러스터 형식은 dataproc: 프리픽스를 추가함).

간소화된 구성과 수동 구성 모두 Iceberg에 Google 승인 (GoogleAuthManager)을 사용하며, 이를 위해서는 다음 클러스터 이미지 또는 서버리스 런타임 버전 중 하나가 필요합니다.

• Managed Service for Apache Spark 클러스터: 2.2 이미지 버전 2.2.65 이상 또는 2.3 이미지 버전 2.3.11 이상
• Managed Service for Apache Spark 서버리스 일괄 워크로드 및 대화형 세션: 2.2 런타임 2.2.60 이상, 2.3 런타임 2.3.10 이상 또는 3.0 런타임

서버리스 일괄 워크로드 및 대화형 세션의 경우 필요한 역할은 런타임 버전에 따라 다릅니다. 런타임 3.0 이상에서는 기본적으로 최종 사용자 인증 정보를 사용합니다. 자세한 내용은 필수 IAM 역할 및 서버리스 배포 역할을 참조하세요.

클러스터

간소화된 구성 속성 (권장)을 사용하거나 카탈로그 속성을 수동으로 지정하여 Iceberg 선택적 구성요소가 있는 Managed Service for Apache Spark 클러스터를 만듭니다.

속성을 사용한 간소화된 구성 (권장)

페더레이션 카탈로그 속성을 사용하여 클러스터를 만듭니다.

gcloud dataproc clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --region=REGION \
  --image-version=IMAGE_VERSION \
  --optional-components=ICEBERG,JUPYTER \
  --enable-component-gateway \
  --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,spark:spark.sql.defaultCatalog=CATALOG_NAME"

다음을 바꿉니다.

• CLUSTER_NAME: 클러스터 이름입니다.
• PROJECT_ID:Google Cloud 프로젝트 ID입니다.
• REGION: 클러스터의 Google Cloud리전(예: us-central1)
• IMAGE_VERSION: Managed Service for Apache Spark 이미지 버전(예: 2.3-debian12) 지원되는 버전은 이 섹션 앞부분의 요구사항을 참조하세요.
• CATALOG_NAME: 로컬 Spark 카탈로그의 이름(예: federated_catalog) FEDERATED_CATALOG_NAME과 동일할 수 있습니다.
• FEDERATED_CATALOG_NAME: 시작하기 전에에서 만든 페더레이션 카탈로그의 ID입니다.

참고: --properties 플래그에 쉼표로 구분된 여러 카탈로그를 전달할 수 있습니다. 각 클러스터 카탈로그 속성에는 dataproc: 프리픽스가 필요합니다.

Snowflake Horizon Catalog 쿼리

Snowflake Horizon Catalog를 쿼리하는 경우 다음 사항에 유의하세요.

• Snowflake 스토리지: 간소화된 구성은 Amazon S3에 저장된 Snowflake 테이블을 지원합니다. Cloud Storage에 저장된 Snowflake 테이블의 경우 io-impl이 org.apache.iceberg.gcp.gcs.GCSFileIO로 설정된 수동 구성을 사용합니다.

• Snowflake STRING 열: Snowflake에서 테이블의 스토리지 직렬화 정책이 COMPATIBLE가 아닌 Snowflake STRING 열을 쿼리하는 중에 오류가 발생하면 Snowflake에서 스토리지 직렬화 정책을 COMPATIBLE로 변경하거나 --properties 플래그에 다음 속성을 추가하여 Spark에서 Parquet 벡터화를 사용 중지할 수 있습니다.

  spark:spark.sql.iceberg.vectorization.enabled=false,spark:spark.sql.catalog.CATALOG_NAME.table-override.read.parquet.vectorization.enabled=false
      

Jupyter 노트북 또는 PySpark 애플리케이션에서 카탈로그 구성을 지정하지 않고 SparkSession를 만듭니다.

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

APP_NAME을 Spark 애플리케이션 이름으로 바꿉니다.

수동 구성

간소화된 구성 속성을 사용하지 않는 경우 이 섹션의 앞부분에서 설명한 대로 dataproc:dataproc.lakehouse.catalog. 속성을 --properties 플래그에 전달하지 않고 클러스터를 만든 다음 SparkSession를 수동으로 구성합니다. 스토리지 제공업체 매개변수 값 목록은 Spark 구성 매개변수를 참고하세요.

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"

spark = SparkSession.builder.appName("APP_NAME") \
.config('spark.sql.defaultCatalog', catalog_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', 'bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_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}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
.config(f'spark.sql.catalog.{catalog_name}.io-impl', 'IO_IMPL') \
.config(f'spark.sql.catalog.{catalog_name}.s3.client-factory-impl', 'org.apache.iceberg.aws.s3.DefaultS3FileIOAwsClientFactory') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

IO_IMPL를 테이블이 포함된 스토리지의 FileIO 구현으로 바꿉니다.

• Amazon S3의 테이블: org.apache.iceberg.aws.s3.S3FileIO
• Cloud Storage의 테이블: org.apache.iceberg.gcp.gcs.GCSFileIO

s3.client-factory-impl 속성은 Amazon S3의 테이블에만 적용됩니다. Cloud Storage 테이블의 경우 이 줄을 생략합니다.

서버리스

간소화된 구성 속성 (권장)을 사용하거나 카탈로그 속성을 수동으로 지정하여 Managed Service for Apache Spark 서버리스에 PySpark 일괄 워크로드를 제출합니다.

속성을 사용한 간소화된 구성 (권장)

일괄 워크로드를 제출할 때 dataproc: 프리픽스 없이 페더레이션 카탈로그 속성을 전달합니다.

gcloud dataproc batches submit pyspark PYSPARK_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --version=RUNTIME_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,spark.sql.defaultCatalog=CATALOG_NAME"

다음을 바꿉니다.

• PYSPARK_FILE: PySpark 애플리케이션 파일의 gs:// Cloud Storage 경로입니다.
• PROJECT_ID:Google Cloud 프로젝트 ID입니다.
• REGION: 일괄 워크로드의 리전입니다.
• RUNTIME_VERSION: Managed Service for Apache Spark 서버리스 런타임 버전(예: 3.0) 지원되는 버전은 이 섹션 앞부분의 요구사항을 참조하세요. 필수 IAM 역할은 런타임 버전에 따라 다릅니다.
• CATALOG_NAME: 로컬 Spark 카탈로그의 이름입니다(예: federated_catalog). FEDERATED_CATALOG_NAME과 동일할 수 있습니다.
• FEDERATED_CATALOG_NAME: 시작하기 전에에서 만든 페더레이션 카탈로그의 ID입니다.

참고: 쉼표로 구분된 여러 카탈로그를 --properties 플래그에 전달할 수 있습니다.

Snowflake Horizon Catalog 쿼리

Snowflake Horizon Catalog를 쿼리하는 경우 다음 사항에 유의하세요.

• Snowflake 스토리지: 간소화된 구성은 Amazon S3에 저장된 Snowflake 테이블을 지원합니다. Cloud Storage에 저장된 Snowflake 테이블의 경우 io-impl를 org.apache.iceberg.gcp.gcs.GCSFileIO로 설정하여 수동 구성을 사용합니다.

• Snowflake STRING 열: Snowflake에서 테이블의 스토리지 직렬화 정책이 COMPATIBLE가 아닌 Snowflake STRING 열을 쿼리하는 중에 오류가 발생하면 Snowflake에서 스토리지 직렬화 정책을 COMPATIBLE로 변경하거나 --properties 플래그에 다음 속성을 추가하여 Spark에서 Parquet 벡터화를 사용 중지할 수 있습니다.

  spark.sql.iceberg.vectorization.enabled=false,spark.sql.catalog.CATALOG_NAME.table-override.read.parquet.vectorization.enabled=false
      

PySpark 애플리케이션 파일에서 카탈로그 구성을 지정하지 않고 SparkSession를 만듭니다.

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

수동 구성

간소화된 구성 속성을 사용하지 않는 경우 gcloud dataproc batches submit 명령어의 --properties 플래그를 사용하여 카탈로그 속성을 지정합니다. 저장소 제공업체 파라미터 값 목록은 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=bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_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.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\
spark.sql.catalog.CATALOG_NAME.io-impl=IO_IMPL,\
spark.sql.catalog.CATALOG_NAME.s3.client-factory-impl=org.apache.iceberg.aws.s3.DefaultS3FileIOAwsClientFactory,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

IO_IMPL를 테이블이 포함된 스토리지의 FileIO 구현으로 바꿉니다.

• Amazon S3의 테이블: org.apache.iceberg.aws.s3.S3FileIO
• Cloud Storage의 테이블: org.apache.iceberg.gcp.gcs.GCSFileIO

s3.client-factory-impl 속성은 Amazon S3의 테이블에만 적용됩니다. Cloud Storage 테이블의 경우 이 속성을 생략합니다.

서버리스

간소화된 구성 속성을 사용하여 (권장) 또는 카탈로그 속성을 수동으로 지정하여 DataprocSparkSession API를 통해 노트북에서 Managed Service for Apache Spark 서버리스 대화형 세션을 만듭니다.

속성을 사용한 간소화된 구성 (권장)

dataproc-spark-connect 패키지가 설치된 노트북(예: BigQuery Studio 노트북 또는 Vertex AI Workbench 노트북)에서 세션을 만들 때 dataproc: 접두사 없이 페더레이션 카탈로그 속성을 전달합니다.

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'

spark = DataprocSparkSession.builder.appName("APP_NAME") \
.dataprocSessionConfig(session_config) \
.config(f'dataproc.lakehouse.catalog.{catalog_name}', 'projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME') \
.config('spark.sql.defaultCatalog', catalog_name) \
.getOrCreate()

다음을 바꿉니다.

• CATALOG_NAME: 로컬 Spark 카탈로그의 이름입니다(예: federated_catalog). FEDERATED_CATALOG_NAME과 동일할 수 있습니다.
• RUNTIME_VERSION: Managed Service for Apache Spark 서버리스 런타임 버전(예: 3.0) 지원되는 버전은 이 섹션 앞부분의 요구사항을 참조하세요. 필요한 IAM 역할은 런타임 버전에 따라 다릅니다.
• APP_NAME: Spark 애플리케이션의 이름입니다.
• PROJECT_ID:Google Cloud 프로젝트 ID입니다.
• FEDERATED_CATALOG_NAME: 시작하기 전에에서 만든 페더레이션 카탈로그의 ID입니다.

세션 템플릿에서 이러한 속성을 설정할 수도 있습니다.

Snowflake Horizon Catalog 쿼리

Snowflake Horizon Catalog를 쿼리하는 경우 다음 사항에 유의하세요.

• Snowflake 스토리지: 간소화된 구성은 Amazon S3에 저장된 Snowflake 테이블을 지원합니다. Cloud Storage에 저장된 Snowflake 테이블의 경우 io-impl를 org.apache.iceberg.gcp.gcs.GCSFileIO로 설정하여 수동 구성을 사용합니다.

• Snowflake STRING 열: Snowflake에서 테이블의 스토리지 직렬화 정책이 COMPATIBLE가 아닌 Snowflake STRING 열을 쿼리할 때 오류가 발생하면 Snowflake에서 스토리지 직렬화 정책을 COMPATIBLE로 변경하거나 세션 빌더에 다음 .config() 호출을 추가하여 Spark에서 Parquet 벡터화를 사용 중지할 수 있습니다.

  .config('spark.sql.iceberg.vectorization.enabled', 'false') \
  .config(f'spark.sql.catalog.{catalog_name}.table-override.read.parquet.vectorization.enabled', 'false')
      

수동 구성

간소화된 구성 속성을 사용하지 않는 경우 세션을 만들 때 카탈로그 속성을 지정합니다. 스토리지 제공업체 파라미터 값 목록은 Spark 구성 매개변수를 참고하세요.

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'

spark = DataprocSparkSession.builder.appName("APP_NAME") \
.dataprocSessionConfig(session_config) \
.config('spark.sql.defaultCatalog', catalog_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', 'bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_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}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
.config(f'spark.sql.catalog.{catalog_name}.io-impl', 'IO_IMPL') \
.config(f'spark.sql.catalog.{catalog_name}.s3.client-factory-impl', 'org.apache.iceberg.aws.s3.DefaultS3FileIOAwsClientFactory') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

이 탭의 앞부분에 나오는 간소화된 구성 예시에 설명된 대로 RUNTIME_VERSION를 바꿉니다.

IO_IMPL를 테이블이 포함된 스토리지의 FileIO 구현으로 바꿉니다.

• Amazon S3의 테이블: org.apache.iceberg.aws.s3.S3FileIO
• Cloud Storage의 테이블: org.apache.iceberg.gcp.gcs.GCSFileIO

s3.client-factory-impl 속성은 Amazon S3의 테이블에만 적용됩니다. Cloud Storage 테이블의 경우 이 줄을 생략합니다.

통합 테이블 쿼리

Spark 세션을 구성한 후 PySpark 또는 Spark SQL을 사용하여 제휴 카탈로그의 테이블을 쿼리할 수 있습니다.

참고: dataproc.lakehouse.catalog. 속성은 카탈로그를 Spark에 등록하지만 기본 카탈로그로 설정하지는 않습니다. 이전 예시에서는 정규화되지 않은 테이블 이름을 사용할 수 있는 서버리스 spark.sql.defaultCatalog 또는 spark:spark.sql.defaultCatalog 클러스터 속성을 설정합니다. 이러한 속성을 생략하는 경우 다음 예와 같이 카탈로그 이름으로 테이블 이름을 한정해야 합니다.

1. PySpark DataFrame API를 사용하여 페더레이션 테이블을 읽습니다.

   df = spark.table("CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME")
   df.show(10, truncate=False)

   다음을 바꿉니다.

   • CATALOG_NAME: 로컬 Spark 카탈로그 이름입니다. spark.sql.defaultCatalog을 CATALOG_NAME로 설정한 경우 이 접두사를 생략할 수 있습니다.
   • NAMESPACE_NAME: 페더레이션 카탈로그의 네임스페이스(데이터베이스 또는 스키마)입니다.
   • TABLE_NAME: 페더레이션 카탈로그의 테이블 이름입니다.

2. Spark SQL을 사용하여 페더레이션 테이블을 쿼리합니다.

   spark.sql("""
       SELECT *
       FROM CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME
       LIMIT 10
   """).show()

제휴 카탈로그와 로컬 카탈로그 간에 데이터 조인 또는 구체화

페더레이션 카탈로그는 읽기 전용입니다. 원격 크로스 클라우드 데이터를 로컬 테이블과 조인하거나 페더레이션 쿼리 결과를 Cloud Storage에 구체화하려면 쉼표로 구분된 dataproc.lakehouse.catalog. 속성을 사용하여 Lakehouse 런타임 카탈로그에 페더레이션 카탈로그와 읽기-쓰기 카탈로그를 연결합니다.

클러스터

Managed Service for Apache Spark 클러스터 예시:

--properties="dataproc:dataproc.lakehouse.catalog.FEDERATED_SPARK_CATALOG=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,dataproc:dataproc.lakehouse.catalog.LOCAL_SPARK_CATALOG=projects/PROJECT_ID/catalogs/LOCAL_CATALOG_ID,spark:spark.sql.defaultCatalog=LOCAL_SPARK_CATALOG"

서버리스

Managed Service for Apache Spark 서버리스 일괄 워크로드 예시:

--properties="dataproc.lakehouse.catalog.FEDERATED_SPARK_CATALOG=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,dataproc.lakehouse.catalog.LOCAL_SPARK_CATALOG=projects/PROJECT_ID/catalogs/LOCAL_CATALOG_ID,spark.sql.defaultCatalog=LOCAL_SPARK_CATALOG"

서버리스

Managed Service for Apache Spark 서버리스 대화형 세션 예시:

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'

spark = DataprocSparkSession.builder.appName("APP_NAME") \
  .dataprocSessionConfig(session_config) \
  .config('dataproc.lakehouse.catalog.FEDERATED_SPARK_CATALOG', 'projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME') \
  .config('dataproc.lakehouse.catalog.LOCAL_SPARK_CATALOG', 'projects/PROJECT_ID/catalogs/LOCAL_CATALOG_ID') \
  .config('spark.sql.defaultCatalog', 'LOCAL_SPARK_CATALOG') \
  .getOrCreate()

이 페이지의 앞부분에 나오는 대화형 세션 예시에 설명된 대로 RUNTIME_VERSION을 바꿉니다.

이러한 속성을 설정한 후에는 페더레이션 카탈로그를 쿼리하고 결과를 로컬 Lakehouse 런타임 카탈로그의 테이블에 쓸 수 있습니다.

워크로드를 실행하는 주 구성원은 클러스터, 서버리스 런타임 2.3 이하, 서비스 계정 사용자 인증 정보가 있는 서버리스 런타임 3.0 이상의 서비스 계정입니다. 최종 사용자 인증 정보가 있는 서버리스 런타임 3.0 이상 (기본값)의 경우 주 구성원은 사용자 계정입니다.

워크로드를 실행하는 주 구성원에게 테이블 데이터를 로컬 카탈로그에 쓰는 데 필요한 권한이 있는지 확인하려면 관리자에게 워크로드를 실행하는 주 구성원에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 인증 정보 제공 모드에서 테이블 데이터 쓰기: 로컬 카탈로그가 포함된 프로젝트에 대한 BigLake 편집자 (roles/biglake.editor)
• 사용자 인증 정보 벤더 제공 모드가 아닌 모드에서 테이블 데이터 쓰기:
  • 로컬 카탈로그가 포함된 프로젝트에 대한 BigLake 편집자 (roles/biglake.editor)
  • 로컬 카탈로그와 연결된 모든 Cloud Storage 버킷에 대한 스토리지 객체 사용자 (roles/storage.objectUser)

다음 예시에서는 제휴 테이블에서 로컬 카탈로그에 테이블을 만듭니다.

spark.sql("""
    CREATE TABLE IF NOT EXISTS LOCAL_SPARK_CATALOG.LOCAL_NAMESPACE.materialized_table
    USING iceberg
    AS SELECT *
    FROM FEDERATED_SPARK_CATALOG.REMOTE_NAMESPACE.REMOTE_TABLE
""")

다음 단계

• Spark 및 Lakehouse 런타임 카탈로그로 레이크하우스 만들기
• Lakehouse 런타임 카탈로그에서 원격 데이터를 쿼리하는 방법 자세히 알아보기
• 크로스 클라우드 데이터 액세스 정보를 읽어보세요.
• 사용자 인증 정보 벤더 제공에 대해 알아봅니다.