排查 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 Publishing Service Agent (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 表失败

当发现扫描处理包含大量数据或大型单个文件（例如，大于 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。

获取支持

如果您需要帮助解决本文档中未提及的问题， 请与 Cloud Customer Care 联系。