datalineage-bigquery-asset-impact-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BigQuery Asset Impact Analysis

BigQuery资产影响分析

This skill guides the agent in performing a downstream impact analysis (blast radius assessment) when a BigQuery table or view is reported as broken, stale, missing, or when a user is planning maintenance and wants to know the consequences of modifying or pausing updates to an asset.

It relies primarily on the Google Cloud Data Lineage (Knowledge Catalog) MCP Server to discover relationships between assets.

本技能指导Agent在BigQuery表或视图被报告损坏、过时、丢失，或者用户计划进行维护并想了解修改或暂停资产更新的后果时，执行下游影响分析（blast radius评估）。

它主要依赖Google Cloud Data Lineage (Knowledge Catalog) MCP Server来发现资产之间的关系。

Prerequisites

前置条件

This skill requires access to the Google Cloud Data Lineage API and an active client connection to the Data Lineage MCP Server. For detailed connection configurations and tool schemas, refer to MCP Usage.

本技能需要能够访问Google Cloud Data Lineage API，并且与Data Lineage MCP Server保持活跃的客户端连接。有关详细的连接配置和工具架构，请参考MCP使用说明。

Analysis Workflow

分析流程

1. Resolve the Asset's Fully Qualified Name (FQN)

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

Ensure you have the correct FQN format for the BigQuery asset:

Format:

bigquery:{project_id}.{dataset_id}.{table_or_view_id}

Example:

bigquery:my-prod-project.analytics.orders

确保你拥有BigQuery资产的正确FQN格式：

格式：

bigquery:{project_id}.{dataset_id}.{table_or_view_id}

示例：

bigquery:my-prod-project.analytics.orders

2. Determine Locations and Parent Path

2. 确定位置和父路径

Identify the locations to search and construct the Data Lineage API request:

Discover Asset Location: Run the command
```
bq show --format=json {project_id}:{dataset_id}
```
and extract the
```
location
```
field (e.g.,
```
us-central1
```
or
```
us
```
). If location discovery fails due to permissions or missing tools, prompt the user for the dataset's location.
Set Parent Path: Set the
```
parent
```
path using the project ID and the MCP server's location. Consult the
```
DataLineageServer
```
tool definition to find the configured region or location (e.g.,
```
us
```
). The format is:
```
projects/{project_id}/locations/{mcp_server_location}
```
.
Configure Search Scope: Include the discovered asset location in the
```
locations
```
array of the payload (e.g.,
```
["us-central1"]
```
or
```
["us", "us-central1"]
```
).

识别要搜索的位置并构建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. Retrieve the Downstream Lineage Graph

3. 获取下游血缘图谱

Call the

DataLineageServer:search_lineage

tool to fetch downstream relationships.

Direction: Set to
```
DOWNSTREAM
```
.
Search Parameters: Use
```
max_depth = 10
```
and
```
max_process_per_link = 5
```
as robust defaults.

调用

DataLineageServer:search_lineage

工具获取下游关系。

方向：设置为
```
DOWNSTREAM
```
。
搜索参数：使用
```
max_depth = 10
```
和
```
max_process_per_link = 5
```
作为可靠的默认值。

4. Identify the Blast Radius

4. 确定影响范围（Blast Radius）

Traverse the returned lineage links to build the impact graph:

Affected Assets: The
```
target
```
of each link represents a downstream asset that depends on your source asset.
Transform Processes: Inspect the
```
processes
```
field on each link. This identifies the ETL pipelines, BigQuery Views, or Scheduled Queries that propagate the data.
Direct vs. Indirect Impact:
- Direct Impact (Depth 1): Assets directly consuming the source asset. If a link has
```
dependency_type: EXACT_COPY
```
  , mark the target as "Directly Stale / Identical Copy".
- Indirect Impact (Depth > 1): Assets further down the stream that will experience cascading stale data or failures.

遍历返回的血缘链接以构建影响图谱：

受影响资产：每个链接的
```
target
```
代表依赖源资产的下游资产。
转换流程：检查每个链接的
```
processes
```
字段。这会识别传播数据的ETL管道、BigQuery视图或计划查询。
直接影响 vs 间接影响：
- 直接影响（层级1）：直接消费源资产的资产。如果链接的
```
dependency_type: EXACT_COPY
```
  ，则将目标标记为“直接过时/完全副本”。
- 间接影响（层级>1）：下游更深处的资产，会出现级联的过时数据或故障。

5. Summarize and Format the Output

5. 总结并格式化输出

Present your findings clearly to the user using the following structure:

Executive Summary: State the total number of downstream assets affected and the maximum depth of the impact.
Critical Path: Highlight high-priority downstream assets (e.g., assets containing "prod", "dashboard", "reporting", or "master" in their names).
Blast Radius Table: A clean Markdown table listing the dependencies. You MUST include all columns:
Downstream Asset Transform Process Depth Impact Type
bigquery:project.dataset.table
projects/p/locations/l/processes/proc
1 Direct
bigquery:project.dataset.view
projects/p/locations/l/processes/view
2 Indirect
Analysis Metadata: Provide transparency on the parameters and boundaries of your search so the user can choose to expand them:
- Locations Searched:
```
{list_of_locations_queried}
```
- Parent Location:
```
{parent_path}
```
- Depth Limit:
```
{max_depth}
```
- Process per Link Limit:
```
{max_process_per_link}
```
- Tip for User: Let the user know they can request to rerun the analysis with expanded locations or larger depth limits.

Downstream Asset	Transform Process	Depth	Impact Type
`bigquery:project.dataset.table`	`projects/p/locations/l/processes/proc`	1	Direct
`bigquery:project.dataset.view`	`projects/p/locations/l/processes/view`	2	Indirect

使用以下结构向用户清晰呈现你的发现：

执行摘要：说明受影响的下游资产总数以及影响的最大层级。
关键路径：突出显示高优先级的下游资产（例如名称中包含“prod”、“dashboard”、“reporting”或“master”的资产）。
影响范围表格：一个简洁的Markdown表格列出依赖项。你必须包含所有列：
下游资产转换流程层级影响类型
bigquery:project.dataset.table
projects/p/locations/l/processes/proc
1 直接
bigquery:project.dataset.view
projects/p/locations/l/processes/view
2 间接
分析元数据：提供搜索的参数和边界，以便用户选择扩展范围：
- 搜索的位置：
```
{查询的位置列表}
```
- 父位置：
```
{父路径}
```
- 层级限制：
```
{max_depth}
```
- 每个链接的流程限制：
```
{max_process_per_link}
```
- 用户提示：告知用户他们可以请求使用扩展的位置或更大的层级限制重新运行分析。

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

Crucial Constraints & Guardrails

关键约束与规则

Interpret Empty Responses Correctly:
- If the lineage response is empty, immediately assume that no dependencies exist in the queried locations and report this to the user.
Strictly Banned Bypasses:
- Exclusively retrieve downstream relationships using the
```
DataLineageServer:search_lineage
```
  tool.
Verify Asset Existence First:
- If
```
bq show
```
  indicates the source table does not exist, stop and report this directly to the user. Do not attempt to guess alternative table names unless the user explicitly instructs you to do so.
No Output Shortcutting or Hallucinated Artifacts:
- Present the complete downstream blast radius table directly in your final response. Avoid telling the user you have created a separate Markdown file or artifact containing the details unless you have explicitly executed file-writing tools to create it.

正确解读空响应：
- 如果血缘响应为空，立即假设在查询的位置中不存在依赖项，并向用户报告这一点。
严格禁止绕过：
- 仅使用
```
DataLineageServer:search_lineage
```
  工具获取下游关系。
先验证资产存在性：
- 如果
```
bq show
```
  表明源表不存在，请停止操作并直接向用户报告。除非用户明确指示，否则不要尝试猜测替代表名。
禁止输出捷径或虚构内容：
- 在最终响应中直接呈现完整的下游影响范围表格。除非你明确执行了文件写入工具创建了单独的Markdown文件或工件，否则不要告知用户你已创建包含详细信息的此类文件。

Reference Directory

参考目录

MCP Usage: Using the Google Cloud Data Lineage remote MCP server and tool preferences.

MCP使用说明：使用Google Cloud Data Lineage远程MCP服务器和工具偏好设置。