基于项目 SQL 证据的动态节点搜索与分层数据血缘治理方法

状态：方法论说明。本文总结当前 SQLGlot 项目的实现路径、治理原则，以及与数据溯源研究和行业框架的对应关系；不构成生产执行、运行时血缘或业务口径确认。

一句话定义

基于项目 SQL 证据的动态节点搜索与分层数据血缘治理方法，是指在一个已冻结的项目 SQL 快照中，以待分析目标为起点，自动搜索可关联的 Dataset Node、writer 和上游依赖路径；再在已证实的节点路径和 SQL scope 内执行字段级 DFS。对无法从项目 SQL 证据唯一证明的关系，系统保留歧义证据，并通过人工审核把技术推断转化为可审计的治理结论。

它的目标不是不计代价地补全血缘，而是保证每一条已发布结论都可回到确定的 SQL、表达式、位置和审核决定；不能证明的部分必须明确说明边界。

方法主链

冻结项目 SQL 快照与哈希
  -> SQL AST / statement / scope 解析
  -> 数据集合（Dataset）抽象与节点分类
  -> 项目范围内的 Dataset Node 依赖图与 writer 候选搜索
  -> 从目标节点动态搜索上游节点与路径
  -> 在已证实节点路径中执行字段级 DFS
  -> 分离交付 VALUE 血缘、控制证据、来源分类和业务解释
  -> 人工审核、版本化和可重复生成

这里的“动态”指目标驱动的项目内搜索与遍历：分析器在冻结的项目 SQL 快照中，按待分析目标自动定位节点、搜索可达 writer 和上游边，再展开字段路径。它不表示读取生产运行事件、执行动态 SQL，或把某次运行中的真实数据贡献当作已证明事实。

第一层：项目 SQL 解析与数据集合抽象

首先处理的不是字段，而是冻结项目 SQL 快照中可作为输入、中间结果或输出的数据集合（Dataset）。解析过程以 statement 和 SQLGlot scope 为边界，识别实际被当前 FROM、JOIN、CTE、子查询或集合运算引用的集合。

数据集合的典型来源包括：

• 物理表或已知写入目标；
• 本地 SQL 输入中没有 writer 的外部表；
• CTE；
• 派生子查询；
• SELECT 的查询结果；
• UNION 等集合运算结果。

稳定标识不能只依赖表名。同名表、跨环境逻辑表、同一文件中的多个 statement 或 scope 都可能不同，因此节点标识必须关联源 SQL、statement、scope 等可回溯证据。

第二层：Dataset Node 分类、writer 搜索与依赖图

每个数据集合被归类为 Dataset Node，并由项目 SQL 结构建立有向依赖边：读取、CTE 绑定、派生、集合分支、写入目标和命令目标等。分析器按目标在项目范围内搜索可关联节点和 writer 候选；此时形成的是数据集合级血缘骨架，回答的问题是：

一个目标表或逻辑数据集合，依赖哪些上游数据集合，以及每一段依赖由哪段 SQL 建立？

节点图只表达被实际引用的依赖，不能把“在 scope 中可见但没有被当前语句使用”的 CTE 误记为输入。跨文件逻辑表 writer 的绑定也必须独立为人工可编辑的审核决定：自动发现候选可以提高效率，但程序不得覆盖人工 REJECTED 决定。

第三层：目标驱动的节点搜索与 DFS

在有了 Dataset Node 图后，分析器从一个目标节点沿上游边动态搜索并做 DFS。这一步负责处理整体结构，而非字段语义：

• CTE、派生查询和嵌套 scope 的展开；
• UNION 等集合运算分支；
• 跨文件 writer 绑定；
• 外部数据集合终点；
• 循环和无法解析结构的终止与诊断。

节点搜索与 DFS 的输出是一个受项目 SQL 结构约束的上游路径集合。它先限定“值可能经过哪些数据集合”，为字段追踪提供合法上下文；字段 DFS 不应脱离这层图直接在全部 SQL 中按同名字段搜索。

第四层：字段级 DFS

字段 DFS 以 (root_node_id, field_name) 为起点。它在当前节点中找到字段的实际投影表达式，提取表达式引用的输入字段，再只沿节点级 DFS 已证明的输入边向上递归。

每次访问都记录唯一的 tree_id + visit_id、父访问、表达式、输入字段、节点边、源文件、statement、scope 和 SQL 位置。因此，同名字段即使经不同的边或分支进入，也不会在审计中混淆。

字段级 DFS 需要保守处理下列 SQL 结构：

• SELECT *：只有字段投影证据能唯一定位来源时才透传；
• 未限定列：多输入 scope 中无法唯一绑定时保留全部候选；
• UNION：先应用外层投影表达式，再进入集合分支；
• 动态环境关系：没有本地 writer 时作为带动态标记的外部终点；
• cycle、缺字段或不可枚举投影：以明确 terminal 原因停止。

AMBIGUOUS_STAR_SOURCES 和 AMBIGUOUS_COLUMN_SOURCES 是诊断证据，不是已确认的 VALUE 来源。它们的作用是完整表达“静态分析不能证明什么”，而不是制造一个看似完整但不可审计的单一路径。

治理控制：从技术血缘到可用结论

1. 证据优先与可复现

输入 SQL、审核表、解析器版本、生成器版本和产物哈希共同构成一次分析的证据链。任何结果都应能定位到源文件、SQL 行范围和生成规则；人工修改 writer 审核表后，必须从节点图开始重建后续字段图。

2. VALUE、控制条件和业务结论分离

字段值的来源与数据适用条件不是同一个概念，应分别保存和交付：

• VALUE 血缘：字段值的上游字段、常量、表达式和加工路径；
• 语义控制证据：CASE/IF 条件、可证明的 inner join 条件，以及 WHERE/HAVING/QUALIFY 的行资格条件；
• 来源分类：仅根据已确认的 VALUE 终点系统映射得出 S1--S4，不把控制条件、表名模式或业务常识伪装为来源证据；
• 业务说明：基于冻结的技术证据解释字段形成规则和边界，不能由模板或模型补猜业务事实。

3. 人在回路中的决定权

自动化负责解析、发现候选、保存证据和重复验证；人负责确认跨环境 writer、源系统归属、业务含义和生产事实。审核结果应有状态、备注、责任归属和生效时点，并与生成产物关联。

4. 分层交付

同一证据链应面向不同读者提供不同粒度的产物：

• 节点、边、字段树和 JSONL 明细：程序、审计和技术排障；
• 字段来源和分类 CSV：数据 Owner、数据治理和变更影响分析；
• 业务 Markdown：业务人员阅读的形成规则、适用条件、关联规则和原 SQL 位置。

研究与行业定位

这不是一项孤立的 SQL 解析技巧，而是将三类成熟思想组合成适合数据治理的落地方法：

1. 数据库领域的 Data Provenance / Data Lineage：用转换与派生关系解释数据从何而来、如何形成；
2. SQL AST 与列级血缘工程：在 SQL scope、投影表达式和输入绑定中提取确定的依赖；
3. 数据治理框架：将技术证据接入责任、审核、影响分析、质量和合规控制。

最直接的学术对应是数据溯源。Cui 与 Widom 的 Lineage Tracing for General Data Warehouse Transformations 研究如何在一般数据仓库转换图中追溯数据到原始输入，并给出在线性和一般无环转换图中的追踪算法。它与“先抽象数据集合、构建节点图、再 DFS”的路径高度同构；区别是该研究更偏元组级、运行时或通用转换，本项目则以 SQL 源码的静态字段级分析为主。论文原文

另一条理论基础是 why / where / how provenance：where 说明结果字段或值来自哪里，why 说明哪些输入共同导致了结果，how 说明经过了怎样的加工组合。字段 DFS 以静态 SQL 为证据，覆盖字段来源和表达式加工；CASE、UNION、函数、常量和确定的输入字段分支均构成可审计的 how 解释。综述：Provenance in Databases: Why, How, and Where；早期理论：Why and Where: A Characterization of Data Provenance。

在工程实现上，近年的 LINEAGEX 同样通过遍历 SQL 解析树提取列级血缘、处理歧义并用于数据质量排查。本项目的额外治理设计是先从项目 SQL 快照形成稳定的 Dataset Node 图，再以目标为起点自动搜索可达节点、writer 和上游路径，并在既有节点关系和 scope 约束内执行字段 DFS，而不是仅从孤立 SQL 直接抽取列依赖。

W3C PROV 是最值得借鉴的跨系统语义模型：Dataset Node 可映射为 Entity，SQL statement、scope 或 ETL 步骤可映射为 Activity，writer 审核人、数据 Owner 和生成器可映射为 Agent。将这三类对象和 used、generated、derived、associated 关系补充到现有模型，可使技术血缘进一步支持跨系统交换、责任归属和审计表达。PROV-DM / PROV-O

OpenLineage 与本方法相似但不相同：它以运行期 Job、Run、Dataset 事件为核心，记录实际执行的输入、输出、版本和状态；本方法以设计期的项目 SQL 快照为证据，在项目范围内动态搜索节点和路径，解释 CTE、表达式、字段映射和潜在歧义。两者应互补使用：项目节点图与字段图解释设计，运行事件核验实际执行。OpenLineage Specification

DAMA-DMBOK 和 EDM Council DCAM 不规定 DFS 算法，却定义了这项能力进入数据治理体系的原因与组织方式，包括元数据、数据架构、质量、控制环境、责任机制、变更影响和审计。因此，SQLGlot 方法是技术血缘能力底座，DAMA/DCAM 是组织管理、使用和衡量该能力的框架。DAMA-DMBOK / EDM Council DCAM

本方法的治理特色不在于单纯使用 DFS，而在于以下四项原则：

1. 先集合、后字段，控制复杂度；
2. 先证据、后结论，不以猜测补全血缘；
3. 自动发现与人工批准分离，保留责任边界；
4. 技术明细、分类结果与业务解释分层交付。

与论文、标准和行业框架的关系

适用边界

本方法能够证明的是冻结项目 SQL 快照所支持的依赖与加工证据，而不是所有业务事实。项目内节点搜索是动态的，但证据范围仍受该快照约束；下列内容需要独立治理或运行期验证：

• 参数、分区和运行条件下实际读取的行与实际贡献比例；
• 存储过程、UDF、动态 SQL、外部任务或未采集脚本内部的逻辑；
• 来源系统、数据 Owner、指标口径和字段业务含义；
• S4 等多系统来源是否在某次生产运行中同时实际贡献；
• 数据质量、权限、敏感数据分级和访问合规结论。

因此，基于项目 SQL 证据的动态节点搜索血缘应被视为数据治理的可审计技术底座，而非替代生产观测、数据责任制或人工业务确认的单一真相源。

建议的正式表述

建议对外使用以下定义：

本项目采用基于项目 SQL 证据的动态节点搜索与分层数据血缘治理方法：先冻结项目 SQL 快照，将其中的物理表、外部表、CTE、派生查询和集合运算结果抽象为可追溯的数据集合节点，构建集合级依赖图；再从目标节点自动搜索项目内可达的 writer、节点和上游路径，并在该路径和 SQL scope 的约束下执行字段级 DFS。系统对无法从项目 SQL 证据唯一证明的关系保留歧义和终止证据，对关键逻辑表绑定和业务归属保留人工审核门，从而把项目 SQL 分析结果转化为可重复、可追溯、可审计的数据治理交付。