在 BigLake 中繼存放區建立及管理資源

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

本文說明如何在 BigLake 中繼資料存放區建立、查看、修改及刪除資源。

事前準備

Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Storage, and Dataproc APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

必要的角色

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

BigQuery 資料編輯者 (roles/bigquery.dataEditor)
Storage 物件使用者 (roles/storage.objectUser)

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

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

建立 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：要刪除的資料表名稱

後續步驟

瞭解其他 BigLake 中繼資料存放區功能。

在 BigLake 中繼存放區建立及管理資源 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

建立 metastore 資源

建立命名空間

API

Spark SQL

Terraform

建立 Iceberg 資料表

API

Spark SQL

Terraform

查看 metastore 資源

查看命名空間

API

Spark SQL

查看資料表

API

Spark SQL

修改 metastore 資源

更新命名空間

API

Spark SQL

更新 Iceberg 資料表

API

Spark SQL

刪除中繼存放區資源

刪除命名空間

API

Spark SQL

刪除資料表

API

Spark SQL

後續步驟

在 BigLake 中繼存放區建立及管理資源