2026 年 4 月 20 日より、BigLake は Lakehouse for Apache Iceberg に名称変更されました。BigLake metastore は、Lakehouse ランタイムカタログと呼ばれるようになりました。Lakehouse API、クライアントライブラリ、CLI コマンド、IAM 名は変更されず、引き続き BigLake を参照します。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Dataproc Metastore から Lakehouse にメタデータを移行する

このドキュメントでは、ボーダレス Lakehouse 上に構築された Dataproc Metastore サービスから Apache Iceberg REST カタログエンドポイントまたは Hive カタログエンドポイントにメタデータを移行する方法について説明します。

ユースケース

サーバーレスの最新化: 従来の Hive Metastore（HMS）から、自動スケーリングされるフルマネージドカタログに移行することで、メタストア管理の運用オーバーヘッドを排除します。
マルチエンジンコラボレーション: Apache Spark、Apache Flink、Apache Hive、BigQuery などのエンジン間でデータ共有を有効にすることで、データサイエンティストとアナリストが同じテーブルで同時に作業できるようになり、ファイルの重複を回避できます。
BigQuery との直接統合: 高パフォーマンスの実行により、BigQuery からオープンソーステーブルに直接クエリを実行します。
統合ガバナンス: メタデータを単一の信頼できる情報源に統合することで、データ検出を簡素化し、ポリシーの適用を統一します。
最新のテーブル形式: 既存の Hive ワークロードとの完全な互換性を維持しながら、Apache Iceberg などの高度なオープン形式をシームレスに採用します。

始める前に

移行元としてアクティブな Dataproc Metastore サービスが存在することを確認します。
移行先の Hive カタログまたは Iceberg カタログが存在し、ソーステーブルのデータとメタデータが格納されている Cloud Storage バケットまたはパス（Dataproc Metastore ウェアハウスバケットなど、 gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse）が含まれていることを確認します。
移行先カタログにデータロケーションが含まれていない場合、移行先カタログがテーブルを登録できないため、テーブル移行は失敗します。Iceberg カタログの作成については、Iceberg REST カタログエンドポイントを設定するをご覧ください。
Hive カタログを作成するには、Lakehouse Hive カタログを作成するをご覧ください。

Google Cloud アカウントにログインします。を初めて使用する場合は Google Cloud、アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse for Apache Iceberg, Dataproc Metastore APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse for Apache Iceberg, Dataproc Metastore APIs.

Roles required to enable APIs

Enable the APIs

必要なロール

移行をトリガーするために必要な権限を取得するには、管理者に Dataproc Metastore サービスに対する次の IAM ロールを付与するよう依頼してください。

移行を開始する: Dataproc Metastore 編集者（roles/metastore.editor）
Hive カタログまたは Iceberg カタログを作成する: BigLake 管理者 (roles/biglake.admin)
移行先プロジェクトを使用してメタデータを移行先カタログに移行する: BigLake 管理者 (roles/biglake.admin)（Dataproc Metastore サービスエージェント（service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com）に対する）
レポートバケットの移行レポートを書き込む（サービスアーティファクトバケットを使用しない場合）: ストレージオブジェクト管理者（roles/storage.objectAdmin）: Dataproc Metastore サービスエージェント（service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com）に対する

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

移行の仕組み

移行プロセスは次のとおりです。

移行先カタログを選択する: 移行先の Hive カタログエンドポイントまたは Apache Iceberg REST カタログエンドポイントを選択します。
移行をトリガーする: gcloud beta metastore services migrations start コマンドを実行するか、Dataproc Metastore サービスで startMigration メソッドを呼び出して、移行を開始します。
ステータスをポーリングする: gcloud beta metastore services migrations describe コマンドを使用するか、ターゲット実行をポーリングして、移行の進行状況をモニタリングします。
レポートを確認する: 指定した Cloud Storage パスに書き込まれた詳細な JSON レポートを確認して、結果を検証します。

移行を実行する

移行を実行するには、移行プロセスをトリガーして、その進行状況をモニタリングします。

移行を開始する

Dataproc Metastore サービスでメタデータ移行をトリガーするには、gcloud CLI または REST API を使用します。

gcloud

gcloud を使用して移行を開始するには、gcloud beta metastore services migrations start コマンドを実行します。

gcloud beta metastore services migrations start SERVICE_ID \
    --location=REGION \
    --hive-catalog="projects/PROJECT_ID/catalogs/HIVE_CATALOG_ID" \
    --hive-databases="HIVE_DB_1,HIVE_DB_2" \
    --iceberg-catalog="projects/PROJECT_ID/catalogs/ICEBERG_CATALOG_ID" \
    --iceberg-namespaces="ICEBERG_NAMESPACE_1,ICEBERG_NAMESPACE_2" \
    --async

次のように置き換えます。

SERVICE_ID: Dataproc Metastore サービスの ID
REGION: Dataproc Metastore サービスのリージョン
PROJECT_ID: 実際の Google Cloud プロジェクト ID
HIVE_CATALOG_ID: 移行先の Hive カタログ ID
HIVE_DB_1、HIVE_DB_2: 移行する Hive データベース。
ICEBERG_CATALOG_ID: 移行先の Iceberg カタログ ID
ICEBERG_NAMESPACE_1、ICEBERG_NAMESPACE_2: 移行する Iceberg 名前空間。

REST

REST API を使用してメタデータ移行をトリガーするには、 startMigration メソッドを BigLakeMetastoreMigrationConfig 構成で呼び出します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "migrationExecution": {
        "biglakeMetastoreMigrationConfig": {
          "mode": "BACKFILL",
          "dryRun": false,
          "reportPath": "gs://BUCKET_NAME/PATH/",
          "conflictPolicy": "SKIP",
          "hiveConfig": {
            "catalog": "projects/PROJECT_ID/catalogs/HIVE_CATALOG_ID",
            "databases": ["HIVE_DB_1", "HIVE_DB_2"]
          },
          "icebergConfig": {
            "catalog": "projects/PROJECT_ID/catalogs/ICEBERG_CATALOG_ID",
            "namespaces": ["ICEBERG_NAMESPACE_1", "ICEBERG_NAMESPACE_2"]
          }
        }
      }
    }' \
    "https://metastore.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID:startMigration"

次のように置き換えます。

BUCKET_NAME: レポート用の Cloud Storage バケットの名前
PATH: レポート用のバケット内のパス
PROJECT_ID: 実際の Google Cloud プロジェクト ID
HIVE_CATALOG_ID: 移行先の Hive カタログ ID
HIVE_DB_1、HIVE_DB_2: 移行する Hive データベース。
ICEBERG_CATALOG_ID: 移行先の Iceberg カタログ ID
ICEBERG_NAMESPACE_1、ICEBERG_NAMESPACE_2: 移行する Iceberg 名前空間。
REGION: Dataproc Metastore サービスのリージョン
SERVICE_ID: Dataproc Metastore サービスの ID

移行の実行をポーリングする

このリクエストは、長時間実行オペレーション（LRO）を開始し、一意の移行実行 ID を返します。gcloud CLI または REST API を使用して、実行の進行状況をモニタリングできます。

gcloud

gcloud を使用して移行の実行を記述するには、gcloud beta metastore services migrations describe コマンドを実行します。

gcloud beta metastore services migrations describe MIGRATION_EXECUTION_ID \
    --service=SERVICE_ID \
    --location=REGION

次のように置き換えます。

MIGRATION_EXECUTION_ID: 前のステップで返された移行実行の ID
SERVICE_ID: Dataproc Metastore サービスの ID
REGION: Dataproc Metastore サービスのリージョン

REST

REST API を使用して実行の進行状況をモニタリングするには、その実行パスで get メソッドを呼び出します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://metastore.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID/migrationExecutions/MIGRATION_EXECUTION_ID"

次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID
REGION: Dataproc Metastore サービスのリージョン
SERVICE_ID: Dataproc Metastore サービスの ID
MIGRATION_EXECUTION_ID: 前のステップで返された移行実行の ID

詳細な移行レポート

移行（バックフィルまたはドライラン）が完了すると、移行ツールは `MigrationReport` スキーマに基づいて、 MigrationReport reportPath`reportPath` で指定された移行先の Cloud Storage パスに 2 つの詳細な JSON レポートファイルを書き込みます。

summary.json: 上位レベルの集計された MigrationSummary 構造が含まれます。
full_report.json: 詳細で粒度の細かい移行レポートが含まれます。詳細については、 CatalogReport をご覧ください。

制限事項

移行先カタログには、ソーステーブルのデータとメタデータが格納されている Cloud Storage バケットまたはパス（ Dataproc Metastore ウェアハウスバケットなど）が含まれている必要があります。移行先カタログがデータバケットのロケーションで構成されていない場合、移行先カタログはテーブルを登録できず、テーブルの移行は失敗します。
このツールは、1 回限りのバックフィルのみをサポートしています。移行後にソース Dataproc Metastore にメタデータの変更を加えても、自動的に伝播されません。移行を再実行して、移行先カタログをソースと同期する必要があります。
移行は、移行先カタログの制限を受けます。Dataproc Metastore テーブルに、移行先カタログでサポートされていないスキーマ構造またはプロパティ（複合型など）が含まれている場合、その特定のテーブルの移行は失敗します。
テーブルまたはデータベースの Dataproc Metastore 権限は、Lakehouse に移行されません。

次のステップ

Lakehouse ランタイムカタログの詳細を確認する。
Lakehouse ランタイムカタログを使用して Spark と Hive を設定する方法を確認する。
Lakehouse ランタイムカタログ、Spark、 BigQuery を使用して Iceberg テーブルにクエリを実行する方法を確認する。

Dataproc Metastore から Lakehouse にメタデータを移行する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ユースケース

始める前に

必要なロール

移行の仕組み

移行を実行する

移行を開始する

gcloud

REST

移行の実行をポーリングする

gcloud

REST

詳細な移行レポート

制限事項

次のステップ

Dataproc Metastore から Lakehouse にメタデータを移行する