BigLake Metastore でオープンソース メタデータを管理する

BigLake Metastore は、Google Cloud 上のデータ分析プロダクト用の統一された物理メタデータ サービスです。BigLake Metastore では、メタデータの信頼できる唯一の情報源が提供され、複数のソースからのデータの管理とアクセスが可能になります。BigQuery や Dataproc のさまざまなオープン データ処理エンジンからアクセスできる BigLake Metastore は、データ アナリストやエンジニアにとって有用なツールです。

ビジネス メタデータの管理については、Dataplex をご覧ください。

BigLake Metastore の仕組み

BigLake Metastore は、使用する前にリソースのプロビジョニングを必要としないサーバーレス サービスです。Dataproc クラスタの Hive メタストアの代わりにサーバーレスとして使用できます。BigLake Metastore は、Hive 互換の API を介して Hive Metastore と同じように機能し、それ以上の手順なしで BigQuery でオープン形式のテーブルに対してすぐにクエリできます。BigLake Metastore は、Apache Iceberg テーブルのみをサポートします。

BigLake Metastore は、カタログ、データベース、テーブルを管理するための API、クライアント ライブラリ、データエンジン統合（Apache Spark など）を提供します。

制限事項

BigLake Metastore には次の制限があります。

• BigLake Metastore は Apache Hive テーブルをサポートしていません。
• Identity and Access Management（IAM）のロールと権限は、プロジェクトにのみ付与できます。リソースへの IAM 権限の付与はサポートされていません。
• Cloud Monitoring はサポートされていません。
• BigLake Metastore のカタログとデータベースには、次の命名制限があります。
  • 名前の長さは 1,024 文字までです。
  • 名前に使用できるのは、UTF-8 の文字（大文字、小文字）、数字、アンダースコアのみです。
  • 名前は、プロジェクトとリージョンの組み合わせごとに一意である必要があります。
• BigLake Metastore テーブルは、BigQuery テーブルと同じ命名規則に従います。詳細については、テーブルの命名をご覧ください。

準備

BigLake Metastore を使用する前に、課金と BigLake API を有効にする必要があります。

1. 管理者に、プロジェクトに対する Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）IAM ロールを付与するよう依頼します。ロールの付与の詳細については、アクセスの管理をご覧ください。
2. Google Cloud プロジェクトに対する課金を有効にします。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

3. BigLake API を有効にします。

   API の有効化

必要なロール

• BigLake Metastore リソースを完全に管理するには、BigLake 管理者ロール（roles/biglake.admin）が必要です。BigQuery Spark コネクタ サービス アカウント、Dataproc サーバーレスのサービス アカウント、または Dataproc VM のサービス アカウントを使用している場合、BigLake 管理者のロールをアカウントに付与します。
• BigLake Metastore リソースに対する読み取り専用アクセス権を得るには、BigLake 閲覧者のロール（roles/biglake.viewer）が必要です。たとえば、BigQuery で BigLake Metastore テーブルをクエリする場合は、ユーザーまたは BigQuery Connection のサービス アカウントに BigLake 閲覧者のロールが必要です。
• 接続がある BigQuery テーブルを作成するには、BigQuery Connection ユーザーのロール（roles/bigquery.connectionUser）が必要です。接続の共有の詳細については、ユーザーと接続を共有するをご覧ください。

ユースケースに応じて、BigLake Metastore を呼び出す ID をユーザーまたはサービス アカウントのいずれかにできます。

• ユーザー: BigLake Rest API を直接呼び出す場合、または BigQuery からの接続がない BigQuery Iceberg テーブルに対してクエリを実行する場合。この状況で、BigQuery はユーザーの認証情報を使用します。
• BigQuery Cloud リソース接続: BigQuery から接続されている BigQuery Iceberg テーブルに対してクエリを実行する場合。BigQuery は、接続サービス アカウントの認証情報を使用して BigLake Metastore にアクセスします。
• BigQuery Spark コネクタ: BigQuery の Spark ストアド プロシージャで BigLake Metastore と一緒に Spark を使用する場合。Spark では、Spark コネクタのサービス アカウント認証情報を使用して、BigLake Metastore にアクセスし、BigQuery テーブルを作成します。
• Dataproc サーバーレスのサービス アカウント: Dataproc サーバーレスで BigLake と一緒に Spark を使用する場合。Spark ではサービス アカウントの認証情報を使用します。
• Dataproc VM のサービス アカウント: （Dataproc サーバーレスではなく）Dataproc を使用する場合。 Apache Spark では、VM のサービス アカウントの認証情報を使用します。

権限に応じて、これらのロールを自身に付与するか、これらのロールを付与するよう管理者に依頼できます。ロールの付与の詳細については、リソースに対して付与可能なロールの表示をご覧ください。

BigLake Metastore リソースにアクセスするために必要な権限を確認するには、必要な権限セクションを開きます。

必要な権限

• すべての読み取り専用アクセスのプロジェクト レベルでの biglake.tables.get。BigQuery Iceberg テーブルのクエリは読み取り専用です。
• すべての読み取り / 書き込み権限のプロジェクト レベルでの biglake.{catalogs|databases|tables}.*。通常、Apache Spark には、カタログ、データベース、テーブルの作成、管理、表示など、データの読み取りと書き込みを行うための機能が必要です。
• 接続を使用して BigQuery Iceberg テーブルを作成するための BigQuery クラウド リソース接続レベル以上の bigquery.connections.delegate。

BigLake Metastore に接続する

以降のセクションでは、BigLake Metastore に接続する方法について説明します。以下のセクションでは、次のメソッドで JAR ファイルに示されているように、BigLake Apache Iceberg カタログ プラグインをインストールして使用します。カタログ プラグインは、Apache Spark などのオープンソース エンジンから BigLake Metastore に接続します。

Dataproc VM に接続する

Dataproc VM を使用して BigLake Metastore に接続する手順は次のとおりです。

1. SSH を使用して Dataproc に接続する。

2. Spark SQL CLI で、次のステートメントを使用して、BigLake Metastore と連携するように Apache Iceberg カスタム カタログをインストールして構成します。

   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.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 Metastore カタログにリンクされています。
• PROJECT_ID: Spark カタログがリンクされる BigLake Metastore カタログの Google Cloud プロジェクト ID。
• LOCATION: Spark カタログがリンクされる BigLake Metastore カタログの 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 サーバーレス ジョブを実行できます。このプロセスは、Dataproc で直接 Dataproc Serverless ジョブを実行する場合と同様です。

メタストア リソースを作成する

以降のセクションでは、メタストア内にリソースを作成する方法について説明します。

カタログを作成する

カタログ名には制約があります。詳細については、制限事項をご覧ください。カタログを作成するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.create メソッドを使用して、カタログの名前を指定します。

Spark SQL

CREATE NAMESPACE SPARK_CATALOG;

Terraform

これにより、「google_biglake_catalog.default.id」変数で指定されたカタログに「HIVE」タイプの「my_database」という名前の BigLake データベースが作成されます。詳細については、Terraform BigLake のドキュメントをご覧ください。

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

データベースを作成する

データベース名には制約があります。詳細については、制限事項をご覧ください。データベース リソースとデータエンジンとの互換性を確保するには、リソース本文を手動で作成するのではなく、データエンジンを使用してデータベースを作成することをおすすめします。データベースを作成するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.databases.create メソッドを使用して、データベースの名前を指定します。

Spark SQL

CREATE NAMESPACE SPARK_CATALOG.BLMS_DB;

以下を置き換えます。

• BLMS_DB: 作成する BigLake Metastore データベース ID

Terraform

これにより、「google_biglake_catalog.default.id」変数で指定されたカタログに「HIVE」タイプの「my_database」という名前の BigLake データベースが作成されます。詳細については、Terraform BigLake のドキュメントをご覧ください。

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"
  }
}
}

テーブルを作成する

テーブル名には制約があります。詳細については、テーブルの命名をご覧ください。テーブルを作成するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.databases.tables.create メソッドを使用して、テーブルの名前を指定します。

Spark SQL

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

以下を置き換えます。

• BLMS_TABLE: 作成する BigLake Metastore テーブル ID

Terraform

これにより、「google_biglake_database.default.id」変数で指定されたデータベースに「HIVE」タイプの「my_table」という名前の BigLake Metastore テーブルが作成されます。詳細については、Terraform プロバイダのドキュメント（BigLake テーブル）をご覧ください。

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」Metastore カタログ、データベース、テーブルを作成する実行可能な E2E の例を示しています。この例の使用方法について詳しくは、基本的な Terraform コマンドをご覧ください。

Hive メタストアから BigLake Metastore に Iceberg テーブルをコピーする

Iceberg テーブルを作成して Hive メタストア テーブルを 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 テーブルにリンクする

BigLake Metastore は、Iceberg 用の BigLake 外部テーブルのクエリに推奨されるメタストアです。Spark で Iceberg テーブルを作成するときに、リンクされた BigLake Iceberg テーブルを同時に作成することもできます。

テーブルを自動的にリンクする

Spark で Iceberg テーブルを作成し、同時に BigLake 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: 作成する BigLake Iceberg テーブルのパス。 BigQuery テーブルパスの構文に従います。プロジェクトが指定されていない場合は、BigLake Metastore カタログと同じプロジェクトが使用されます。

• BQ_RESOURCE_CONNECTION（省略可）: 形式は project.location.connection-id です。指定すると、BigQuery クエリでは Cloud リソース接続の認証情報を使用して BigLake Metastore にアクセスします。指定されていない場合、BigQuery では BigLake テーブルの代わりに通常の外部テーブルを作成します。

  注: テーブルを作成する BigQuery データセットがすでに存在している必要があります。このステートメントではデータセットが作成されません。BigQuery のデータセットとテーブルのロケーションは、BigLake Metastore カタログと同じである必要があります。

テーブルを手動でリンクする

指定した BigLake Metastore テーブルの URI（blms://…）を使用して、BigLake Iceberg テーブルのリンクを手動で作成するには、次の 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 Metastore のリソースを表示する方法について説明します。

カタログを表示する

カタログ内のすべてのデータベースを表示するには、projects.locations.catalogs.list メソッドを使用してカタログの名前を指定します。

カタログに関する情報を表示するには、projects.locations.catalogs.get メソッドを使用してカタログの名前を指定します。

データベースを表示する

データベースを表示するには、次の手順を行います。

API

データベース内のすべてのテーブルを表示するには、projects.locations.catalogs.databases.list メソッドを使用してデータベースの名前を指定します。

データベースに関する情報を表示するには、projects.locations.catalogs.databases.get メソッドを使用してデータベースの名前を指定します。

Spark SQL

カタログ内のすべてのデータベースを表示するには、次のステートメントを使用します。

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

定義済みのデータベースに関する情報を表示するには、次のステートメントを使用します。

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

テーブルの表示

データベース内のすべてのテーブルを表示するか、定義済みのテーブルを表示するには、次のようにします。

API

データベース内のすべてのテーブルを表示するには、projects.locations.catalogs.databases.tables.list メソッドを使用してデータベースの名前を指定します。

テーブルに関する情報を表示するには、projects.locations.catalogs.databases.tables.get メソッドを使用してテーブルの名前を指定します。

Spark SQL

データベース内のすべてのテーブルを表示するには、次のステートメントを使用します。

SHOW TABLES IN SPARK_CATALOG.BLMS_DB;

定義済みのテーブルに関する情報を表示するには、次のステートメントを使用します。

DESCRIBE TABLE [EXTENDED] SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

メタストア リソースを変更する

以降のセクションでは、メタストア内のリソースを変更する方法について説明します。

テーブルを更新する

複数のジョブで同じテーブルを同時に更新しようとした場合の競合を回避するために、BigLake Metastore はオプティミスティック ロックを使用します。オプティミスティック ロックを使用するには、まず GetTable メソッドを使用してテーブルの現在のバージョン（etag と呼ばれる）を取得する必要があります。その後、テーブルを変更して、UpdateTable メソッドを使用し、以前に取得した etag を渡します。ETag の取得後に別のジョブがテーブルを更新すると、UpdateTable メソッドは失敗します。この対策により、一度に 1 つのジョブのみがテーブルを更新できるようになるため、競合が防止されます。

テーブルを更新するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.databases.tables.patch メソッドを使用して、テーブルの名前を指定します。

Spark SQL

SQL のテーブル更新オプションについては、ALTER TABLE をご覧ください。

テーブルの名前を変更する

テーブルの名前を変更するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.databases.tables.rename メソッドを使用して、テーブルの名前と newName 値を指定します。

Spark SQL

ALTER TABLE BLMS_TABLE RENAME TO NEW_BLMS_TABLE;

以下を置き換えます。

• NEW_BLMS_TABLE: BLMS_TABLE の新しい名前。BLMS_TABLE と同じデータセットに存在する必要があります。

メタストア リソースを削除する

以降のセクションでは、BigLake Metastore のリソースを削除する方法について説明します。

カタログを削除する

カタログを削除するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.delete メソッドを使用して、カタログの名前を指定します。この方法では、Google Cloud 上の関連ファイルは削除されません。

Spark SQL

DROP NAMESPACE SPARK_CATALOG;

データベースを削除する

データベースを削除するには、次のいずれかのオプションを選択します。

API

projects.locations.catalogs.databases.delete メソッドを使用して、データベースの名前を指定します。この方法では、Google Cloud 上の関連ファイルは削除されません。

Spark SQL

DROP NAMESPACE SPARK_CATALOG.BLMS_DB;

テーブルの削除

テーブルを削除するには、次のいずれかの方法を選択します。

API

projects.locations.catalogs.databases.tables.delete メソッドを使用して、テーブルの名前を指定します。この方法では、Google Cloud 上の関連ファイルは削除されません。

Spark SQL

テーブルを削除するだけの場合は、次のステートメントを使用します。

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

Google Cloud でテーブルと関連ファイルを削除するには、次のステートメントを使用します。

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE PURGE;