使用 BigLake 中繼存放區 (傳統版) 管理開放原始碼中繼資料

BigLake 中繼資料庫 (傳統版) 是 Google Cloud上數據分析產品的統一實體中繼資料服務。BigLake 中繼存放區 (傳統版) 可提供中繼資料的單一來源，讓您管理及存取多個來源的資料。BigLake metastore (classic) 可透過 BigQuery 和 Dataproc 上的各種開放資料處理引擎存取，因此是資料分析師和工程師實用的工具。

如要管理商務中繼資料，請參閱「Dataplex 通用目錄」。

BigLake metastore (傳統版) 的運作方式

BigLake 元資料庫 (傳統版) 是一項無伺服器服務，您不必先佈建資源才能使用。您可以將其用於 Dataproc 叢集中的 Hive Metastore，做為無伺服器替代方案。BigLake 元資料庫 (傳統版) 的運作方式與 Hive 元資料庫相同，可透過與 Hive 相容的 API 運作，讓您立即在 BigQuery 中查詢開放格式資料表，不必再採取其他步驟。BigLake metastore (傳統版) 僅支援 Apache Iceberg 資料表。

BigLake 中繼存放區 (傳統版) 提供API、用戶端程式庫和資料引擎整合 (例如 Apache Spark)，用於管理目錄、資料庫和資料表。

限制

BigLake 元資料庫 (傳統版) 有下列限制：

• BigLake metastore (傳統版) 不支援 Apache Hive 資料表。
• 身分與存取權管理 (IAM) 角色和權限只能授予專案。不支援為資源授予 IAM 權限。
• 不支援 Cloud Monitoring。
• BigLake 中繼存放區 (傳統版) 目錄和資料庫有以下命名限制：
  • 名稱的長度上限為 1,024 個半形字元。
  • 名稱只能包含 UTF-8 英文字母 (大寫、小寫)、數字和底線。
  • 每個專案和區域組合的名稱不得重複。
• BigLake 元資料庫 (傳統版) 資料表的命名慣例與 BigQuery 資料表相同。詳情請參閱「資料表命名」一文。

事前準備

您必須先啟用計費功能和 BigLake API，才能使用 BigLake 元資料庫 (傳統版)。

1. 請要求管理員授予您專案的「服務使用情形管理員」(roles/serviceusage.serviceUsageAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理存取權」。
2. 為 Google Cloud 專案啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

3. 啟用 BigLake API。

   啟用 API

必要的角色

• 如要完全控管 BigLake 中繼資料庫 (傳統版) 資源，您需要 BigLake 管理員角色 (roles/biglake.admin)。如果您使用 BigQuery Spark 連接器服務帳戶、Dataproc Serverless 服務帳戶或 Dataproc VM 服務帳戶，請將 BigLake 管理員角色授予該帳戶。
• 如要取得 BigLake 中繼資料庫 (傳統版) 資源的唯讀存取權，您必須具備 BigLake 檢視者角色 (roles/biglake.viewer)。舉例來說，在 BigQuery 中查詢 BigLake 中繼資料庫 (傳統版) 資料表時，使用者或 BigQuery 連結服務帳戶必須具備 BigLake 檢視者角色。
• 如要建立含有連線的 BigQuery 資料表，您必須具備 BigQuery 連線使用者角色 (roles/bigquery.connectionUser)。如要進一步瞭解如何共用連線，請參閱「與使用者共用連線」。

視用途而定，呼叫 BigLake 元資料庫 (傳統版) 的身分可以是使用者或服務帳戶：

• 使用者：直接呼叫 BigLake API，或在未透過 BigQuery 連線的情況下，查詢 BigQuery 資料表中 Apache Iceberg 的 BigLake 資料表。在這種情況下，BigQuery 會使用使用者的憑證。
• BigQuery Cloud 資源連線：透過 BigQuery 連線查詢 BigQuery 中的 BigLake Iceberg 資料表。BigQuery 會使用連線服務帳戶憑證存取 BigLake 元資料庫 (傳統版)。
• BigQuery Spark 連接器：在 BigQuery Spark 儲存程序中，搭配使用 Spark 與 BigLake 中繼存放區 (傳統版)。Spark 會使用 Spark 連接器的服務帳戶憑證，存取 BigLake 中繼存放區 (傳統版) 並建立 BigQuery 資料表。
• Dataproc Serverless 服務帳戶：在 Dataproc Serverless 中使用 Spark 搭配 BigLake 時。Spark 會使用服務帳戶憑證。
• Dataproc VM 服務帳戶：使用 Dataproc (而非 Dataproc Serverless) 時。Apache Spark 會使用 VM 服務帳戶憑證。

視您的權限而定，您可以將這些角色授予自己，或請管理員將這些角色授予您。如要進一步瞭解如何授予角色，請參閱「查看可針對資源授予的角色」。

如要查看存取 BigLake 元資料庫 (傳統版) 資源所需的確切權限，請展開「必要權限」部分：

連線至 BigLake 元資料庫 (傳統版)

以下各節說明如何連線至 BigLake 元資料庫 (傳統版)。這些部分會安裝並使用 BigLake Apache Iceberg 目錄外掛程式，如以下方法中的 JAR 檔案所示。目錄外掛程式可從 Apache Spark 等開放原始碼引擎連線至 BigLake 中繼資料庫 (傳統版)。

連線至 Dataproc VM

如要透過 Dataproc VM 連線至 BigLake Metastore (傳統版)，請執行下列步驟：

1. 使用 SSH 連線至 Dataproc。

2. 在 Spark SQL CLI 中，使用下列陳述式安裝及設定 Apache Iceberg 自訂目錄，以便與 BigLake 元資料庫 (傳統版) 搭配運作：

   spark-sql \
     --packages ICEBERG_SPARK_PACKAGE \
     --jars BIGLAKE_ICEBERG_CATALOG_JAR \
     --conf spark.sql.catalog.SPARK_CATALOG=org.apache.iceberg.spark.SparkCatalog \
     --conf spark.sql.catalog.SPARK_CATALOG.catalog-impl=org.apache.iceberg.gcp.biglake.BigLakeCatalog \
     --conf spark.sql.catalog.SPARK_CATALOG.gcp_project=PROJECT_ID \
     --conf spark.sql.catalog.SPARK_CATALOG.gcp_location=LOCATION \
     --conf spark.sql.catalog.SPARK_CATALOG.blms_catalog=BLMS_CATALOG \
     --conf spark.sql.catalog.SPARK_CATALOG.warehouse=GCS_DATA_WAREHOUSE_FOLDER \
     --conf spark.sql.catalog.SPARK_HMS_CATALOG=org.apache.iceberg.spark.SparkCatalog \
     --conf spark.sql.catalog.SPARK_HMS_CATALOG.type=hive \
     --conf spark.sql.catalog.SPARK_HMS_CATALOG.uri=thrift://HMS_URI:9083
     

更改下列內容：

• ICEBERG_SPARK_PACKAGE：要使用的 Apache Iceberg 與 Spark 版本。建議您使用與 Dataproc 或 Dataproc Serverless 執行個體中的 Spark 版本相符的 Spark 版本。如要查看可用 Apache Iceberg 版本的清單，請參閱 Apache Iceberg 下載項目。舉例來說，Apache Spark 3.3 的標記為：
  --packages org.apache.iceberg:iceberg-spark-runtime-3.3_2.13:1.2.1
• BIGLAKE_ICEBERG_CATALOG_JAR：要安裝的 Iceberg 自訂目錄外掛程式的 Cloud Storage URI。視環境而定，請選取下列其中一個選項：
  • Iceberg 1.5.1: gs://spark-lib/biglake/biglake-catalog-iceberg1.5.1-0.1.2-with-dependencies.jar
  • Iceberg 1.5.0：gs://spark-lib/biglake/biglake-catalog-iceberg1.5.0-0.1.1-with-dependencies.jar
  • Iceberg 1.2.0：gs://spark-lib/biglake/biglake-catalog-iceberg1.2.0-0.1.1-with-dependencies.jar
  • Iceberg 0.14.0：gs://spark-lib/biglake/biglake-catalog-iceberg0.14.0-0.1.1-with-dependencies.jar
• SPARK_CATALOG：Spark 的產品目錄 ID。並連結至 BigLake 元資料庫 (傳統版) 目錄。
• PROJECT_ID：Spark 目錄連結的 BigLake 中繼資料庫 (傳統版) 目錄的 Google Cloud 專案 ID。
• LOCATION：Spark 目錄連結的 BigLake 元資料庫 (傳統版) 目錄的 Google Cloud 位置。
• BLMS_CATALOG：Spark 目錄連結的 BigLake 中繼資料庫 (傳統版) 目錄 ID。目錄不必存在，也可以在 Spark 中建立。
• GCS_DATA_WAREHOUSE_FOLDER：Spark 建立所有檔案的 Cloud Storage 資料夾。開頭為 gs://。
• HMS_DB：(選用) 包含要複製資料表的 HMS 資料庫。
• HMS_TABLE：(選用) 要複製的 HMS 資料表。
• HMS_URI：(選用) HMS Thrift 端點。

連結至 Dataproc 叢集

您也可以將 Dataproc 工作提交至叢集。以下範例會安裝適當的 Iceberg 自訂目錄。

如要連線至 Dataproc 叢集，請按照下列規格提交工作：

CONFS="spark.sql.catalog.SPARK_CATALOG=org.apache.iceberg.spark.SparkCatalog,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.catalog-impl=org.apache.iceberg.gcp.biglake.BigLakeCatalog,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.gcp_project=PROJECT_ID,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.gcp_location=LOCATION,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.blms_catalog=BLMS_CATALOG,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.warehouse=GCS_DATA_WAREHOUSE_FOLDER,"
CONFS+="spark.jars.packages=ICEBERG_SPARK_PACKAGE"

gcloud dataproc jobs submit spark-sql --cluster=DATAPROC_CLUSTER \
  --project=DATAPROC_PROJECT_ID \
  --region=DATAPROC_LOCATION \
  --jars=BIGLAKE_ICEBERG_CATALOG_JAR \
  --properties="${CONFS}" \
  --file=QUERY_FILE_PATH

更改下列內容：

• DATAPROC_CLUSTER：要提交工作的 Dataproc 叢集。
• DATAPROC_PROJECT_ID：Dataproc 叢集的專案 ID。這個 ID 可能與 PROJECT_ID 不同。
• DATAPROC_LOCATION：Dataproc 叢集的位置。這個位置可能與 LOCATION 不同。
• QUERY_FILE_PATH：包含要執行的查詢的檔案路徑。

連結至 Dataproc Serverless

同樣地，您也可以將批次工作負載提交至 Dataproc Serverless。如要執行這項操作，請按照批次工作負載操作說明操作，並加上下列額外標記：

• --properties="${CONFS}"
• --jars=BIGLAKE_ICEBERG_CATALOG_JAR

連結至 BigQuery 預存程序

您可以使用 BigQuery 儲存程序執行 Dataproc Serverless 工作。這個程序類似於直接在 Dataproc 中執行 Dataproc Serverless 工作。

建立 Metastore 資源

下列各節將說明如何在元資料庫中建立資源。

建立目錄

目錄名稱有限制，詳情請參閱「限制」一節。如要建立目錄，請選取下列任一選項：

CREATE NAMESPACE SPARK_CATALOG;

resource "google_biglake_catalog" "default" {
name     = "my_catalog"
location = "US"
}

建立資料庫

資料庫名稱有限制，詳情請參閱「限制」一節。為確保資料庫資源與資料引擎相容，建議您使用資料引擎建立資料庫，而非手動編寫資源主體。如要建立資料庫，請選取下列任一選項：

CREATE NAMESPACE SPARK_CATALOG.BLMS_DB;

resource "google_biglake_database" "default" {
name    = "my_database"
catalog = google_biglake_catalog.default.id
type    = "HIVE"
hive_options {
  location_uri = "gs://${google_storage_bucket.default.name}/${google_storage_bucket_object.metadata_directory.name}"
  parameters = {
    "owner" = "Alex"
  }
}
}

製作表格

資料表名稱有限制。詳情請參閱「資料表命名」一文。如要建立資料表，請選取下列任一選項：

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

resource "google_biglake_table" "default" {
name     = "my-table"
database = google_biglake_database.default.id
type     = "HIVE"
hive_options {
  table_type = "MANAGED_TABLE"
  storage_descriptor {
    location_uri  = "gs://${google_storage_bucket.default.name}/${google_storage_bucket_object.data_directory.name}"
    input_format  = "org.apache.hadoop.mapred.SequenceFileInputFormat"
    output_format = "org.apache.hadoop.hive.ql.io.HiveSequenceFileOutputFormat"
  }
  parameters = {
    "spark.sql.create.version"          = "3.1.3"
    "spark.sql.sources.schema.numParts" = "1"
    "transient_lastDdlTime"             = "1680894197"
    "spark.sql.partitionProvider"       = "catalog"
    "owner"                             = "Alex"
    "spark.sql.sources.schema.part.0" = jsonencode({
      "type" : "struct",
      "fields" : [
        { "name" : "id", "type" : "integer",
          "nullable" : true,
          "metadata" : {}
        },
        {
          "name" : "name",
          "type" : "string",
          "nullable" : true,
          "metadata" : {}
        },
        {
          "name" : "age",
          "type" : "integer",
          "nullable" : true,
          "metadata" : {}
        }
      ]
    })
    "spark.sql.sources.provider" = "iceberg"
    "provider"                   = "iceberg"
  }
}
}

E2E Terraform 範例

這個 GitHub 範例提供可執行的端對端範例，可用來建立 BigLake 元資料庫 (傳統版) 目錄、資料庫和資料表。如要進一步瞭解如何使用這個範例，請參閱「Terraform 基本指令」。

將 Iceberg 資料表從 Hive 中繼儲存庫複製到 BigLake 中繼儲存庫 (傳統版)

如要建立 Iceberg 資料表，並將 Hive 中繼存放區資料表複製到 BigLake 中繼存放區 (傳統版)，請使用下列 Spark SQL 陳述式：

CREATE TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE
  (id bigint, data string) USING iceberg
  TBLPROPERTIES(hms_table='HMS_DB.HMS_TABLE');

將 BigLake 資料表連結至 BigLake 元資料庫 (傳統版) 資料表

在 Spark 中建立 Iceberg 資料表時，您可以選擇同時建立連結的 Iceberg 唯讀資料表。

自動連結資料表

如要在 Spark 中建立 Iceberg 資料表，並同時自動建立 Iceberg 唯讀資料表，請使用下列 Spark SQL 陳述式：

  CREATE TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE
    (id bigint, data string) USING iceberg
    TBLPROPERTIES(bq_table='BQ_TABLE_PATH',
    bq_connection='BQ_RESOURCE_CONNECTION');

更改下列內容：

• BQ_TABLE_PATH：要建立的 Iceberg 唯讀資料表路徑。請遵循 BigQuery 資料表路徑語法。如果未指定專案，則會使用與 BigLake 元資料庫 (傳統版) 目錄相同的專案。

• BQ_RESOURCE_CONNECTION (選用)：格式為 project.location.connection-id。如果指定，BigQuery 查詢會使用 Cloud Resource connection 憑證存取 BigLake 中繼存放區 (傳統版)。如果未指定，BigQuery 會建立一般外部資料表，而非 BigLake 資料表。

手動連結資料表

如要手動建立 Iceberg 唯讀資料表連結，並指定 BigLake 元資料庫 (傳統版) 資料表 URI (blms://…)，請使用下列 BigQuery SQL 陳述式：

CREATE EXTERNAL TABLE 'BQ_TABLE_PATH'
  WITH CONNECTION `BQ_RESOURCE_CONNECTION`
  OPTIONS (
          format = 'ICEBERG',
          uris = ['blms://projects/PROJECT_ID/locations/LOCATION/catalogs/BLMS_CATALOG/databases/BLMS_DB/tables/BLMS_TABLE']
          )

查看元資料庫資源

下列各節將說明如何查看 BigLake 元資料庫 (傳統版) 中的資源。

查看目錄

如要查看目錄中的所有資料庫，請使用 projects.locations.catalogs.list 方法，並指定目錄名稱。

如要查看目錄相關資訊，請使用 projects.locations.catalogs.get 方法，並指定目錄名稱。

查看資料庫

如要查看資料庫，請按照下列步驟操作：

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

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

查看資料表

如要查看資料庫中的所有資料表或已定義的資料表，請按照下列步驟操作：

SHOW TABLES IN SPARK_CATALOG.BLMS_DB;

DESCRIBE TABLE [EXTENDED] SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

修改元資料庫資源

下列各節將說明如何修改元資料庫中的資源。

更新資料表

為避免多個工作同時嘗試更新相同資料表時發生衝突，BigLake 元資料儲存庫 (傳統版) 會使用樂觀式鎖定機制。如要使用樂觀式鎖定，您必須先使用 GetTable 方法取得資料表的目前版本 (稱為 etag)。接著，您可以變更資料表並使用 UpdateTable 方法，傳入先前擷取的 etag。如果在擷取 etag 後，其他工作更新了資料表，UpdateTable 方法就會失敗。這項措施可確保一次只有一項工作可以更新資料表，避免發生衝突。

如要更新資料表，請選取下列任一選項：

重新命名表格

如要重新命名資料表，請選取下列其中一個選項：

ALTER TABLE BLMS_TABLE RENAME TO NEW_BLMS_TABLE;

更改下列內容：

• NEW_BLMS_TABLE：BLMS_TABLE 的新名稱。必須與 BLMS_TABLE 位於相同的資料集中。

刪除中繼存放區資源

下列各節將說明如何刪除 BigLake 元資料庫 (傳統版) 中的資源。

刪除目錄

如要刪除目錄，請選取下列任一選項：

DROP NAMESPACE SPARK_CATALOG;

刪除資料庫

如要刪除資料庫，請選取下列任一選項：

DROP NAMESPACE SPARK_CATALOG.BLMS_DB;

刪除資料表

如要刪除表格，請選取下列其中一個選項：

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE PURGE;