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

Knowledge Catalog(旧称 Dataplex Universal Catalog)のデータ検出(スタンドアロン検出とも呼ばれます)を使用すると、Cloud Storage バケットを自動的にスキャンしてメタデータを抽出し、BigQuery にテーブルを公開できます。BigQuery テーブルと BigLake テーブルの公開エラー、フォルダ スキーマの不一致、スキーマ変更後に更新されないテーブルなど、一般的な検出スキャンエラーのトラブルシューティングと解決を行うことができます。詳細については、Cloud Storage データを検出してカタログ化するをご覧ください。

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

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

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

検出スキャンで、大量のデータまたは大きな個々のファイル(30 MB を超える Avro ファイルなど)を含む Cloud Storage バケットを処理すると、スキャンで 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): パーティション キーが一致していないか、存在しません。たとえば、1 つのパスで 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 に変更して、[保存] をクリックします。