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

Dataproc Metastore サービスから、ボーダーレス Lakehouse に構築された Apache Iceberg REST カタログ エンドポイントまたは Hive カタログ エンドポイントにメタデータを移行できます。この移行により、オープン テーブル形式にモダナイズし、複数の分析エンジン間でカタログ アクセスを統合できます。

ユースケース

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

始める前に

1. 移行元としてアクティブな Dataproc Metastore サービスが存在することを確認します。
2. ターゲットの Hive カタログまたは Iceberg カタログが存在し、ソーステーブルのデータとメタデータが存在する Cloud Storage バケットまたはパス（gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse などの Dataproc Metastore ウェアハウス バケットなど）が含まれていることを確認します。

   宛先カタログにデータのロケーションが含まれていない場合、ターゲット カタログはテーブルを登録できないため、テーブルの移行は失敗します。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, Dataproc Metastore APIs, if any are not already enabled.

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, Dataproc Metastore APIs, if any are not already enabled.

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

必要なロール

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

• 移行を開始する: Dataproc Metastore 編集者 （roles/metastore.editor）
• Hive または Iceberg カタログを作成する: BigLake 管理者 （roles/biglake.admin）
• ターゲット プロジェクトを使用してメタデータを宛先カタログに移行する: Dataproc Metastore サービス エージェント（[e-mail]）に対する BigLake 管理者（roles/biglake.admin）。
• レポート バケットの移行レポートを作成する（サービス アーティファクト バケットを使用しない場合）: Dataproc Metastore サービス エージェント（[e-mail]）に対するストレージ オブジェクト管理者（roles/storage.objectAdmin）

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

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

移行の仕組み

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

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

移行を実行する

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

移行を開始する

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

コンソール

1. Google Cloud コンソールで、[Dataproc Metastore] ページに移動します。

   [Dataproc Metastore] に移動

2. metastore サービスリストで、移行するサービスの名前をクリックします。

3. サービスの詳細ページで、上部のナビゲーション バーにある [レイクハウスに移行] をクリックします。

4. [移行名] に、移行の表示名を入力します。

5. [移行タイプ] で、[バックフィル移行] を選択して移行を実行するか、[ドライラン] を選択して、宛先カタログにメタデータを書き込まずに移行を検証します。

6. ターゲット設定を構成します。

   • レポート: （省略可）移行ステータス レポートを保存する Cloud Storage パスを選択します。指定しない場合、レポートは Dataproc Metastore サービスのアーティファクト バケットに生成されます。
   • 競合処理: 重複するデータベース エントリをスキップするか、上書きするかを選択します。

7. [宛先] で、移行先のカタログの種類（[Iceberg REST カタログ エンドポイント] または [Hive metastore]）を選択します。ソース データベースから移行する必要があるテーブルのタイプに応じて、1 つのカタログまたは両方のカタログに同時に移行できます。

   Iceberg REST カタログに移行する場合:

   1. [プロジェクト] で、移行先のカタログを含むプロジェクトを選択します。
   2. [Iceberg REST カタログ] で、移行先のカタログを選択するか、[カタログを作成] をクリックして新しいカタログを作成します。

   Hive カタログに移行する場合:

   1. [プロジェクト] で、移行先のカタログを含むプロジェクトを選択します。
   2. [Hive カタログ] で、移行先のカタログを選択するか、[カタログを作成] をクリックして新しいカタログを作成します。

8. [移行を開始] をクリックします。

[移行] タブに自動的にリダイレクトされます。[マネージド移行] に移行が一覧表示され、移行が完了するまで状態が更新されます。

gcloud

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

gcloud 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

注: --hive-databases または --iceberg-namespaces に * を指定すると、すべてのデータベースまたは名前空間を移行できます。

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

• 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 を使用してメタデータの移行をトリガーするには、BigLakeMetastoreMigrationConfig 構成で startMigration メソッドを呼び出します。

注: databases または namespaces に ["*"] を使用すると、すべてのデータベースまたは Namespace を移行できます。

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/v1/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 metastore services migrations describe コマンドを実行します。

gcloud 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/v1/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 スキーマに基づいて 2 つの詳細な JSON レポート ファイルを reportPath で指定されたターゲット Cloud Storage パスに書き込みます。

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

Google Cloud コンソールでレポートを表示する手順は次のとおりです。

1. Google Cloud コンソールで、[Dataproc Metastore] ページに移動します。

   [Dataproc Metastore] に移動

2. メタストア サービスの一覧で、レポートを含むサービスの表示名をクリックします。

   [移行] ページが開きます。

3. [マネージド移行] で、レポートを含む移行の名前を選択します。

   [移行の詳細] ページが開き、移行されたデータベースとテーブルの詳細、および移行ステータスが表示されます。

制限事項

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

次のステップ

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