使用 Google Cloud CLI 在 Lakehouse 建立及查詢 Iceberg 資料表

設定環境並建立 bucket

開啟 Cloud Shell 並建立 Cloud Storage bucket，用於存放 PySpark 指令碼和 Iceberg 資料表資料：

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

   啟用 Cloud Shell

2. 如果出現提示訊息，請按一下「授權」。

3. 為專案、區域、bucket 和目錄名稱設定環境變數，以便在本快速入門導覽課程中重複使用：

   export PROJECT_ID=$(gcloud config get-value project)
   export REGION="us-central1"
   export BUCKET_NAME="${PROJECT_ID}-lakehouse-quickstart"
   export LAKEHOUSE_CATALOG_ID="quickstart_catalog"

4. 在所選區域建立 Cloud Storage bucket：

   gcloud storage buckets create gs://${BUCKET_NAME} \
       --project=${PROJECT_ID} \
       --location=${REGION}

將權限授予 Spark 服務帳戶

根據預設，Managed Service for Apache Spark 會使用專案的 Compute Engine 預設服務帳戶執行批次工作。向這個服務帳戶授予下列 IAM 角色，以便從 Cloud Storage 讀取 PySpark 指令碼，並與 Lakehouse 執行階段目錄和 BigQuery 互動：

請注意，Spark 服務帳戶只需要 Storage 物件檢視者角色 (roles/storage.objectViewer)，即可讀取 PySpark 指令碼。工作執行時，Lakehouse 執行階段目錄會提供資料表範圍的臨時寫入憑證，因此不需要值區的直接寫入權限。

在 Cloud Shell 執行下列指令碼，授予這些角色：

PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} \
    --format='value(projectNumber)')
SPARK_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

for ROLE in \
    "roles/dataproc.worker" \
    "roles/serviceusage.serviceUsageConsumer" \
    "roles/biglake.editor" \
    "roles/bigquery.dataEditor"; do
  gcloud projects add-iam-policy-binding ${PROJECT_ID} \
      --member="serviceAccount:${SPARK_SA}" \
      --role="${ROLE}"
done

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
    --member="serviceAccount:${SPARK_SA}" \
    --role="roles/storage.objectViewer"

在 Lakehouse 執行階段目錄中建立目錄

在 Lakehouse 執行階段目錄中，為 Apache Iceberg 資料表建立目錄。

1. 在 Cloud Shell 中建立多值區目錄。多 bucket 目錄可讓您獨立命名目錄，不受任何 bucket 名稱影響，並將多個 Cloud Storage bucket 與單一目錄建立關聯。啟用憑證臨時配發模式，讓 Lakehouse 執行階段目錄能代表您，安全地向 Spark 核發臨時儲存空間憑證。

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

2. 授予目錄值區存取權：

   使用憑證販售功能時，目錄的自動佈建服務帳戶需要 bucket 的 Storage 物件使用者角色 (roles/storage.objectUser)，才能為用戶端引擎產生臨時存取權杖。

   # Retrieve the auto-provisioned catalog service account email
   CATALOG_SA=$(gcloud biglake iceberg catalogs describe ${LAKEHOUSE_CATALOG_ID} \
       --project=${PROJECT_ID} \
       --format='value(biglake-service-account)')
   
   # Grant the Storage Object User role to the catalog service account on your bucket
   gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
       --member="serviceAccount:${CATALOG_SA}" \
       --role="roles/storage.objectUser"

使用 PySpark 工作建立 Iceberg 資料表

目錄和權限準備就緒後，您可以在 Managed Service for Apache Spark 執行 PySpark 工作，建立 Iceberg 資料表並插入一些樣本資料。

建立及上傳 PySpark 指令碼

1. 在 Cloud Shell 建立名為 quickstart.py 的檔案：

   cat << 'EOF' > quickstart.py
   from pyspark.sql import SparkSession
   
   spark = SparkSession.builder.appName("quickstart").getOrCreate()
   
   # Create a namespace
   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')
   """)
   EOF

   這個指令碼會啟動 Spark 工作階段、建立名為 quickstart_namespace 的命名空間和名為 quickstart_table 的 Iceberg 資料表，並插入三列樣本資料。由於 SQL 陳述式未指定 bucket 路徑 (LOCATION)，Lakehouse 執行階段目錄會自動將命名空間和資料表檔案儲存在目錄的 --default-location bucket (gs://${BUCKET_NAME}) 中。

2. 將 quickstart.py 複製到 Cloud Storage bucket，讓 Managed Service for Apache Spark 存取：

   gcloud storage cp quickstart.py gs://${BUCKET_NAME}/quickstart.py

執行 PySpark 指令碼

將 PySpark 指令碼提交為 Managed Service for Apache Spark 批次工作，使用預先安裝的 Iceberg 程式庫執行程式碼，不需佈建叢集。

--properties 旗標會設定 Spark，使用 Apache Iceberg REST 目錄端點，連線至 Lakehouse 執行階段目錄中的目錄：

1. 在 Cloud Shell 提交批次工作：

   gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \
       --project=${PROJECT_ID} \
       --region=${REGION} \
       --version=2.2 \
       --properties="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"

   除了標準 Iceberg 設定 (SparkCatalog、type=rest 和 IcebergSparkSessionExtensions) 之外，這些屬性也會設定 Lakehouse 執行階段目錄連線：

   • uri 和 warehouse (bl://...)：將 Spark 連線至 Lakehouse 執行階段目錄 Apache Iceberg REST 目錄端點，並將要求轉送至多個 bucket 目錄。
   • rest.auth.type 和 header.x-goog-user-project：使用 Spark 服務帳戶的憑證驗證 REST 要求，並向專案收取 API 配額費用。
   • header.X-Iceberg-Access-Delegation、io-impl 和 gcs.oauth2.refresh-credentials-endpoint：向目錄要求臨時提供的 Cloud Storage 憑證，並設定 Iceberg 的 GCSFileIO 用戶端，使用這些權杖寫入資料檔案。

   如要進一步瞭解這些設定，請參閱「設定用戶端應用程式」和 Apache Iceberg Spark 設定說明文件。

   工作完成後，輸出內容大致如下：

   Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished.
   metadata:
     '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
     batch: projects/PROJECT_ID/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/PROJECT_ID/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef
   

透過 BigQuery 查詢資料表

Spark 寫入 Iceberg 資料表後，您就能立即在 BigQuery 中使用 4 部分的 P.C.N.T (Project.Catalog.Namespace.Table) 語法查詢資料表：

1. 在 Cloud Shell 執行下列 bq query 指令：

   bq query --project_id=${PROJECT_ID} --location=${REGION} --use_legacy_sql=false \
       "SELECT * FROM \`${PROJECT_ID}.${LAKEHOUSE_CATALOG_ID}.quickstart_namespace.quickstart_table\`"

   輸出內容會顯示您透過 PySpark 工作插入的三個資料列：

   +----+-------+
   | id | name  |
   +----+-------+
   |  1 | one   |
   |  2 | two   |
   |  3 | three |
   +----+-------+
   

由於 Lakehouse 執行階段目錄會追蹤 Iceberg 中繼資料並處理儲存空間存取權，因此 Spark 提交快照後，BigQuery 就會立即讀取 Cloud Storage 中的基礎檔案。

此時，您也可以使用任何其他與 Iceberg 相容的引擎 (例如 Trino、Flink 或自行管理的 Spark 叢集)，讀取或寫入 quickstart_table。由於目錄已啟用憑證販售功能，外部引擎只需要專案的 BigLake 檢視者角色 (roles/biglake.viewer) 即可讀取資料表，或需要 BigLake 編輯者角色 (roles/biglake.editor) 才能寫入資料及提交新快照。如要瞭解如何連結其他引擎，請參閱「設定 Apache Iceberg REST 目錄端點」。