技能介绍

要解决什么问题

在 ODPS、MaxCompute 或 Hive 上跑大型分层数仓时，表与表之间的依赖往往散落在成百上千个 .sql 脚本里。改一张中间表、下线一个分区任务，或排查「这张报表从哪张源表来」时，人工翻脚本成本很高；Graphify 等工具若只解析 DDL，INSERT/SELECT 里的表引用也不会进血缘图。

本技能面向表级血缘：扫描项目目录、解析 SQL，产出可查询的 graph.json，并支持向上溯源、向下影响分析和分层概览。

如何工作

所有能力通过统一 CLI（scripts/cli.py）暴露，典型流程如下：

安装依赖：sql_lineage_install 拉齐 sqlglot、graphify、tree-sitter-sql 等解析栈。
提取血缘：sql_lineage_extract 指定 project_dir，默认 hive 方言（适配 ODPS 常见写法）；可用 --merge-graphify 与 Graphify 已有 graph.json 合并边；tmp_、mid_、z_ 等临时表前缀默认跳过。
查询与分析：

- sql_lineage_upstream / sql_lineage_downstream：从指定表追溯上游源表或下游终端表，可设 --max-depth。
- sql_lineage_deps：只看一级直接上下游。
- sql_lineage_layers、sql_lineage_stats：各层表数量、层间关系，以及源头表、终端表统计。

工作流文档里还描述了环形依赖检测：遍历 WRITES_TO 边，用 DFS 发现循环引用。分区变量如 ${bizdate} 会在解析前替换为占位符，减少语法报错。

适用边界

字段级血缘不在范围内；需要列级溯源应配合 DataHub、Amundsen 等治理工具。
SQLGlot 以 hive 方言解析 ODPS SQL，LATERAL VIEW、TRANS_ARRAY 等极少数特有语法可能不完整，但 INSERT/SELECT/FROM/JOIN 的核心表引用通常可用。
若项目已用 Graphify，建议先 graphify extract --no-cluster 再 extract --merge-graphify，因为 Graphify 的 SQL 解析器主要处理 DDL，不覆盖 INSERT/SELECT 中的表引用。
命令需在技能根目录（SKILL.md 所在目录）执行，以便正确找到 scripts/cli.py。