Dataproc Metastore 管理者インターフェース

このページでは、Dataproc Metastore 管理者インターフェースを使用する方法について説明します。

管理者インターフェースには、Dataproc Metastore サービスに保存されているメタデータを検査、管理するための一元化されたツールが用意されています。すべて Dataproc クラスタや Hive インスタンスに接続する必要はありません。代わりに、gcloud CLI または Dataproc Metastore API を使用してメタデータを管理できます。

たとえば、管理者インターフェースを使用して、バックエンド メタデータに対して SQL クエリを直接実行し、特定のテーブル名をフェッチできます。このプロセスは、Dataproc クラスタの作成、SSH を使用したクラスタへの接続、Hive インスタンスの起動、クエリの実行（例: SELECT * FROM table_name）というような典型的なワークフローよりも少ない手順になります。

結果として、管理者インターフェースを使用すると、時間を節約し、データの取得に必要な Google Cloud リソースの量を減らすことができます。

始める前に

• プロジェクトで Dataproc Metastore を有効にします。
• Dataproc Metastore サービスを作成します。
• メタデータを Dataproc Metastore にインポートします。

必要なロール

Dataproc Metastore 管理者インターフェースを使用するために必要な権限を取得するには、最小限の権限の原則に基づいて、プロジェクトの次の IAM ロールを付与するように管理者に依頼してください。

• Dataproc Metastore メタデータのクエリを実行する場合: ユーザー アカウントまたはサービス アカウントに対するメタデータ クエリ管理者（roles/metastore.metadataQueryAdmin）
• メタデータ（データベース、テーブル、パーティションなど）のリソース ロケーションを変更する場合や、テーブルを別のデータベースに移動する場合:
  • ユーザー アカウントまたはサービス アカウントに対するメタデータ変更管理者（roles/metastore.metadataMutateAdmin）
  • ユーザー アカウントまたはサービス アカウントの Dataproc Metastore 編集者（roles/metastore.editor）

ロールの付与の詳細については、アクセスの管理をご覧ください。

これらの事前定義ロールには、Dataproc Metastore 管理者インターフェースの使用に必要な権限が含まれています。必要な権限を正確に確認するには、[必要な権限] セクションを開いてください。

必要な権限

Dataproc Metastore 管理者インターフェースを使用するには、次の権限が必要です。

• Dataproc Metastore メタデータのクエリを実行する場合: metastore.services.queryMetadata
• Dataproc Metastore テーブルを変更または移動する場合: metastore.services.mutateMetadata

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

Dataproc Metastore の特定のロールと権限については、Dataproc Metastore IAM の概要をご覧ください。

サポートされている管理者オペレーション

管理者インターフェース オペレーションは、gcloud CLI または Dataproc Metastore API を使用してのみ実施できます。Google Cloud コンソールでは、管理者インターフェース オペレーションはサポートされていません。

管理インターフェースは、次のオペレーションに対応しています。

• 読み取り専用オペレーション。

  • メタデータをクエリします。
  警告: インタラクティブな読み取り専用クエリのみを実行します。本番環境の重要なプロセスでは、非インタラクティブな読み取り専用クエリを自動化または実行しないでください。基盤となるデータベース スキーマが予告なく変更された場合、非インタラクティブなクエリを実行すると問題が発生します。

• 読み取り / 書き込みオペレーション

  • メタデータのリソースの場所（データベース、テーブル、パーティションなど）を変更します。
  • テーブルのプロパティ（カスタム Key-Value ペアなど）を変更します。
  • テーブルを別のデータベースに移動します。

メタデータをクエリする

このオペレーションにより、SQL クエリを使用してデータベース内のメタデータ情報を検索できます。クエリを実行すると、結果がアーティファクト Google Cloud バケットにダンプされます。

このオペレーションを実行する前に、次の検討事項を留意してください。

• サポートされているオペレーションには、read-only MySQL または Spanner クエリのみが含まれます。クエリがデータを変更しようとすると、オペレーションは失敗します。
• 出力ファイルには最大で 1,000 行が含まれます。この構成は変更できません。

• 出力ファイルは自動的に削除されません。代わりに、Google Cloud バケットから手動で削除する必要があります。それらを削除しないと、追加のストレージ費用が発生する場合があります。

gcloud CLI

1. メタデータをクエリするには、次の gcloud metastore services query-metadata コマンドを実行します。

   gcloud metastore services query-metadata SERVICE \
     --location=LOCATION \
     --query=QUERY

   以下を置き換えます。

   • SERVICE: Dataproc Metastore サービスの名前。
   • LOCATION: Dataproc Metastore サービスが存在する Google Cloud リージョン。
   • QUERY: メタデータをターゲットとする SQL クエリ。
     • MySQL データベースを使用している場合は、通常の MySQL クエリを使用します。
     • Spanner データベースを使用している場合は、GoogleSQL クエリを使用します。

2. アーティファクト Google Cloud バケットで出力ファイルを表示します。

REST

注: 次のコマンドでは、ユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud init または gcloud auth login を実行するか、gcloud CLI に自動ログインする Cloud Shell を使用してログインできます。gcloud auth list を実行すると、アクティブなアカウントを確認できます。

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -X POST -d '{"query": "QUERY"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:queryMetadata

以下を置き換えます。

• QUERY: メタデータをターゲットとするために使用する SQL クエリ。
  • MySQL データベースを使用している場合は、通常の MySQL クエリを使用します。
  • Spanner データベースを使用している場合は、GoogleSQL クエリを使用します。
• PROJECT_ID: Dataproc Metastore サービスが存在する Google Cloud プロジェクト ID。
• SERVICE: Dataproc Metastore サービスの名前。
• LOCATION: Dataproc Metastore が存在するリージョン。

次の例は、DBS という名前のデータベースから select * クエリを実行するサンプル コマンドを示しています。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" -X POST -d  '{"query": "select * from DBS;"}' \
  https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:queryMetadata

クエリ メタデータ オペレーションの出力を解釈する

クエリ メタデータ コマンドを初めて実行すると、Dataproc Metastore によってアーティファクト Google Cloud バケットに Google Cloud フォルダが自動的に作成されます。このフォルダの名前は query-results です。クエリ実行（API 呼び出し）が成功するたびに、query-results フォルダ内に新しいフォルダが作成されます（ランダムに生成された UUID の名前が付けられます）。

新しいフォルダごとに、クエリ結果を含む result manifest ファイルが含まれます。このフォルダの場所は、API 呼び出しのレスポンスで返されます。

たとえば、レスポンスで resultManifestUri フィールドにはファイルの場所が含まれています。

"response": {
    "@type": "type.googleapis.com/google.cloud.metastore.QueryMetadataResponse",
    "resultManifestUri": "gs://gcs-bucket-6a3638b8-e319-46363-ad33-e632a5e/query-results/800156f5-2d13-4b80-bec3-2345a9e880f6/result-manifest"
  }

result manifest ファイルの出力は、次のようになります。

{
  "status": {
    "code": 0,
    "message": "Query results are successfully uploaded to cloud storage",
    "details": []
  },
  "filenames": ["result-001"]
}

結果のマニフェスト ファイルの詳細:

• status フィールドは、クエリが成功したか失敗したかを示します。
• クエリの実行が成功すると、作成されたすべてのファイルが filenames フィールドに一覧表示されます。これらのファイルは、result manifest ファイルと同じフォルダにあります。
• クエリが失敗した場合は、details フィールドにエラー メッセージが表示されます。

注: デフォルトでは、出力ファイルに TTL（有効期間）はありません。Google Cloud バケットからそれらを手動で削除するか、query-results フォルダにカスタム TTL ルールを作成する必要があります。それらを削除しないと、追加のストレージ費用が発生する場合があります。

メタデータのリソース ロケーションを変更する

このオペレーションによって、データベース、テーブル、またはパーティションのリソース ロケーションを変更できます。

このコマンドを実行すると、親ディレクトリまたはそれぞれのメタデータ リソースのみが更新されます。このコマンドでは、既存のデータは新しいロケーションに転送されません。

gcloud CLI

1. メタデータのリソース ロケーションを変更するには、次の gcloud metastore services alter-metadata-resource-location コマンドを実行します。

   gcloud metastore services alter-metadata-resource-location SERVICE \
     --location=LOCATION \
     --resource_name=RESOURCE_NAME \
     --location_uri=LOCATION_URI

   以下を置き換えます。

   • SERVICE: Dataproc Metastore サービスの名前。
   • LOCATION: Dataproc Metastore サービスが存在する Google Cloud リージョン。
   • RESOURCE_NAME: 変更するデータベース、テーブル、パーティションの名前。
   • LOCATION_URI: RESOURCE_NAME のコンテンツ用の新しい Cloud Storage パス。この値は、メタデータ リソース ロケーションの移動先のパスです。このパスは gs:// で始まる必要があります。例: gs://bucket/object。

2. リソース ロケーションが正常に変更されたことを確認します。

REST

注: 次のコマンドでは、ユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud init または gcloud auth login を実行するか、アカウントが gcloud auth list を実行する Cloud Shell を使用してログインできます。

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"resource_name": "RESOURCE_NAME", "location_uri":"LOCATION_URI"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterLocation

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

• PROJECT_ID: Dataproc Metastore サービスが存在する Google Cloud プロジェクト ID。
• SERVICE: Dataproc Metastore サービスの名前。
• LOCATION: Dataproc Metastore が存在するリージョン。
• RESOURCE_NAME: 変更するデータベース、テーブル、パーティションの名前。
• LOCATION_URI: RESOURCE_NAME のコンテンツ用の新しい Cloud Storage パス。この値は、メタデータ リソース ロケーションの移動先のパスです。このパスは gs:// で始まる必要があります。例: gs://bucket/object。

次の例は、test-table2 というテーブルを新しい Cloud Storage バケットに移動するサンプル コマンドを示しています。

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -X POST -d  '{"resource_name": "databases/testdb1/tables/test-table2",
   "location_uri":"gs://gcs-bucket-dpms1-9425bd83-b794-4f1c-9e79-2d833f758cc1/empty"}'
   https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:alterLocation

テーブルのプロパティを変更する

このオペレーションにより、テーブルのプロパティ（データの保存に使用するカスタム Key-Value ペアなど）を変更できます。たとえば、properties.customerID_1 の Key-Value ペアを properties.customerID_2 に変更できます。

gcloud CLI

1. テーブルのプロパティを変更するには、次の gcloud metastore services alter-table-properties コマンドを実行します。

   gcloud metastore services alter-table-properties SERVICE \
     --location=LOCATION \
     --table-name=TABLE_NAME \
     --update-mask=UPDATE_MASK \
     --properties=PROPERTIES

   以下を置き換えます。

   • SERVICE: Dataproc Metastore サービスの名前。
   • LOCATION: Dataproc Metastore サービスが存在する Google Cloud リージョン。
   • TABLE_NAME: 変更するプロパティを含むテーブルの名前（databases/{database_id}/tables/{table_id} の形式）。
   • UPDATE_MASK: 更新する既存のプロパティ値。Key-Value ペアを記述する場合は、カンマ区切りのリスト（例: properties.1,properties.2,properties.3,...）を使用します。
   • PROPERTIES: テーブルの新しいプロパティ。Key-Value ペアを記述する場合は、カンマ区切りのリストを使用します。例: a=1,b=2,c=3,...。ここで指定した値は、UPDATE_MASK の値を上書きします。

REST

注: 次のコマンドでは、ユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud init または gcloud auth login を実行するか、gcloud CLI に自動ログインする Cloud Shell を使用してログインできます。gcloud auth list を実行すると、アクティブなアカウントを確認できます。

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "update_mask":"UPDATE_MASK", "properties":PROPERTIES}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterTableProperties

以下を置き換えます。

• SERVICE: Dataproc Metastore サービスの名前。
• LOCATION: Dataproc Metastore サービスが存在する Google Cloud リージョン。
• TABLE_NAME: 変更するプロパティを含むテーブルの名前（databases/{database_id}/tables/{table_id} の形式）。
• UPDATE_MASK: 更新する既存のプロパティ値。Key-Value ペアを記述する場合は、カンマ区切りのリスト（例: properties.1,properties.2,properties.3,...）を使用します。
• PROPERTIES: テーブルの新しいプロパティ。Key-Value ペアを記述する場合は、カンマ区切りのリスト（例: a=1,b=2,c=3,...）を使用します。ここで指定した値は、UPDATE_MASK の値を上書きします。

次の例は、test-table というテーブルのテーブル プロパティを変更するサンプル コマンドを示しています。この例では、既存の Key-Value ペア properties.customerID_1 は、新しい値 properties.customerID_2 に更新されます。

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -X POST -d  '{"table_name": "databases/default/tables/test-table", "update_mask":{"paths":"properties.customerID_1"}, "properties":{"customerID_1":"customerID_2"}}' https://metastore.googleapis.com/projects/dpms-p

テーブルを別のデータベースに移動する

このオペレーションにより、内部テーブル（マネージド テーブル）を別のデータベースに移動できます。この場合、データベースの親ディレクトリとそのデータの両方が移動します。

外部テーブルに保存されているデータは移動できません。

gcloud CLI

1. テーブルを別のデータベースに移動するには、次の gcloud metastore services move-table-to-database コマンドを実行します。

   gcloud metastore services move-table-to-database SERVICE \
     --location=LOCATION \
     --db_name=DB_NAME \
     --table_name=TABLE_NAME \
     --destination_db_name=DESTINATION_DB_NAME

   以下を置き換えます。

   • SERVICE: Dataproc Metastore サービスの名前。
   • LOCATION: Dataproc Metastore サービスが存在する Google Cloud リージョン。
   • DB_NAME: 移動するテーブルを含むソース データベースの名前。
   • TABLE_NAME: 移動するテーブルの名前。
   • DESTINATION_DB_NAME: テーブルを移行する先の新しいデータベースの名前。

2. テーブルの変更が成功したことを確認します。

REST

注: 次のコマンドでは、ユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud init または gcloud auth login を実行するか、gcloud CLI に自動ログインする Cloud Shell を使用してログインできます。gcloud auth list を実行すると、アクティブなアカウントを確認できます。

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "db_name": "DB_NAME", "destination_db_name": "DESTINATION_DB_NAME"}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:moveTableToDatabase

以下を置き換えます。

• PROJECT_ID: Dataproc Metastore サービスが存在する Google Cloud プロジェクト ID。
• SERVICE: Dataproc Metastore サービスの名前。
• LOCATION: Dataproc Metastore が存在するリージョン。
• DB_NAME: 移動するテーブルを含むソース データベースの名前。
• TABLE_NAME: 移動するテーブルの名前。
• DESTINATION_DB_NAME: テーブルを移行する先の新しいデータベースの名前。

次の例は、testdb1 というデータベースを testdb2 という異なるデータベースに移動するサンプル コマンドを示しています。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json"
 -X POST -d  '{"table_name": "testtb1", "db_name": "testdb1",
 "destination_db_name": "testdb2"}' https://metastore.googleapis.com/projects/dpms/locations/asia-northeast2/services/dpms1:moveTableToDatabase

次のステップ

• ExportMetadata
• メタストアの更新
• メタストアのバックアップ