SQLink 血缘系统管理
本指南组织元数据采集、血缘空间、解析任务、预处理、血缘编辑和运行调度。首次建设先按实施顺序准备，日常操作进入相应详细指南。
| 任务 | 详细指南 |
|---|---|
| 采集数据库、报表、DDL、API 或自定义对象 | 采集与资源同步 |
| 创建解析任务、导入文件并检查报告 | 血缘任务与解析 |
| 设置对象身份、连接映射及预处理 | 命名空间与预处理 |
| 补充有明确依据的手工关系 | 血缘编辑 |
| 管理执行周期、节点与日志 | 任务调度 |
建议实施顺序
- 梳理系统、环境、数据源和代码来源。
- 规划命名空间及默认 Schema。
- 配置元数据采集并检查采集结果。
- 将数据库、报表或 OpenLineage 资源纳入血缘空间。
- 根据代码来源创建解析任务，必要时配置预处理和连接映射。
- 执行任务并处理解析报告中的失败或缺失项。
- 对自动解析无法覆盖且有证据的关系进行受控编辑。
- 配置调度并持续检查成功率、覆盖率和链路质量。
采集管理
数据源采集
数据源采集为血缘关联提供数据库元数据。创建采集配置时选择数据源和采集范围，并根据实际需要设置采样、名称补全和黑名单。黑名单用于排除无需采集的对象，使用前应确认不会排除关键上下游。
执行后在任务列表查看进度和状态，再抽样检查数据库、Schema、表和字段是否完整。采集成功不代表所有业务对象均已覆盖。
报表采集
报表采集用于获取报表资源及其数据集等信息。保存前执行连接测试；正式采集通常由后台任务完成，应在任务记录中检查完成状态、资源数量和失败信息。
文件采集
文件采集可处理 DDL 等文件来源。配置时选择解析引擎、命名空间和默认 Schema；若文件通过 API 或外部流程提交，还需核对来源标识和元数据上下文。不同数据库语法应使用匹配的解析引擎。
自定义元模型采集
当标准采集无法表达特定对象时，可依据已配置的自定义元模型采集。采集前确认元模型的类型、属性和关系定义，采集后检查对象是否落入预期类型，避免形成无法参与分析的孤立节点。
血缘空间
血缘空间集中管理参与血缘分析的资源，主要包括以下部分：
| 区域 | 管理内容 | 核对重点 |
|---|---|---|
| 血缘管理 | 已解析关系及其状态 | 对象身份、方向、层级和解析结果 |
| 数据库资源 | 已采集的数据库元数据 | 命名空间、Schema 和覆盖范围 |
| 报表资源 | 已采集的报表及数据集 | 报表来源和数据库对象关联 |
| OpenLineage 任务 | 外部运行任务与事件 | 作业标识、输入输出和事件完整性 |
元数据采集完成后先在血缘空间检查资源，再创建正式血缘任务。资源缺失时应回到采集配置处理，而不是通过手工血缘长期弥补。
创建血缘任务
血缘任务按来源可分为：
- Script：处理脚本或 SQL 文件。
- ETL：处理受支持的 ETL 工具导出内容或任务定义。
- Container of User-Defined-Object：血缘编辑保存后生成的对象容器，不可再次解析。
创建时应记录任务用途、责任人、来源、解析引擎、命名空间和运行方式。先用小批量文件验证，再导入完整范围。
全量与增量导入
全量导入将指定目录中的脚本导入，重复文件被覆盖并变为“未解析”，支持多层目录和不同层同名文件。增量导入按内容、大小、路径和文件名比较，相同文件跳过，不同文件更新。执行前核对范围，不把“全量”理解为已有文件必然全部删除。
强制绑定元数据
强制绑定用于把代码解析得到的对象关联到已采集元数据。启用前必须确认命名空间、数据连接、默认 Schema 和对象命名规则一致。绑定失败时先修复上下文，不应按名称随意选择对象。
预处理管理
预处理在正式解析前处理变量、连接信息或不规则文本。可用方式包括：
- JavaScript：按受控脚本转换输入内容。
- 正则表达式：匹配并替换格式稳定的文本或变量。
- 大模型：辅助处理难以用固定规则覆盖的内容，结果必须抽样复核。
规则可引用任务变量和数据连接。配置后先比较预处理前后的文本，确认没有改变业务语义，再提交解析。预处理脚本或表达式应由授权人员维护并保留变更记录。
解析报告
任务执行后，解析报告通常按以下结果分类：
| 结果 | 含义 | 处理方式 |
|---|---|---|
| 成功 | 内容完成解析 | 抽样核对关键链路 |
| 部分成功 | 仅部分语句或对象完成解析 | 查看未解析明细并修复后重跑 |
| 语法错误 | 内容不符合所选解析语法 | 核对引擎、代码完整性和变量 |
| 元数据缺失 | 解析节点无法关联到元数据 | 补采元数据或修正命名空间与 Schema |
| 其他错误 | 运行环境或未知原因导致失败 | 查看日志并记录复现样本 |
解析成功率衡量输入内容的处理情况，元数据覆盖率衡量解析对象与已采集元数据的关联情况。两个指标应分别检查。
DBLink 映射
当代码通过 DBLink 等机制引用其他数据源时，配置映射把代码中的连接标识对应到正确的数据连接和命名空间。映射错误会造成跨系统链路断开或关联到错误环境。
命名空间管理
命名空间用于唯一识别不同系统和环境中的对象。规划时记录所属系统、环境、资源类型和命名规则。血缘空间允许更换任务命名空间，但会影响对象匹配，执行前检查相关采集与血缘关系。
血缘编辑
血缘编辑用于补充有明确证据但无法自动采集的关系。编辑中的删除仅作用于本次新增实体和连线，不删除原画布内容。保存为自定义血缘文件后可查看、删除，但不能再次编辑修改；具体步骤见血缘编辑。
手工编辑应记录来源证据和原因。若同类关系持续需要人工维护，应优先修复采集、预处理或解析配置。
任务管理与调度
任务管理用于查看运行状态、执行历史和计划。配置调度时选择时间模板；多个模板的可执行日期取交集，再按重复周期执行。被引用模板删除或禁用后，任务不再受该模板约束。
日常监控至少关注最近和下次执行时间、成功或失败状态、处理文件数量、解析报告和连续失败次数。修改调度后执行一次受控验证，确认任务真正触发。
数据源、驱动与插件
新增数据源前确认网络、账号权限、数据库类型和驱动兼容性。驱动或解析插件的增加、替换和停用属于管理员操作，应先在测试范围验证，并记录受影响的数据源和任务。不要在用户手册或截图中保存连接密码。
结果验证
- 数据库、报表和文件资源均进入正确命名空间。
- 采集范围与计划一致，黑名单未排除关键对象。
- 解析报告中的部分成功和失败项已有处理结论。
- 成功率与元数据覆盖率分别达到项目验收要求。
- 跨数据源链路的连接和 DBLink 映射正确。
- 手工血缘有证据、操作者和时间记录。
- 调度已实际触发，执行历史与预期时间一致。
故障排查
| 现象 | 优先检查 |
|---|---|
| 元数据未进入血缘空间 | 连接、采集范围、黑名单、任务状态和数据权限 |
| 文件解析失败 | 文件完整性、解析引擎、变量、预处理和错误日志 |
| 出现大量元数据缺失 | 命名空间、默认 Schema、采集范围和对象大小写 |
| 跨系统链路断开 | 数据连接映射、DBLink 映射和上下游任务是否均已采集 |
| 出现重复节点 | 命名空间规划、对象标识和重复导入方式 |
| 调度未执行 | 启停状态、时间模板交集、依赖任务和调度日志 |