使用 Lakehouse 執行階段目錄、Spark 和 BigQuery 查詢 Iceberg 資料表

瞭解如何建立多值區目錄，藉此建立 Lakehouse 執行階段目錄，並使用 Lakehouse for Apache Iceberg。這項設定會建立受管理的中繼資料層，將開放原始碼處理引擎與 Google Cloud連結。

接著，您會執行 Managed Service for Apache Spark PySpark 工作，使用 Apache Iceberg REST 目錄端點建立 Lakehouse Iceberg REST 目錄資料表。

之後，您可以使用 project.catalog.namespace.table 語法，直接從 BigQuery 的 Google Cloud 主控台 查詢產生的資料表。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the BigLake, Dataproc APIs.

    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

  5. 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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the BigLake, Dataproc APIs.

    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

    8.

授予 IAM 角色

如要允許 Managed Service for Apache Spark PySpark 工作和 Lakehouse 執行階段目錄使用 Cloud Storage 和 BigQuery，請將必要角色授予對應的主體：

  1. 在 Google Cloud 控制台點選「Activate Cloud Shell」(啟用 Cloud Shell)。

    啟用 Cloud Shell

  2. 按一下 [授權]。

  3. 將「Dataproc Worker」角色授予專案的 Compute Engine 預設服務帳戶，Managed Service for Apache Spark 預設會使用這個帳戶，詳情請參閱「Managed Service for Apache Spark 服務帳戶」。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
    --role="roles/dataproc.worker"

  4. 將「服務使用情形用戶」角色授予專案的 Compute Engine 預設服務帳戶。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
    --role="roles/serviceusage.serviceUsageConsumer"

  5. 將「BigLake 編輯者」角色授予專案的 Compute Engine 預設服務帳戶。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
    --role="roles/biglake.editor"

  6. 將「BigQuery 資料編輯者」角色授予專案的 Compute Engine 預設服務帳戶。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')-compute@developer.gserviceaccount.com" \
    --role="roles/bigquery.dataEditor"

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID

建立 Lakehouse 執行階段目錄

建立 Lakehouse 執行階段目錄，管理 Iceberg 資料表的中繼資料。

  1. 在 Cloud Shell 中執行下列指令，建立多個 bucket (bl://) 並提供憑證：

    gcloud biglake iceberg catalogs create LAKEHOUSE_CATALOG_ID \
    --project=PROJECT_ID \
    --catalog-type=biglake \
    --default-location=gs://BUCKET_NAME \
    --credential-mode=vended-credentials

    更改下列內容：

    • LAKEHOUSE_CATALOG_ID：目錄的專屬名稱。
    • PROJECT_ID：您的 Google Cloud 專案 ID。
    • BUCKET_NAME：包含 PySpark 應用程式檔案的 Cloud Storage bucket 名稱。

  2. 將 bucket 的權限授予目錄的服務帳戶：

    1. 前往 Google Cloud 控制台的「Lakehouse」Lakehouse。

      前往 Lakehouse

    2. 按一下剛建立的目錄名稱 (LAKEHOUSE_CATALOG_ID)。

    3. 在「驗證方式」下方，按一下「設定 bucket 權限」。

    4. 在對話方塊中，按一下「確認」。這會驗證目錄的服務帳戶是否具備 bucket 的「Storage 物件使用者」角色。

建立及執行 PySpark 工作

如要建立及查詢 Iceberg 資料表，請先使用必要的 Spark SQL 陳述式建立 PySpark 工作。然後使用 Managed Service for Apache Spark 執行工作。

使用命名空間和表格建立 PySpark 指令碼

在文字編輯器中，建立名為 quickstart.py 的檔案，並加入下列內容。

這個 PySpark 指令碼會初始化 Spark 工作階段，以便對 Iceberg 目錄執行多項作業。如果命名空間不存在，指令碼會先建立命名空間。然後建立名為 quickstart_table 的 Iceberg 資料表，並使用基本結構定義。資料表建立完成後，指令碼會插入三列資料。最後，它會查詢資料表，擷取所有插入的記錄。

在下一個步驟中執行 gcloud dataproc batches submit pyspark 工作時，會使用這些值。

from pyspark.sql import SparkSession

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

# Create a namespace (dataset) if it doesn't exist
spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace")

# Create the table
spark.sql("""
    CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table (
        id INT,
        name STRING
    )
    USING iceberg
""")

# Insert data into the table
spark.sql("""
    INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table
    VALUES (1, 'one'), (2, 'two'), (3, 'three')
""")

將指令碼上傳至 Cloud Storage 值區

建立 quickstart.py 指令碼後，請將其上傳至 Cloud Storage 值區。

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」。

    前往「Buckets」(值區) 頁面

  2. 按一下 bucket 名稱。

  3. 在「物件」分頁，依序點選「上傳」 >「上傳檔案」。

  4. 在檔案瀏覽器中選取 quickstart.py 檔案，然後按一下「開啟」。

執行 PySpark 工作

上傳 quickstart.py 指令碼後，請以 Managed Service for Apache Spark 批次工作形式運作執行。

  1. 在 Cloud Shell 中，使用 quickstart.py 指令碼執行下列 Managed Service for Apache Spark 批次工作。

    gcloud dataproc batches submit pyspark gs://BUCKET_NAME/quickstart.py \
    --project=PROJECT_ID \
    --region=REGION \
    --version=2.2 \
    --properties="\
spark.sql.defaultCatalog=quickstart_catalog,\
spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\
spark.sql.catalog.quickstart_catalog.type=rest,\
spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/PROJECT_ID/catalogs/LAKEHOUSE_CATALOG_ID,\
spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=PROJECT_ID,\
spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\
spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"

    更改下列內容：

    • BUCKET_NAME：包含 PySpark 應用程式檔案的 Cloud Storage bucket 名稱。

    • LAKEHOUSE_CATALOG_ID：BigLake 目錄的名稱。稍後在 BigQuery 中使用 P.C.N.T 語法查詢目錄時，會用到這個名稱。例如：my-project.biglake-catalog.quickstart_namespace.quickstart_table。

    • PROJECT_ID：您的 Google Cloud 專案 ID。

    • REGION：執行 Managed Service for Apache Spark 批次工作負載的區域。

    工作完成後，畫面會顯示類似以下的輸出內容：

    Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished.
metadata:
'@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
batch: projects/your-project/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff
batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
createTime: '2026-01-24T00:10:50.224097Z'
description: Batch
labels:
    goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff
    goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
    goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
    goog-dataproc-location: us-central1
operationType: BATCH
name: projects/your-project/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef

從 BigQuery 查詢資料表

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在查詢編輯器中輸入下列陳述式，查詢會使用 project.catalog.namespace.table 語法。

    SELECT * FROM `PROJECT_ID.LAKEHOUSE_CATALOG_ID.quickstart_namespace.quickstart_table`;

    更改項目：

    • PROJECT_ID：您的 Google Cloud 專案 ID。

    • LAKEHOUSE_CATALOG_ID：要在 BigQuery 查詢中使用的目錄 ID。

  3. 按一下「執行」。

    查詢結果會顯示您透過 PySpark 工作插入的資料。

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。

  1. 更新 quickstart.py，刪除命名空間 (資料集) 和資料表：

    from pyspark.sql import SparkSession

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

# Delete the table first, then the namespace (dataset)
spark.sql("DROP TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table")
spark.sql("DROP NAMESPACE `quickstart_catalog`.quickstart_namespace")

    將檔案上傳至 Cloud Storage bucket：

    1. 前往 Google Cloud 控制台的「Cloud Storage bucket」。

      前往「Buckets」(值區) 頁面

    2. 按一下 bucket 名稱。

    3. 在「物件」分頁，依序點選「上傳」 >「上傳檔案」。

    4. 在檔案瀏覽器中選取 quickstart.py 檔案，然後按一下「開啟」。

    在 Cloud Shell 中，使用更新後的 quickstart.py 指令碼，執行另一個 Managed Service for Apache Spark 批次工作。

    gcloud dataproc batches submit pyspark gs://BUCKET_NAME/quickstart.py \
    --project=PROJECT_ID \
    --region=REGION \
    --version=2.2 \
    --properties="\
spark.sql.defaultCatalog=quickstart_catalog,\
spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\
spark.sql.catalog.quickstart_catalog.type=rest,\
spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/PROJECT_ID/catalogs/LAKEHOUSE_CATALOG_ID,\
spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=PROJECT_ID,\
spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\
spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"

    更改下列內容：

    • BUCKET_NAME：包含 PySpark 應用程式檔案的 Cloud Storage bucket 名稱。

    • LAKEHOUSE_CATALOG_ID：BigLake 目錄的名稱。

    • PROJECT_ID：您的 Google Cloud 專案 ID。

    • REGION：執行 Managed Service for Apache Spark 批次工作負載的區域。

  2. 前往「Lakehouse」Lakehouse。

    前往 Lakehouse

  3. 選取 LAKEHOUSE_CATALOG_ID 目錄，然後按一下「刪除」。

  4. 前往「Cloud Storage Buckets」(Cloud Storage bucket)。

    前往「Buckets」(值區) 頁面

  5. 選取 bucket，然後點選「Delete」(刪除)。

後續步驟