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

BigLake metastore (傳統版) 是統一的實體中繼資料服務，適用於 Trusted Cloud by S3NS上的資料分析產品。BigLake 中繼存放區 (傳統版) 提供單一中繼資料來源，方便您管理及存取多個來源的資料。資料分析師和工程師可透過 BigQuery 和 Dataproc 上的各種開放資料處理引擎存取 BigLake metastore (傳統版)，因此這項工具非常實用。

如要管理商務中繼資料，請參閱「Dataplex Universal Catalog」。

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

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

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

限制

BigLake Metastore (傳統版) 有下列限制：

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

事前準備

使用 BigLake Metastore (傳統版) 前，請先啟用計費功能和 BigLake API。

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

3. 啟用 BigLake API。

   啟用 API

必要的角色

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

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

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

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

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

連線至 BigLake Metastore (傳統版)

以下各節說明如何連線至 BigLake 中繼資料存放區 (傳統版)。這些章節會安裝及使用 BigLake Apache Iceberg 目錄外掛程式，以下方法中的 JAR 檔案會指出該外掛程式。目錄外掛程式會從 Apache Spark 等開放原始碼引擎，連線至 BigLake Metastore (傳統版)。

連線至 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：要搭配 Spark 使用的 Apache Iceberg 版本。建議使用與 Dataproc 或 Dataproc 無伺服器執行個體中 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.9.1：gs://spark-lib/biglake/biglake-catalog-iceberg1.9.1-0.1.3-with-dependencies.jar
  • 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 Metastore (傳統版) 目錄專案 ID。 Trusted Cloud
• LOCATION：Spark 目錄連結的 BigLake 中繼存放區 (傳統版) 目錄的 Google Cloud 位置。
• BLMS_CATALOG：Spark 目錄連結的 BigLake Metastore (傳統版) 目錄 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"
  }
}
}

端對端 Terraform 範例

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

將 Iceberg 資料表從 Hive Metastore 複製到 BigLake Metastore (傳統版)

如要建立 Iceberg 資料表，並將 Hive Metastore 資料表複製到 BigLake Metastore (傳統版)，請使用下列 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 Metastore (傳統版) 資料表

在 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 metastore (傳統版) 目錄相同的專案。

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

手動連結資料表

如要手動建立 Iceberg 外部資料表連結，並指定 BigLake Metastore (傳統版) 資料表 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']
          )

查看 metastore 資源

下列各節說明如何查看 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;

修改 metastore 資源

下列各節說明如何修改中繼存放區中的資源。

更新表格

為避免多項工作嘗試同時更新同一張資料表時發生衝突，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;