📚 课程目录第3章 OpenLineage 核心概念

3. OpenLineage 核心概念

在金融数据血缘采集场景中，OpenLineage 并不是一个“抓 SQL 日志”的工具，而是一套用于描述数据流转过程的元数据标准。它把一次数据加工拆解为可被统一理解的几个核心对象：命名空间、数据集、作业、运行与事件。只有先理解这些对象之间的语义边界，后续接入 Spark、Flink、Airflow 或自研调度系统时，才能把血缘信息准确映射到 OpenLineage 模型上。

一、核心对象与语义边界

OpenLineage 的元数据模型围绕“谁在什么环境下、对哪些数据、执行了什么、产生了什么结果”展开。五个核心概念分别承担不同职责：

命名空间（Namespace）：用于隔离不同环境、集群或租户下的同名对象。金融场景中常见如 prod-bigdata、uat-risk、dev-etl。命名空间是数据集和作业的唯一性前缀，避免“生产订单表”和“测试订单表”被错误合并。
数据集（Dataset）：血缘的节点，表示被读取或写入的数据实体，可以是 Hive 表、Kafka Topic、对象存储路径、数据库表或文件。数据集由“命名空间 + 名称”唯一确定。
作业（Job）：血缘的边，表示一次数据加工逻辑，如一个 Spark 应用、一条 Flink 作业、一个 Airflow Task 或一段 SQL 脚本。作业描述“做什么”，但不代表某一次具体执行。
运行（Run）：作业的一次具体执行实例，拥有唯一 runId。同一作业每天调度一次，就会产生多个 Run。运行是连接事件、时间、状态和血缘快照的载体。
事件（Event）：OpenLineage 采集的最小传输单元，采用 JSON 结构描述某一时刻发生的血缘事实，如 START、RUNNING、COMPLETE、FAIL、ABORT。

一句话理解：命名空间划定边界，数据集构成节点，作业定义逻辑，运行承载实例，事件负责传输。血缘图谱最终由大量事件按 runId 聚合而成。

二、事件模型与元数据规范

OpenLineage 事件遵循统一 JSON Schema，核心字段包括 eventType、eventTime、producer、job、run、inputs、outputs 以及可选的 facets。其中 facets 是扩展元数据的关键机制，用于承载 schema、数据质量、列级血缘、生命周期状态等附加信息。

{
  "eventType": "COMPLETE",
  "eventTime": "2025-03-18T02:15:33.120Z",
  "producer": "https://github.com/OpenLineage/OpenLineage/tree/1.9.0/integration/spark",
  "job": {
    "namespace": "prod-bigdata",
    "name": "risk.dwd_loan_repay_daily"
  },
  "run": {
    "runId": "8f2c1a7e-4b6d-4f0a-9c3e-2d7b5a1e9f01"
  },
  "inputs": [
    {
      "namespace": "hive://prod-cluster",
      "name": "ods.loan_repay_log"
    }
  ],
  "outputs": [
    {
      "namespace": "hive://prod-cluster",
      "name": "dwd.loan_repay_daily"
    }
  ],
  "facets": {
    "schema": {
      "fields": [
        {"name": "loan_id", "type": "string"},
        {"name": "repay_amt", "type": "decimal(18,2)"}
      ]
    }
  }
}

事件类型通常按生命周期划分：START 表示作业开始，RUNNING 表示执行中，COMPLETE 表示成功结束，FAIL 表示失败，ABORT 表示被终止。采集端可以在 START 时先上报输入数据集，在 COMPLETE 时补充输出数据集和 schema facet，从而形成完整血缘。

三、金融场景下的血缘采集流程

以某银行“贷款还款日汇总”任务为例，Airflow 每天凌晨调度 Spark 作业，从 Hive 贴源层读取还款日志，写入 DWD 层宽表。接入 OpenLineage 后，采集流程如下：

Airflow 触发 Spark 应用，OpenLineage Spark Listener 捕获作业启动，生成 START 事件，携带 job、run 和输入数据集。
Spark 执行过程中，Listener 解析逻辑计划与物理计划，提取输入输出表、列级映射和 schema 信息。
作业成功结束，生成 COMPLETE 事件，写入输出数据集及 schema facet。
事件发送至 OpenLineage 兼容后端（如 Marquez），后端按 runId 聚合，形成“数据集—作业—数据集”的血缘边。
元数据平台消费血缘图谱，支撑影响分析、根因定位和合规审计。

四、常见误区与复盘要点

误区一：把作业名当成运行 ID。作业名是逻辑标识，runId 才是执行实例标识。若用作业名聚合事件，多次调度会互相覆盖，导致血缘时间线错乱。

误区二：忽略命名空间隔离。生产与测试环境若共用命名空间，同名表会被合并成同一节点，影响分析结果失真。

误区三：只上报输入不上报输出。只有 START 事件时，血缘图只有上游没有下游，无法做影响分析。必须在 COMPLETE 事件中补齐 outputs。

误区四：facets 随意扩展。自定义 facet 应遵循 _producer、_schemaURL 规范，否则后端无法识别，元数据会丢失。

核心概念	唯一标识	金融场景示例	常见采集来源
命名空间	namespace 字符串	prod-bigdata	集成配置、环境变量
数据集	namespace + name	hive://prod-cluster/dwd.loan_repay_daily	Spark Listener、SQL 解析
作业	namespace + name	risk.dwd_loan_repay_daily	调度系统、应用配置
运行	runId (UUID)	8f2c1a7e-4b6d-4f0a-9c3e-2d7b5a1e9f01	运行时自动生成
事件	eventType + eventTime	COMPLETE @ 2025-03-18T02:15:33Z	OpenLineage Client / Listener

复盘建议：接入初期先用最小事件集（START + COMPLETE）跑通链路，确认 runId 聚合正确、命名空间隔离生效，再逐步补充 schema、列级血缘、数据质量等 facet。不要一开始就追求全字段采集，否则事件体积和排障成本会迅速上升。

理解这五个核心概念后，后续无论是配置 Spark 集成、编写自定义采集器，还是对接 Marquez 等后端，都能围绕“命名空间定边界、数据集定节点、作业定逻辑、运行定实例、事件定传输”这一主线展开，避免血缘数据在采集阶段就出现语义偏差。