Knowledge Catalog のデータ検出に関する問題のトラブルシューティング

このガイドでは、テーブルの公開の失敗やスキーマの非互換性エラーなど、Knowledge Catalog のデータ検出スキャン（スタンドアロン検出とも呼ばれます）に関する一般的な問題のトラブルシューティングと解決に役立つ情報を提供します。

BigQuery テーブルの公開の失敗（FAILED_BIGQUERY_TABLE_PUBLISH）

検出スキャンを実行すると、テーブルを BigQuery に公開できないことがあります。この場合、スキャンは Cloud Logging に FAILED_BIGQUERY_TABLE_PUBLISH アクションを記録します。

この問題は、次の条件が満たされた場合に発生します。

  • IAM 権限が不足している: Knowledge Catalog サービス アカウントまたは BigQuery 接続サービス アカウントに、接続の委任、Cloud Storage へのアクセス、宛先データセットへの書き込みに必要なロールがありません。
  • BigQuery 接続またはデータセットの不一致: 指定された接続 ID が無効であるか、接続と宛先データセットが異なるリージョンにあります。
  • テーブル構成エラー: テーブルの作成または変更で、正しくない設定またはサポートされていない設定が適用されます。

この問題を解決するには、次のチェックを行います。

  • サービス アカウントのロールを確認する: Knowledge Catalog サービス アカウント service-PROJECT_NUMBER@gcp-sa-dataplex. に Dataplex Discovery BigLake 公開サービス エージェント（roles/dataplex.discoveryBigLakePublishingServiceAgent）ロールがあることを確認します。
  • 接続権限を確認する: BigLake テーブルを作成する場合は、BigQuery 接続サービス アカウントに Cloud Storage バケットへの読み取りアクセス権があることを確認します（roles/storage.objectViewer または roles/dataplex.discoveryServiceAgent を使用）。
  • 接続とデータセットのロケーションを確認する: BigQuery 接続と BigQuery データセットが同じリージョンに存在し、Cloud Storage バケットのロケーションと互換性があることを確認します。
  • ログを調べて詳細を確認する: Cloud Logging で DataScan ジョブのログを確認します。エラーに BigQuery: Permission denied が含まれている場合は、サービス アカウントの権限を確認します。TABLE_CONFIG が含まれている場合は、データファイルが BigQuery の要件に準拠していることを確認します。

大きな Cloud Storage バケットで BigLake テーブルの作成が失敗する

検出スキャンで大量のデータを含む Cloud Storage バケットや大きな個々のファイル（30 MB を超える Avro ファイルなど）を処理すると、スキャンで BigQuery データセットを正常に作成できても、BigLake テーブルの公開に失敗することがあります。

この場合、Cloud Logging に次のエラーが表示されることがあります。

  • FAILED_BIGQUERY_TABLE_PUBLISH
  • com.google.cloud.bigquery.BigQueryException: Read timed out

この問題は、既知のスケーラビリティの制限です。テーブルの即時プロビジョニングが必要な場合は、バケットデータのフィルタされた小さなサブセットを含むように検出スキャンを構成します。

Cloud Storage フォルダのスキーマの不一致

データ検出スキャンで外部テーブルを登録できないか、特定のフォルダ内のファイルが検出されない。

この問題は、Cloud Storage フォルダに互換性のないスキーマまたは異なる形式のファイルが含まれている場合に発生します。検出スキャンでは、ファイルが同じフォルダにあり、互換性のあるスキーマがある場合にのみ、ファイルが 1 つのテーブルにグループ化されます。

データ検出スキャンで Cloud Storage パスを分析する場合、フォルダ内のファイルとフォルダ間のパーティション構造が整合していることが想定されます。スキャンでは、次のいずれかが検出されるとアクションにフラグが設定されます。

  • 無効なデータ形式（INVALID_DATA_FORMAT）: 同じフォルダ内またはパーティション間でデータ形式の不整合が見つかりました（たとえば、同じディレクトリに .csv ファイルと .parquet ファイルが混在している場合）。
  • 無効なパーティション定義（INVALID_PARTITION_DEFINITION）: パーティション キーに一貫性がないか、パーティション キーがありません。たとえば、あるパスで Year=2023/Mon=Jan を使用し、別のパスで Year=2023/Dept=Sales を使用する場合があります。
  • 互換性のないデータスキーマ（INCOMPATIBLE_DATA_SCHEMA）: 同じフォルダまたはテーブル内のファイル間で、一貫性のないスキーマまたは互換性のないスキーマが検出されました。

Avro や Parquet などの厳密な型指定の形式では、スキーマの不一致は次の原因で発生します。

  • 互換性のないデータ型: あるファイルでは列の型が string で、別のファイルでは int または boolean である。
  • デフォルト値の欠落: スキーマ定義でデフォルト値を指定せずに、新しいファイルで新しいフィールドが追加または削除されるため、スキーマの正しい進化が妨げられます。
  • ファイル形式が破損している: 1 つ以上のファイルが不正な形式であるか破損しているため、スキャンでスキーマの読み取りと抽出ができません。

この問題を解決するには、ファイル構造とスキーマ定義を確認します。

  • スキーマと形式でファイルを整理する: 1 つのフォルダ内のすべてのファイルが同じ形式とスキーマ構造を共有していることを確認します。列、プリミティブ型、形式が異なるファイルは、個別のテーブルとして登録できるように、個別のフォルダまたは接頭辞に移動します。
  • 一貫したパーティション定義を使用する: すべてのパーティション フォルダでパーティション キーと構造が統一されていることを確認します（たとえば、Year=YYYY/Month=MM/ を一貫して使用します）。
  • スキーマの進化ルールに従う: スキーマを更新する（Avro ファイルのフィールドの追加や削除など）場合は、検出サービスがスキーマ バリアントを正常に統合できるように、常にデフォルト値を定義します。
  • 破損したファイルを特定する: スキャン出力またはログを調べて、特定のファイルがデコードに失敗したかどうかを確認します。特定のファイルが原因でスキャンが失敗するかどうかを確認するため、ファイルを一時的に移動します。

検出されたテーブルがスキーマの変更で更新されない

Cloud Storage でファイルを変更するか、新しいスキャンを実行しても、更新されたスキーマは公開された BigQuery テーブルに反映されません。

この問題は、公開されたテーブルの metadata-managed-mode ラベルが user_managed に設定されている場合に発生します。デフォルトでは、検出はテーブルを discovery_managed として公開します。ユーザーまたは別のユーザーがテーブル スキーマのプロパティを手動で編集する場合は、ラベルを user_managed に変更して自動更新をブロックする必要があります。

この問題を解決するには、BigQuery でテーブルラベルを確認します。

  1. Google Cloud コンソールで、[BigQuery] ページに移動します。
  2. [エクスプローラ] ペインで、プロジェクトを開き、データセットを選択して、影響を受けるテーブルをクリックします。
  3. [詳細] タブをクリックします。
  4. [ラベル] セクションで、metadata-managed-mode キーの値を確認します。

  5. 検出スキャンでスキーマの管理と更新を再開する場合は、[詳細を編集] をクリックして、値を discovery_managed に変更します。

サポートを受ける

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