排解 Knowledge Catalog 資料探索問題

Knowledge Catalog (舊稱 Dataplex Universal Catalog) 資料探索功能 (也稱為獨立探索) 可自動掃描 Cloud Storage bucket,擷取中繼資料並將資料表發布至 BigQuery。您可以排解並解決常見的探索掃描錯誤,例如 BigQuery 和 BigLake 資料表發布失敗、資料夾結構定義不符,以及結構定義變更後資料表未更新。詳情請參閱「探索 Cloud Storage 資料並建立目錄」。

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

無法發布 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 資料表,請使用 Storage 物件檢視者 (roles/storage.objectViewer) 或 Dataplex Discovery 服務代理 (roles/dataplex.discoveryServiceAgent) 角色,確認 BigQuery 連線服務帳戶具備 Cloud Storage bucket 的讀取權限。
  • 檢查連線和資料集位置:確認 BigQuery 連線和 BigQuery 資料集位於相同區域,且與 Cloud Storage bucket 的位置相容。
  • 查看記錄檔瞭解詳情:在 Cloud Logging 中查看 DataScan 工作記錄。如果錯誤包含 BigQuery: Permission denied,請檢查服務帳戶權限。如果包含 TABLE_CONFIG,請確認資料檔案符合 BigQuery 規定。

大型 Cloud Storage bucket 無法建立 BigLake 資料表

探索掃描作業處理含有大量資料或大型個別檔案 (例如大於 30 MB 的 Avro 檔案) 的 Cloud Storage bucket 時,可以成功建立 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. 如要讓探索掃描作業繼續管理及更新結構定義, 請依序點選「Edit」>「Edit details」,將值變更為 discovery_managed,然後按一下「Save」。