Databricks Unity Catalog からメタデータをインポートする

Knowledge Catalog（旧称 Dataplex Universal Catalog）コネクタを使用して Databricks Unity Catalog から Google Cloudにメタデータを直接インポートすることで、データサイロを解消し、ツールの切り替えを回避します。

このコネクタは、Google Cloud、Microsoft Azure、アマゾン ウェブ サービス（AWS）でホストされている Databricks Unity Catalog インスタンスをサポートしています。

次の表に、Databricks Unity Catalog コネクタがキャプチャするメタデータを示します。

カテゴリ	メタデータのキャプチャ
技術	メタストア カタログ スキーマ テーブル（マネージド Delta、外部、ストリーミング、オンライン、特徴、Apache Iceberg REST Catalog（IRC）） ビュー（標準、マテリアライズド） ボリューム 関数とプロシージャ
運用	使用状況の指標（30 日間と 90 日間のビュー、30 日間の読み取り、書き込み、頻繁なユーザー、頻繁に結合されるテーブル） 主キーと外部キー
ビジネス	タグ（オブジェクト、データ分類） データ品質（データ品質モニタリングによる異常検出結果、レイクハウス モニタリングによるデータドリフトとカスタム指標） データ プロファイリング（Lakehouse Monitoring から） 結合と関係 テーブルとビューのオーナー、作成日時、最終変更日時
Semantic	指標ビュー（ディメンション、メジャー、関係マッピング、認定資格） 指標ビューのオーナー 指標ビューの使用状況（30 日間と 90 日間のビュー、30 日間の読み取り、書き込み、頻繁なユーザー、頻繁に結合されるテーブル） 表示名（指標ビューから） 類義語（指標ビューから） マークダウン コメント

制限事項

Databricks Unity Catalog コネクタには次の制限があります。

• リネージはサポートされていません。
• セマンティック タグとビジネス用語集は、統合（Genie API）ではサポートされていません。
• コネクタは Iceberg テーブルのメタデータをインポートしますが、インポートされたエントリを対応する Google Cloud Lakehouse Databricks Unity Catalog Iceberg REST Catalog（IRC）エントリに自動的にリンクしません。

始める前に

Databricks Unity Catalog からメタデータをインポートする前に、次のタスクを完了します。

1. 必要なロールと権限を付与します。
2. Dataplex API と BigQuery Data Transfer Service API を有効にします。
3. Databricks Unity Catalog の前提条件を満たします。
4. ネットワークの前提条件を満たします。

IAM のロールと権限

Knowledge Catalog コネクタジョブを作成して管理するには、Knowledge Catalog と BigQuery Data Transfer Service の権限を付与する Identity and Access Management（IAM）ロールが必要です。

Databricks Unity Catalog コネクタの構成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• エントリ グループを作成、管理するには: プロジェクトに対する Dataplex Catalog 管理者（roles/dataplex.catalogAdmin）、Dataplex Catalog 編集者（roles/dataplex.catalogEditor）、または Dataplex エントリ グループ オーナー（roles/dataplex.entryGroupOwner）。
• Databricks Unity Catalog メタデータを表示するには: プロジェクトに対する Dataplex Catalog 閲覧者（roles/dataplex.catalogViewer）。
• BigQuery Data Transfer Service 転送ジョブを作成して管理する: プロジェクトに対する BigQuery 管理者（roles/bigquery.admin）。
• Cloud Logging でログを表示するには: プロジェクトに対するログビューア（roles/logging.viewer）。

また、BigQuery Data Transfer Service サービス エージェント（[e-mail]）に次の両方のロールを付与する必要があります。

• 宛先エントリ グループまたはそれを含むプロジェクトに対する Dataplex エントリ グループ インポータ（roles/dataplex.entryGroupImporter）。このロールにより、サービス エージェントはメタデータをエントリ グループ（dataplex.entryGroups.import）にインポートできます。

• 宛先エントリ グループを含むプロジェクトに対する Dataplex エントリ / エントリリンク オーナー（roles/dataplex.entryOwner）。このロールにより、サービス エージェントは使用状況、ビジネス、データ品質のメタデータとエントリリンクをインポートできます。このロールに含まれる権限は以下のとおりです。

  • dataplex.entryGroups.useDataProfileAspect
  • dataplex.entryGroups.useDataQualityScorecardAspect
  • dataplex.entryGroups.useManagedConnectorTypes
  • dataplex.entryGroups.useReferenceEntryLink
  • dataplex.entryGroups.useSchemaAspect
  • dataplex.entryGroups.useSchemaJoinAspect
  • dataplex.entryGroups.useSchemaJoinEntryLink
  • dataplex.entryGroups.useUsageAspect
  • dataplex.entryLinks.reference

  インポートではプロジェクトの dataplex.entryLinks.reference 権限がチェックされるため、エントリ グループだけでなく、プロジェクトでもこのロールを付与します。サービス エージェントにプロジェクトに対するこの権限がない場合、転送実行は Permission 'dataplex.entryLinks.reference' denied などのエラーで失敗し、メタデータはインポートされません。

これらのロールを両方付与する代わりに、宛先エントリ グループを含むプロジェクトに Dataplex エントリ グループ オーナー（roles/dataplex.entryGroupOwner）ロールを付与することもできます。このロールには、両方のロールの権限が含まれています。また、サービス エージェントは、プロジェクト内のすべてのエントリ グループを作成、削除、管理できます。

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

API を有効にする

Dataplex API と BigQuery Data Transfer Service API を有効にします。

API を有効にする

Databricks Unity Catalog の前提条件

Databricks Unity Catalog コネクタに使用されるサービス プリンシパルには、Databricks Unity Catalog で次の権限が必要です。

• コネクタで使用される Databricks SQL ウェアハウスに対する Can use 権限。
• ターゲット カタログに対する BROWSE 権限、またはターゲット カタログ、スキーマ、テーブルまたはビューに対する USE CATALOG、USE SCHEMA、SELECT。
• system カタログに対する USE CATALOG、および次のシステム スキーマに対する USE SCHEMA と SELECT。
  • system.information_schema: カタログ、スキーマ、テーブル、列、ボリューム、ルーティン、制約、タグの読み取りに必要です。
  • system.access と system.query: 省略可。使用状況の指標、使用状況の分析情報、クエリ履歴の結合をインポートするために必要です。
  • system.data_quality_monitoring: 省略可。異常検出結果をインポートするために必要です。
• 省略可: Lakehouse Monitoring 出力テーブル（TABLE_NAME_profile_metrics と TABLE_NAME_drift_metrics）に対する USE CATALOG、USE SCHEMA、SELECT。データ プロファイリングとドリフト指標をインポートします。

リモート Databricks カタログに対して SQL クエリまたは Spark ジョブを実行する場合は、Databricks Unity Catalog のクロス クラウド接続を設定するをご覧ください。

ネットワーキングの前提事項

BigQuery Data Transfer Service がプライベート ネットワーク内のプライベート IP アドレスを使用して外部データベースまたはサードパーティのクラウド データソースに安全に接続できるようにするには、Private Service Connect を介してネットワーク アタッチメントを構成します。

パブリック IP アドレスを使用してオンプレミス環境またはクラウドホスト型インスタンスに接続する場合、ネットワーク アタッチメントは必要ありません。

注: ネットワーク アタッチメントを使用するプライベート ドメインはサポートされていません。

Databricks Unity Catalog コネクタを構成する

Google Cloud コンソールまたは REST API を使用して、Databricks Unity Catalog コネクタを構成します。

コンソール

1. Google Cloud コンソールで、Knowledge Catalog ページに移動します。

   Knowledge Catalog に移動

2. ナビゲーション メニューの [管理] セクションで、[コネクタ] をクリックし、[接続を追加] をクリックします。

3. [コネクタ] リストで、[Databricks Unity Catalog] カードを選択します。

4. [データソースの詳細] セクションで、Databricks Unity Catalog インスタンスの接続の詳細を指定します。

   • [ネットワーク アタッチメント] で、必要に応じて既存のネットワーク アタッチメントを選択するか、作成します。
   • ワークスペース ホスト、SQL ウェアハウスの HTTP パス、クライアント ID、クライアント シークレット を入力します。

   • [転送する Databricks オブジェクト] で、[参照] をクリックして、Knowledge Catalog にインポートするメタストア、カタログ、スキーマ、または個々のオブジェクト（テーブル、ビュー、ボリューム、関数、プロシージャ）を選択します。メタストア、カタログ、スキーマを選択すると、その中のすべてのオブジェクトがインポートされます。

     オブジェクトを手動で入力することもできます。その場合は、TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]] の形式を使用します。ここで、TYPE は METASTORE、CATALOG、SCHEMA、TABLE、VIEW、VOLUME、FUNCTION、PROCEDURE のいずれかです（例: SCHEMA:my_metastore/main/sales）。名前パターンはサポートされていません。

5. [宛先の設定] セクションで、次の操作を行います。

   • [参照] をクリックして、インポートしたメタデータを保存する既存の Knowledge Catalog エントリ グループを選択するか、[新しいエントリ グループを作成] をクリックします。
   • エントリ グループの権限を今すぐ設定するか、後で設定するかを選択します。ユーザーがインポートされたメタデータを表示できるようにするには、エントリ グループに権限を設定します。プロジェクト レベルで BigQuery Data Transfer Service サービス エージェントに Dataplex エントリ グループ インポータ（roles/dataplex.entryGroupImporter）ロールまたは dataplex.entryGroups.import 権限を付与していない場合は、このエントリ グループに付与します。dataplex.entryLinks.reference 権限はプロジェクト レベルで確認されるため、プロジェクトに対する Dataplex エントリ / エントリリンク オーナー（roles/dataplex.entryOwner）ロールを付与する必要があります。詳細については、IAM のロールと権限をご覧ください。

6. [転送構成名] セクションの [表示名] に、メタデータのインポート ジョブの名前を入力します。

7. [スケジュール オプション] セクションで、メタデータ インポート ジョブの頻度を構成します。[オンデマンド] を選択した場合、ジョブは手動でトリガーした場合にのみ実行されます。

8. 省略可: [通知オプション] セクションで、ジョブの失敗に関するメール通知または Pub/Sub 通知を構成します。

9. 省略可: [詳細オプション] セクションで、暗号化設定を構成します。顧客管理の暗号鍵（CMEK）を選択すると、Knowledge Catalog メタデータ インポート ジョブを開始する前にステージングされた一時データが鍵によって暗号化されます。この鍵は、宛先の Knowledge Catalog エントリ グループのメタデータを暗号化しません。

10. [保存] をクリックします。

REST

projects.locations.transferConfigs.create メソッドを使用します。TransferConfig リソースで、次のフィールドを構成します。

• dataSourceId フィールドを "databricks_unity" に設定します。
• metadataDestination フィールドの dataplexConfiguration.entryGroup フィールドに、ターゲット Knowledge Catalog エントリ グループのリソースパス（projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID）を入力します。
• params フィールドで、次のパラメータを設定します。
  • connector.host（必須）: Databricks ワークスペースのホスト名（例: dbc-a1b2345c-d6e7.cloud.databricks.com）。
  • connector.httpPath（必須）: Databricks SQL ウェアハウスの HTTP パス（例: /sql/1.0/warehouses/a1b2345c67890def）。
  • connector.authentication.oauth.clientId（必須）: Databricks OAuth クライアント ID。
  • connector.authentication.oauth.clientSecret（必須）: Databricks OAuth クライアント シークレット。
  • connector.networkAttachment（省略可）: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID 形式のネットワーク アタッチメント。
  • assets（必須）: インポートする Databricks Unity Catalog オブジェクトのリスト。TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]] 形式（["SCHEMA:my_metastore/main/sales"] など）。
• 省略可: OAuth 認証情報を転送構成に含めないようにするには、Secret Manager に保存します。
  1. connector.authentication.oauth.clientSecret（必要に応じて connector.authentication.oauth.clientId）を projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID 形式のシークレット バージョン リソース名に設定し、それらのパラメータ名を paramConfig.secretManagerManagedParams フィールドに追加します。
  2. 各シークレットに対する Secret Manager シークレット アクセサー（roles/secretmanager.secretAccessor）ロールを、転送構成（[e-mail]）を含むプロジェクトの BigQuery Data Transfer Service サービス エージェントに付与します。シークレットは別のプロジェクトに存在してもかまいません。サービス エージェントがシークレットを読み取れない場合、実行は開始前に失敗し、Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied などのエラーが発生します。BigQuery Data Transfer Service は、各実行の開始時にシークレットを読み取ります。したがって、VERSION_ID を latest に設定すると、次の実行からローテーションされたシークレットが使用されます。

次の例は、TransferConfig リクエスト本文を示しています。

{
  "displayName": "databricks-unity-metadata-import",
  "dataSourceId": "databricks_unity",
  "schedule": "every 24 hours",
  "params": {
    "connector.host": "dbc-a1b2345c-d6e7.cloud.databricks.com",
    "connector.httpPath": "/sql/1.0/warehouses/a1b2345c67890def",
    "connector.authentication.oauth.clientId": "CLIENT_ID",
    "connector.authentication.oauth.clientSecret": "CLIENT_SECRET",
    "assets": [
      "SCHEMA:my_metastore/main/sales"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

ジョブはスケジュールに基づいて自動的に実行されます。また、手動でトリガーすることもできます。

Databricks Unity Catalog コネクタジョブをモニタリングする

Google Cloud コンソールまたは REST API を使用して、Databricks Unity Catalog コネクタジョブをモニタリングします。

コンソール

1. Google Cloud コンソールの [コネクタ] ページで、Databricks Unity Catalog 転送ジョブの表示名をクリックします。
2. [実行履歴] タブで、[詳細を表示] をクリックしてログを表示します。
3. 作成されたエントリを表示するには、[詳細] タブをクリックし、[メタデータの宛先] エントリ グループのリンクをクリックします。

REST

• 転送構成の実行を一覧表示してその状態を表示するには、projects.locations.transferConfigs.runs.list メソッドを使用します。

• 各実行では、ID が dts-run-RUN_ID のメタデータ インポート ジョブを使用して、収集されたメタデータを Knowledge Catalog にインポートします。作成されたエントリの数など、インポートの結果を表示するには、次のクエリを使用して Logging でジョブのログをフィルタします。

  logName="projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job"
  AND resource.labels.metadata_job_id="dts-run-RUN_ID"
  

• Logging を使用せずにインポートの結果を表示するには、projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID で projects.locations.metadataJobs.get メソッドを呼び出します。importResult フィールドには、作成、更新、変更なし、削除されたエントリとエントリリンクの数が表示されます。

注: 転送実行では、メタデータのインポート ジョブが SUCCEEDED_WITH_ERRORS で終了した場合でも、SUCCEEDED の状態が表示されることがあります。たとえば、エントリのアスペクトの 1 つが大きすぎるためにエントリが拒否された場合などです。メタデータのインポート ジョブの状態とログを確認して、すべてのエントリがインポートされたことを確認します。

Databricks Unity Catalog のメタデータを検索して表示する

1. Google Cloud コンソールで、Knowledge Catalog の [検索] ページに移動します。

   [検索] に移動

2. [フィルタ] パネルで、[プロジェクト]、[システム]、[タイプ エイリアス] セクションを使用して、Databricks Unity Catalog アセットをフィルタします。すべての Databricks Unity Catalog メタデータをフィルタするには、[システム] セクションで [インポートされたコンテキスト] を選択し、[マネージド コネクタ] サブセクションで [Databricks Unity] を選択します。

3. 検索フィールドに、キーワードまたは自然言語検索クエリを入力します。たとえば、キーワード検索ですべての Databricks Unity Catalog アセットを表示するには、「system=DATABRICKS」と入力します。

   リソースの検索の詳細については、Knowledge Catalog でリソースを検索するをご覧ください。検索フィールドで使用できる式の詳細については、Knowledge Catalog の検索構文をご覧ください。

LookupContext API を使用して、特定の Databricks Unity Catalog リソースの LLM コンテキストを取得することもできます。詳細については、データアセットのコンテキストを取得するをご覧ください。

次のステップ

• コネクタジョブを管理する方法を学習する。