在 Lakehouse 執行階段目錄中建立及管理資源

Lakehouse for Apache Iceberg 支援透過 Lakehouse 執行階段目錄管理資源。

這個共用目錄可免除為不同資料處理引擎的開放原始碼工作負載維護多個目錄的需求。支援的操作包括建立、查看、修改及刪除命名空間和資料表等資源。

事前準備

  1. 確認專案已啟用計費功能 Google Cloud 。

  2. 啟用 BigQuery、BigQuery Storage 和 Managed Service for Apache Spark API。

    啟用 API 時所需的角色

    如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

    啟用 API

必要的角色

如要取得管理 Lakehouse 執行階段目錄中 Apache Iceberg 資源所需的權限，請要求管理員授予您專案的下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

建立目錄資源

下列各節說明如何在 Lakehouse 執行階段目錄中建立資源。

建立命名空間

選取下列選項之一：

API

使用 datasets.insert 方法，並在您傳入的 資料集資源中指定 ExternalCatalogDatasetOptions 欄位。

{
  "datasetReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID"
  },
  "externalCatalogDatasetOptions": {
    "defaultStorageLocationUri": "URI",
    "parameters": {
      ...
    }
  },
  "location": "LOCATION"
}

更改下列內容：

  • PROJECT_ID：包含目標資料集的專案 ID。
  • DATASET_ID：目標資料集的 ID。
  • URI：資料集中所有資料表的 Cloud Storage URI。
  • LOCATION：您要在其中建立資料集的BigQuery 位置。

Apache Spark SQL 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：新命名空間的名稱。

Terraform

provider "google" {
  project = "PROJECT_ID"
}

resource "google_bigquery_dataset" "default" {
  dataset_id = "DATASET_ID"
  location   = "LOCATION"

  external_catalog_dataset_options {
    default_storage_location_uri = "URI"
    parameters = {
      ...
    }
  }
}

更改下列內容：

  • PROJECT_ID：包含目標資料集的專案 ID。
  • DATASET_ID：目標資料集的 ID。
  • LOCATION：您要在其中建立資料集的BigQuery 位置。
  • URI：資料集中所有資料表的 Cloud Storage URI。

建立 Apache Iceberg 資料表

選取下列選項之一：

API

使用 tables.insert 方法，並在您傳入的資料表資源中指定 ExternalCatalogTableOptions 欄位。

{
  "tableReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "externalCatalogTableOptions": {
    "parameters": {
      "table_type": "iceberg",
      "metadata_location": "METADATA_URI"
    },
    "connection_id": "CONNECTION_ID"
  }
}

更改下列內容：

  • PROJECT_ID：包含目標表格的專案 ID。
  • DATASET_ID：包含目標表格的資料集 ID。
  • TABLE_ID：目標資料表的 ID。
  • METADATA_URI：最新 Apache Iceberg 中繼資料檔案的 Cloud Storage URI。例如：gs://mybucket/mytable/metadata/1234.metadata.json。
  • CONNECTION_ID：與 Cloud Storage 的連線 ID。

Apache Spark SQL 

CREATE TABLE SPARK_CATALOG.NAMESPACE.TABLE
  (id bigint, data string) USING iceberg;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。
  • TABLE：新資料表的名稱。

Terraform

resource "google_bigquery_table" "default" {
  deletion_protection = false
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "TABLE"

  external_catalog_table_options {
    storage_descriptor {
      location_uri  = "STORAGE_URI"
      input_format  = "org.apache.hadoop.mapred.FileInputFormat"
      output_format = "org.apache.hadoop.mapred.FileOutputFormat"
    }
    parameters = {
      "table_type"        = "iceberg"
      "metadata_location" = "METADATA_URI"
      "write.parquet.compression-codec" : "zstd"
      "EXTERNAL" : "TRUE"
    }
  }
}

更改下列內容：

  • TABLE：目標資料表的名稱。
  • STORAGE_URI：儲存資料表資料的 Cloud Storage URI，開頭為 gs://。
  • METADATA_URI：最新 Apache Iceberg 中繼資料檔案的 Cloud Storage URI。例如：gs://mybucket/mytable/metadata/1234.metadata.json。

查看目錄資源

下列各節說明如何在 Lakehouse 執行階段目錄中查看資源。

查看命名空間

選取下列選項之一：

API

使用 datasets.list 方法查看所有命名空間，或使用 datasets.get 方法查看已定義命名空間的相關資訊。

Apache Spark SQL

如要查看目錄中的所有命名空間，請使用下列陳述式：

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

將 SPARK_CATALOG 替換為 Apache Spark 目錄名稱。

如要查看已定義命名空間的相關資訊，請使用下列陳述式：

DESCRIBE { DATABASE | NAMESPACE } [EXTENDED]
SPARK_CATALOG.NAMESPACE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。

查看資料表

選取下列選項之一：

API

如要查看命名空間中的所有資料表，請使用 tables.list 方法；如要查看已定義資料表的相關資訊，請使用 tables.get 方法。

Apache Spark SQL

如要查看命名空間中的所有資料表，請使用下列陳述式：

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。

如要查看已定義資料表的相關資訊，請使用下列陳述式：

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。
  • TABLE：資料表名稱。

修改目錄資源

下列各節說明如何修改 Lakehouse 執行階段目錄中的資源。

更新命名空間

選取下列選項之一：

API

使用 datasets.patch 方法，並更新資料集資源中的 ExternalCatalogDatasetOptions 欄位。不建議使用 datasets.update 方法，因為該方法會取代整個資料集資源。

Apache Spark SQL

使用 ALTER DATABASE 陳述式。

更新 Apache Iceberg 資料表

選取下列選項之一：

API

使用 tables.patch 方法，並更新資料表資源中的 ExternalCatalogTableOptions 欄位。不建議使用 tables.update 方法，因為該方法會取代整個資料表資源。

如要更新結構定義或中繼資料檔案，請使用 tables.patch 方法，並將 autodetect_schema 屬性設為 true：

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID?autodetect_schema=true

更改下列內容：

  • PROJECT_ID：包含要更新資料表的專案 ID。
  • DATASET_ID：包含要更新資料表的資料集 ID。
  • TABLE_ID：要更新的資料表 ID。

在要求主體中，為每個欄位指定更新的值。舉例來說，如要更新 Apache Iceberg 資料表的 中繼資料位置，請為 metadata_location 欄位指定更新的值：

{
  "externalCatalogTableOptions": {
    "parameters": {"metadata_location": "METADATA_URI"}
  },
  "schema": null
}'

請將 METADATA_URI 替換為最新 Apache Iceberg 中繼資料檔案的 Cloud Storage URI。例如：gs://mybucket/mytable/metadata/1234.metadata.json。

Apache Spark SQL

使用 ALTER TABLE 陳述式。

刪除目錄資源

下列各節說明如何刪除 Lakehouse 執行階段目錄中的資源。

刪除命名空間

選取下列選項之一：

API

請使用 datasets.delete 方法。將 deleteContents 參數設為 true，即可刪除命名空間中的資料表。

Apache Spark SQL 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。

刪除資料表

選取下列選項之一：

API

使用 tables.delete 方法，並指定資料表名稱。這個方法不會刪除 Cloud Storage 中的相關聯檔案。

Apache Spark SQL

如要只捨棄資料表，請使用下列陳述式：

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。
  • TABLE：要捨棄的資料表名稱。

如要捨棄資料表並刪除 Cloud Storage 中的相關聯檔案，請使用下列陳述式：

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

更改下列內容：

  • SPARK_CATALOG：Apache Spark 目錄的名稱。
  • NAMESPACE：命名空間名稱。
  • TABLE：要刪除的資料表名稱。

後續步驟