排解 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.iam.gserviceaccount.com 具有 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 bucket 無法建立 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 資料夾包含不相容的結構定義或不同格式的檔案，就會發生這個問題。只有當檔案位於相同資料夾且具有相容的結構定義時，探索掃描作業才會將檔案分組到單一資料表中。

資料探索掃描作業分析 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 類型。
  • 缺少預設值：在較新的檔案中新增或刪除欄位時，未在結構定義中指定預設值，導致結構定義無法正確演變。
  • 檔案格式損毀：一或多個檔案格式錯誤或損毀，導致掃描作業無法讀取及擷取結構定義。

如要解決這個問題，請檢查檔案結構和結構定義：

  • 依結構定義和格式整理檔案： 確認單一資料夾中的所有檔案共用相同的格式和結構定義結構。將具有不同欄、原始型別或格式的檔案移至不同的資料夾或前置字串，以便註冊為個別資料表。
  • 使用一致的分區定義： 確保所有分區資料夾的分區鍵和結構一致 (例如一律使用 Year=YYYY/Month=MM/)。
  • 遵守結構定義演進規則： 更新結構定義 (例如在 Avro 檔案中新增或移除欄位) 時，請務必定義預設值，讓探索服務順利合併結構定義變體。
  • 找出損毀的檔案： 檢查掃描輸出內容或記錄，找出無法解碼的檔案。暫時移動檔案，找出導致掃描失敗的特定檔案。

系統不會根據結構定義變更更新探索到的資料表

修改 Cloud Storage 中的檔案或執行新的掃描作業後，發布的 BigQuery 資料表不會反映更新後的結構定義。

如果發布的資料表將 metadata-managed-mode 標籤設為 user_managed，就會發生這個問題。根據預設，探索會將資料表發布為 discovery_managed。如果您或其他使用者手動編輯資料表結構定義屬性，請務必將標籤變更為 user_managed，以封鎖自動更新。

如要解決這個問題，請檢查 BigQuery 中的資料表標籤：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。
  2. 在「Explorer」窗格中展開專案，選取資料集，然後按一下受影響的資料表。
  3. 點按「Details」(詳細資料) 分頁標籤。
  4. 在「Labels」(標籤) 部分，檢查 metadata-managed-mode 鍵的值。

  5. 如要讓探索掃描作業繼續管理及更新結構定義，請按一下「編輯詳細資料」，然後將值變更為 discovery_managed。

取得支援

如果需要協助解決本文未提及的問題，請與 Cloud Customer Care 聯絡。