排查 Knowledge Catalog 数据发现问题

Knowledge Catalog（以前称为 Dataplex Universal Catalog）数据发现（也称为独立发现）可让您自动扫描 Cloud Storage 存储桶，以提取元数据并将表发布到 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 Publishing Service Agent (roles/dataplex.discoveryBigLakePublishingServiceAgent) 角色。
  • 验证连接权限：如果您创建 BigLake 表，请验证 BigQuery 连接服务账号是否具有使用 Storage Object Viewer (roles/storage.objectViewer) 或 Dataplex Discovery Service Agent (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 文件夹包含架构不兼容或格式不同的文件，则会出现此问题。仅当文件位于同一文件夹中且具有兼容的架构时，发现扫描才会将文件分组到单个表中。

数据发现扫描在分析 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. 在探索器窗格中，展开您的项目，选择数据集，然后点击受影响的表。
  3. 点击详情标签页。
  4. 在标签部分中，检查 metadata-managed-mode 键的值。

  5. 如果您希望发现扫描继续管理和更新架构，请点击修改 > 修改详细信息，将值更改为 discovery_managed，然后点击保存。