"Managed Service for Apache Spark" is the new name for the product formerly known as "Dataproc on Compute Engine" (cluster deployment) and "Google Cloud Serverless for Apache Spark" (serverless deployment).

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Spark 和 Lakehouse 執行階段目錄查詢聯合目錄

在 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 資料表 bucket)	連線至 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，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $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.

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.

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

Enable the APIs

確認遠端目錄中有 Iceberg 資料表。
在 Lakehouse 執行階段目錄中，為遠端目錄供應商設定跨雲端連線和聯合目錄：

必要的 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 工作及讀取聯合資料表，請要求管理員將下列 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 Resource Manager 節點服務代理 (roles/dataprocrm.nodeServiceAgent)
在執行階段探索及讀取聯合資料表中繼資料：在包含聯合目錄的專案中，具備 BigLake 檢視者 (roles/biglake.viewer) 角色

為確保 Managed Service for Apache Spark 服務代理 (service-PROJECT_NUMBER@dataproc-accounts.iam.gserviceaccount.com) 具備必要權限，可在您建立叢集、提交批次工作負載或建立互動式工作階段時，解析 dataproc.lakehouse.catalog. 簡化設定屬性，請要求管理員在包含聯合目錄的專案中，將 BigLake 檢視者 (roles/biglake.viewer) IAM 角色授予 Managed Service for Apache Spark 服務代理 (service-PROJECT_NUMBER@dataproc-accounts.iam.gserviceaccount.com)。

重要事項：您必須將這個角色授予 Managed Service for Apache Spark 服務代理 (service-PROJECT_NUMBER@dataproc-accounts.iam.gserviceaccount.com)，而非您的使用者帳戶。如果未將角色授予正確的主體，可能會發生權限錯誤。

設定 Amazon S3 的傳出網路連線

查詢由 Amazon S3 支援的聯合目錄時，Managed Service for Apache Spark 無伺服器批次工作負載和互動式工作階段，以及內部 IP Managed Service for Apache Spark 叢集，無法使用預設網路設定連線至 Amazon S3 端點。在工作負載虛擬私有雲網路上佈建 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 叢集、批次工作負載或互動式工作階段的虛擬私有雲網路，例如 default。
REGION：Managed Service for Apache Spark 叢集、批次工作負載或互動式工作階段的 Google Cloud區域。

設定 Managed Service for Apache Spark 並查詢聯合資料表

您可以設定 Managed Service for Apache Spark 叢集、無伺服器批次工作負載或互動式工作階段，連線至 Lakehouse 執行階段目錄中的聯合目錄。這些 Managed Service for Apache Spark 資源支援 dataproc.lakehouse.catalog.CATALOG_NAME 簡化設定屬性 (建議)，可從 Lakehouse 執行階段目錄讀取聯合目錄定義，並產生必要的 Iceberg REST 目錄 Spark 屬性，包括儲存空間 io-impl 和憑證販售標頭 (屬性的叢集形式會加上 dataproc: 前置字元)。

簡化設定和手動設定都會使用 Google 授權來存取 Iceberg (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。

查詢 Snowflake Horizon Catalog

如要查詢 Snowflake Horizon Catalog，請注意下列事項：

Snowflake 儲存空間：簡化設定支援儲存在 Amazon S3 的 Snowflake 資料表。如果是儲存在 Cloud Storage 的 Snowflake 資料表，請使用手動設定，並將 io-impl 設為 org.apache.iceberg.gcp.gcs.GCSFileIO。
Snowflake STRING 欄：如果查詢 Snowflake STRING 欄時發生錯誤，且資料表在 Snowflake 的儲存空間序列化政策不是 COMPATIBLE，您可以在 Snowflake 將儲存空間序列化政策變更為 COMPATIBLE，或在 Spark 停用 Parquet 向量化，方法是在 --properties 旗標中新增下列屬性：
```
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 資料表，請省略這一行。

無伺服器

使用簡化的設定屬性 (建議做法)，或手動指定目錄屬性，將 PySpark 批次工作負載提交至 Managed Service for Apache Spark 無伺服器。

使用屬性簡化設定 (建議)

提交批次工作負載時，請傳遞不含 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。

查詢 Snowflake Horizon Catalog

如要查詢 Snowflake Horizon Catalog，請注意下列事項：

Snowflake 儲存空間：簡化設定支援儲存在 Amazon S3 的 Snowflake 資料表。如果是儲存在 Cloud Storage 的 Snowflake 資料表，請使用手動設定，並將 io-impl 設為 org.apache.iceberg.gcp.gcs.GCSFileIO。
Snowflake STRING 欄：如果查詢 Snowflake STRING 欄時發生錯誤，且資料表在 Snowflake 的儲存空間序列化政策不是 COMPATIBLE，您可以在 Snowflake 將儲存空間序列化政策變更為 COMPATIBLE，或在 Spark 停用 Parquet 向量化，方法是在 --properties 旗標中新增下列屬性：
```
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 資料表，請省略這項屬性。

無伺服器

使用簡化的設定屬性 (建議做法)，或手動指定目錄屬性，透過 ManagedSparkSession API 在 Notebook 中建立 Managed Service for Apache Spark 無伺服器互動式工作階段。

使用屬性簡化設定 (建議)

在已安裝 google-cloud-spark-connect 套件的筆記本 (例如 Google Cloud Data Agent Kit 筆記本或 Vertex AI Workbench 筆記本) 中，建立工作階段時，請傳遞不含 dataproc: 前置字元的聯合目錄屬性：

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

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

spark = ManagedSparkSession.builder.sessionId("SESSION_ID") \
.sessionConfig(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 無伺服器執行階段版本。google-cloud-spark-connect 必須使用 3.0 以上版本的執行階段。必要的 IAM 角色取決於執行階段版本。
SESSION_ID：Spark 工作階段的自訂 ID，例如 my-spark-session。
PROJECT_ID：Google Cloud 專案 ID。
FEDERATED_CATALOG_NAME：您在「事前準備」中建立的聯合目錄 ID。

您也可以在Google Cloud 控制台的「Create a runtime profile」(建立執行階段設定檔) 頁面，依序選取「Additional configuration」(其他設定) >「Metastore configuration」(Metastore 設定) 下方的「Lakehouse runtime catalog」(Lakehouse 執行階段目錄)，在執行階段設定檔 (工作階段範本) 中設定聯合目錄，或使用 gcloud CLI 或 Dataproc API 在工作階段範本中設定這些屬性。

查詢 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，或在 Spark 停用 Parquet 向量化，方法是在工作階段建構工具中新增下列 .config() 呼叫：
```
.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.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

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

spark = ManagedSparkSession.builder.sessionId("SESSION_ID") \
.sessionConfig(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 查詢聯合目錄中的資料表。

使用 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：聯合目錄中的資料表名稱。

使用 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.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

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

spark = ManagedSparkSession.builder.sessionId("SESSION_ID") \
  .sessionConfig(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 bucket 的 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 執行階段目錄查詢聯合目錄

支援的聯合目錄類型

事前準備

必要的 Identity and Access Management (IAM) 角色

使用者角色

服務帳戶角色

設定 Amazon S3 的傳出網路連線

設定 Managed Service for Apache Spark 並查詢聯合資料表

叢集

使用屬性簡化設定 (建議)

查詢 Snowflake Horizon Catalog

手動設定

無伺服器

使用屬性簡化設定 (建議)

查詢 Snowflake Horizon Catalog

手動設定

無伺服器

使用屬性簡化設定 (建議)

查詢 Snowflake Horizon Catalog

手動設定

查詢聯合資料表

彙整或具體化聯合和本機目錄中的資料

叢集

無伺服器

無伺服器

後續步驟