データリネージの問題のトラブルシューティング

Knowledge Catalog（旧称 Dataplex Universal Catalog）のデータリネージを使用すると、データの移動を追跡し、データの発生元を把握して、データ パイプラインをデバッグできます。リネージグラフ、プロセス メタデータ、テーブルの詳細、列レベルのリンクが想定どおりに表示されない場合や、予期しない Knowledge Catalog Premium Processing の料金が発生した場合は、プロジェクトの権限、API 設定、サポートされているサービスの種類を確認してください。

このドキュメントで説明されていない問題の解決にサポートが必要な場合は、Cloud カスタマーケアをご覧ください。

プロジェクトの種類

データアセットは異なるプロジェクトに存在できます。使用可能なプロジェクトとそのアセット名の概要は次のとおりです。

BigQuery ストレージ プロジェクト

このプロジェクトには、BigQuery データアセットが保存されます。アセットの詳細で、Table ID の一部として最初のドットの前に表示されます。

BigQuery UI では、ストレージ プロジェクト名が、完全修飾されたテーブル名の最初のドットの前に [Table ID] フィールドに表示されます。
図 1. BigQuery ストレージ プロジェクトの名前。

コンピューティング プロジェクト

このプロジェクトには、データリネージのメタデータが保存されます。BigQuery の場合、ここでジョブを実行します。Google Cloud コンソールを使用してジョブを実行する場合は、プロジェクト セレクタでコンピューティング プロジェクト名を確認できます。

BigQuery UI で、SQL クエリを実行するページに docs-compute というコンピューティング プロジェクトが表示されています。
図 2. BigQuery ジョブを実行するコンピューティング プロジェクトの名前。

BigQuery API にリクエストを送信する場合は、URL にコンピューティング プロジェクトを指定します。次に例を示します。

POST /bigquery/v2/projects/docs-compute/jobs HTTP/1.1
Host: bigquery.googleapis.com
User-Agent: Go-http-client/1.1
Authorization: <REDACTED 1031 BYTES>
Accept-Encoding: gzip
{
  "configuration": {
    "query": {
      "useLegacySql": false,
      "query": "CREATE OR REPLACE TABLE `docs-target.dataset.target-002` AS SELECT * FROM `docs-source.dataset.source-002`;"
    }
  },
  "jobReference": {
    "projectId": "docs-compute",
    "jobId": "docs-compute-job-id",
    "location": "us",
  }
}

アクティブなプロジェクト

これは、データリネージを表示しているプロジェクトです。Google Cloud コンソールで、アクティブなプロジェクトがプロジェクト セレクタに表示されます。API を使用している場合、アクティブなプロジェクトは API 呼び出しを行っているプロジェクトです。

BigQuery UI で、docs-source というプロジェクトにある source-001 というデータセットのデータリネージが表示されています。
図 3. Google Cloud コンソールでアクティブなプロジェクト。

BigQuery データリネージが表示されない

BigQuery ジョブの実行後に次の問題が発生します。この場合、次の 3 つのシナリオが考えられます。

「権限がないためリネージを取得できませんでした。」というメッセージが表示された場合は、アクティブなプロジェクトに対する権限がありません。そうでない場合は、コンピューティング プロジェクトに対する権限がありません。

空のリネージグラフ。
図 4. BigQuery UI にリネージが表示されない例。

この問題を解決するには、まずコンピューティング プロジェクトで Data Lineage API が有効になっていることを確認します。API を有効にしてから、データリネージを確認するためにジョブを実行する必要があります。処理されるデータの量と複雑さに応じて、データリネージが表示されるまでに 30 分から最大 24 時間かかることがあります。

次に、アクティブなプロジェクトで Data Lineage API が有効になっていることを確認します。

Data Lineage API が有効になったら、アクティブなプロジェクトとコンピューティング プロジェクトの両方でデータリネージ閲覧者のロール（roles/datalineage.viewer）を付与します。

BigQuery プロセスのメタデータが表示されない

次の問題は、テーブルの詳細ウィンドウを開いたときに、SQL ステートメントや Process type プロパティなどのすべての詳細が表示されない場合に発生します。これは、データリネージが正しく表示されている場合でも発生します。

これは、コンピューティング プロジェクトのメタデータを表示する権限がない場合に発生します。

例:

BigQuery プロセスの詳細をクリックすると、 Google Cloud コンソールに次のメッセージが表示されます。

You don't have permission to view BigQuery process metadata in project X.
BigQuery UI の場合、[Lineage] タブの [Details] ペインにエラー メッセージが表示されます。
図 5. BigQuery UI に BigQuery プロセスの詳細が表示されない例。

この問題を解決するには、コンピューティング プロジェクトでユーザーに bigquery.jobs.get 権限（BigQuery リソース閲覧者ロールに含まれる権限など）を付与します。

BigQuery テーブルの詳細が表示されない

次の問題は、テーブルの詳細ペインを開いたときに発生し、Fully qualified name プロパティのみが表示されます。これは、データリネージが正しく表示されている場合でも発生します。これは、テーブルのストレージ プロジェクトで必要な権限をすべて持っていない場合に発生することがあります。

例:

この場合、BigQuery ノードの詳細をクリックすると、メッセージ Entry with this fully qualified name is not available in Knowledge Catalog or you do not have permissions to view it が表示されます。

BigQuery テーブルの詳細が表示されません。
図 6. BigQuery UI に BigQuery テーブルの詳細が表示されない例。

この問題を解決するには、ストレージ プロジェクトで bigquery.tables.get 権限（BigQuery データ閲覧者のロールに含まれる権限など）を付与します。

列レベルのリネージに「選択する列がありません」と表示される

Google Cloud コンソールでアセットを表示すると、テーブルレベルのリネージグラフは正しく表示されますが、列レベルのリネージを選択すると、「選択する列がありません」というメッセージが表示されるか、列間のリンクが表示されません。

この問題は、次のような状況で発生する可能性があります。

  • カスタム OpenLineage イベント: Data Lineage API ProcessOpenLineageRunEvent エンドポイントを介して取り込まれたイベントは、テーブルレベルのリネージのみをサポートします。カスタム列レベルのファセットはGoogle Cloud コンソールに表示されません。
  • サポートされていないデータソースまたはシステム: 列レベルのリネージグラフは、BigQuery SQL 変換と Managed Service for Apache Spark ジョブに対してのみ生成されます。他の統合システム（Cloud Data Fusion や Vertex AI など）は、テーブルレベルのリネージのみをサポートしています。
  • サポートされていない BigQuery サービスの種類: 列レベルのリネージは、BigQuery の読み込みジョブ、コピージョブ、ルーティンでは収集されません。
  • 外部テーブル: 外部テーブルの上流の列レベルの系統は収集されません。
  • 非構造化アセットまたはストレージ レベルのアセット: ファイルベースのアセット（未加工の Cloud Storage ファイルやバケットなど）は通常、構造化されていませんが、列レベルのリネージがシステムに報告されると、データリネージに列が表示されます。ファイル アセットの列レベルのリネージが報告されていない場合、列を選択することはできません。
  • 複雑なネストされた型: 列レベルの系統は、最上位の列のみを追跡します。複雑なデータ型（STRUCT や JSON など）内にネストされたフィールドを個別に選択することはできません。
  • パーティショニング疑似列: システム パーティショニング列（_PARTITIONDATE や _PARTITIONTIME など）は、列レベルのリネージグラフで認識されません。
  • リンクの上限を超えた場合: 変換ジョブで 1,500 個を超える列レベルのリンクが生成された場合、Knowledge Catalog は列レベルのリネージの収集をスキップし、テーブルレベルのリネージのみを保持します。
  • 組織間のアセット: リネージパスが別の組織にあるアセットを走査する場合、アセットと同じ組織に属していないと、スキーマと列の詳細にアクセスできません。

Knowledge Catalog プレミアム処理の予期しない料金

料金の発生を停止するために Dataplex API（dataplex.googleapis.com）を無効にしましたが、「Knowledge Catalog Premium Processing」SKU の料金が毎日発生しています。

この問題は、Data Lineage API（datalineage.googleapis.com）が有効なままになっている場合に発生することがあります。Data Lineage API は「Knowledge Catalog Premium Processing」SKU で課金されますが、 Google Cloud コンソールでは別の API として管理されます。Dataplex API を無効にしても、Data Lineage API は無効にならず、課金も停止されません。

データリネージが課金の原因かどうかを特定するには、Cloud Billing レポートで、ラベル goog-dataplex-workload-type の値が LINEAGE であることを確認します。

課金を停止するには、プロジェクトで Data Lineage API を無効にしてデータリネージをオフにします。