在 BigLake Metastore 中管理 Iceberg 資源

BigLake metastore 是單一共用中繼存放區，可讓資料處理引擎共用資料，不必為開放原始碼工作負載維護個別中繼存放區。

本文說明如何在 BigLake Metastore 中建立、查看、修改及刪除 Iceberg 資源。

事前準備

  1. Make sure that billing is enabled for your Google Cloud project.

    瞭解如何檢查專案是否已啟用計費功能。

  2. Enable the BigQuery, BigQuery Storage, and Dataproc APIs.

    Enable the APIs

  3. 選用：瞭解 BigLake Metastore 的運作方式，以及使用這項服務的原因。

必要的角色

如要取得管理 BigLake Metastore 中 Iceberg 資源所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

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

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

建立 metastore 資源

下列各節說明如何在 BigLake 中繼存放區建立資源。

建立命名空間

選取下列選項之一：

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 位置

Spark SQL 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

更改下列內容：

  • SPARK_CATALOG：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

建立 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：最新 Iceberg 中繼資料檔案的 Cloud Storage URI。例如：gs://mybucket/mytable/metadata/1234.metadata.json。
  • CONNECTION_ID：與 Cloud Storage 的連線 ID。

Spark SQL 

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

更改下列內容：

  • SPARK_CATALOG：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：最新 Iceberg 中繼資料檔案的 Cloud Storage URI。例如：gs://mybucket/mytable/metadata/1234.metadata.json。

查看 metastore 資源

下列各節說明如何查看 BigLake 中繼存放區中的資源。

查看命名空間

選取下列選項之一：

API

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

Spark SQL

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

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

將 SPARK_CATALOG 替換為您的 Spark 目錄名稱。

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

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

更改下列內容：

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

查看資料表

選取下列選項之一：

API

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

Spark SQL

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

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

更改下列內容：

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

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

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

更改下列內容：

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

修改 metastore 資源

下列各節說明如何修改 BigLake Metastore 中的資源。

更新命名空間

選取下列選項之一：

API

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

Spark SQL

使用 ALTER DATABASE 陳述式。

更新 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

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

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

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

Spark SQL

使用 ALTER TABLE 陳述式。

刪除中繼存放區資源

下列各節說明如何刪除 BigLake Metastore 中的資源。

刪除命名空間

選取下列選項之一：

API

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

Spark SQL 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

更改下列內容：

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

刪除資料表

選取下列選項之一：

API

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

Spark SQL

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

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

更改下列內容：

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

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

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

更改下列內容：

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

後續步驟