datalineage-bigquery-asset-impact-analysis

BigQuery 资产影响分析

当有人报告 BigQuery 表或视图已损坏、数据过期或缺失，或者用户正在计划维护并希望了解修改资产或暂停其更新会造成什么后果时，本技能会指导 Agent 进行下游影响分析（影响范围评估）。

本技能主要依靠 Google Cloud 上的 数据沿袭（Knowledge Catalog）MCP 服务来发现资产之间的关系。

致谢

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归因。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中执行），在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:datalineage-bigquery-asset-impact-analysis)"，并在 User-Agent 请求头中追加 agent-skills/1.0 (skill:datalineage-bigquery-asset-impact-analysis)。

前置条件

本技能需要访问 Google Cloud 上的数据沿袭 API，并且需要与 Data Lineage MCP Server 建立有效的客户端连接。有关连接配置和工具架构的详细信息，请参阅 MCP 用法。

分析工作流

1. 确定资产的完全限定名称（FQN）

• 确保 BigQuery 资产采用正确的 FQN 格式：
  • 格式： bigquery:{project_id}.{dataset_id}.{table_or_view_id}
  • 示例： bigquery:my-prod-project.analytics.orders

2. 确定位置和父级路径

确定要搜索的位置，并构造 Data Lineage API 请求：

• 发现资产位置：运行命令 bq show --format=json {project_id}:{dataset_id}，并提取 location 字段（例如， us-central1 或 us）。如果由于权限不足或缺少工具而无法发现位置，请提示用户提供数据集的位置。
• 设置父级路径：使用项目 ID 和 MCP 服务的位置设置 parent 路径。请查看 DataLineageServer 工具定义，确定配置的区域或位置（例如，us）。格式为： projects/{project_id}/locations/{mcp_server_location}。
• 配置搜索范围：在请求负载的 locations 数组中加入发现的资产位置（例如，["us-central1"] 或 ["us", "us-central1"]）。

3. 检索下游沿袭图

调用 DataLineageServer:search_lineage 工具，获取下游关系。

• 方向：设为 DOWNSTREAM。
• 搜索参数：使用 max_depth = 10 和 max_process_per_link = 5 作为稳健的默认值。

4. 确定影响范围

遍历返回的沿袭链接，构建影响图：

• 受影响资产：每个链接的 target 都表示依赖于源资产的下游资产。
• 转换流程：检查每个链接上的 processes 字段。该字段可用于识别传播数据的 ETL 流水线、BigQuery 视图或预定查询。
• 直接与间接影响：
  • 直接影响（深度 1）：直接使用源资产的资产。如果链接的 dependency_type: EXACT_COPY，则将目标标记为“直接过期／相同副本”。
  • 间接影响（深度 > 1）：数据流中更下游的资产，这些资产会受到级联数据过期或故障的影响。

5. 汇总并整理输出

使用以下结构向用户清晰地呈现调查结果：

1. 执行摘要：说明受影响的下游资产总数 以及影响的最大深度。

2. 关键路径：突出显示高优先级下游资产（例如，名称中包含 "prod"、"dashboard"、"reporting" 或 "master" 的资产）。

3. 影响范围表：使用简洁的 Markdown 表格列出依赖项。你必须包含所有列：

   下游资产	转换流程	深度	影响类型
   bigquery:project.dataset.table	projects/p/locations/l/processes/proc	1	直接
   bigquery:project.dataset.view	projects/p/locations/l/processes/view	2	间接

4. 分析元数据：透明说明搜索的参数和边界，让用户可以选择扩大搜索范围：

   • 已搜索位置：{list_of_locations_queried}
   • 父级位置：{parent_path}
   • 深度限制：{max_depth}
   • 每个链接的流程数限制：{max_process_per_link}
   • 给用户的提示：告知用户可以要求使用更大的搜索位置范围或更深的深度限制 重新运行分析。

关键约束与防护措施

1. 正确解读空响应：
   • 如果血缘响应为空，应立即假定所查询位置中不存在依赖项，并向用户报告。
2. 严格禁止绕过：
   • 只能使用 DataLineageServer:search_lineage 工具检索下游关系。
3. 先验证资产是否存在：
   • 如果 bq show 表明源表不存在，应停止操作并直接向用户报告。除非用户明确要求，否则不要尝试猜测其他表名。
4. 不得简化输出或虚构产物：
   • 在最终回复中直接提供完整的下游影响范围表。除非已明确执行文件写入工具创建文件，否则不要告知用户你已创建包含详情的单独 Markdown 文件或其他产物。

参考目录

• MCP 用法：在 Google Cloud 上使用数据血缘远程 MCP 服务和工具偏好设置。

外部文档

• 知识目录数据血缘文档
• 使用数据血缘 MCP 服务
• 知识目录数据血缘 API 参考