📚 课程目录第4章 Dataset定义与注册

4. Dataset 定义与注册：如何定义 Schema、注册流程与元数据存储设计

好，咱们进入 Dataset Trigger 最核心的一步——Dataset 的定义与注册。

说白了，你要用数据驱动调度，首先得让系统认识你的数据。它长什么样？存在哪？谁来更新？这些信息不告诉调度系统，它就是个瞎子。

我个人习惯把这一步比作「给数据上户口」。户口本上写清楚姓名、住址、家庭成员，系统才能后续追踪它的变化。今天我们就聊聊这个户口本怎么写。

4.1 Dataset Schema 定义

Schema 就是数据的「身份证」。它描述了数据集的结构和关键属性。

我在项目中遇到过不少团队，上来就定义一堆字段，结果跑起来发现缺了关键信息——比如忘了标记数据集的更新频率，导致调度系统不知道什么时候该去检查。

核心原则：Schema 定义要「够用但不过度」。最少包含以下四类信息：

标识信息：数据集名称、命名空间、版本
位置信息：存储路径、文件格式、分区键
血缘信息：上游依赖、下游消费者
治理信息：更新频率、保留策略、数据质量规则

来看一个实际的 Schema 定义示例。这是我在一个实时数仓项目中用过的结构：

{
  "dataset": {
    "name": "order_flow_daily",
    "namespace": "ods.trade",
    "version": "1.0.0",
    "description": "每日订单流量汇总表",
    "location": {
      "path": "hdfs://nameservice1/data/ods/trade/order_flow",
      "format": "parquet",
      "partition": ["dt", "hour"]
    },
    "lineage": {
      "upstream": ["ods.trade.order_detail", "ods.trade.payment"],
      "downstream": ["dws.trade.order_agg"]
    },
    "governance": {
      "update_frequency": "hourly",
      "retention_days": 30,
      "quality_rules": ["row_count > 0", "amount_sum > 0"]
    }
  }
}

嗯，这里要注意：partition 字段一定要写清楚。我见过有人忘了写分区键，结果调度系统每次全表扫描，把 HDFS 都扫崩了。

4.2 Dataset 注册流程

定义好 Schema 之后，就要把它注册到调度系统的元数据中心。注册流程我一般分为三步：

提交 Schema —— 通过 API 或 CLI 提交定义文件
校验与解析 —— 系统检查格式、必填字段、命名冲突
持久化存储 —— 写入元数据库，建立索引

你想想看，如果第二步校验不通过，第三步根本不会执行。这其实是个很好的防御机制。

我的经验：注册流程一定要支持「幂等性」。同一个 Dataset 重复注册不会报错，而是返回已有记录。我曾经因为脚本重跑，同一个数据集被注册了三次，结果下游任务触发了三次，数据翻了三倍——那场面，啧。

下面是一个典型的注册 API 调用示例：

curl -X POST http://scheduler:8080/api/v1/datasets/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_flow_daily",
    "namespace": "ods.trade",
    "location": "hdfs://nameservice1/data/ods/trade/order_flow",
    "format": "parquet",
    "partition": ["dt", "hour"],
    "update_frequency": "hourly"
  }'

返回结果会包含一个 dataset_id，后续所有操作都靠这个 ID 来关联。

4.3 元数据存储设计

元数据怎么存？这是个老生常谈的问题。我直接说结论：关系型数据库 + 缓存 是最稳的方案。

为什么？

关系型数据库保证事务和一致性——注册、更新、删除不会乱
缓存扛查询压力——调度系统每秒可能要查几万个 Dataset 的状态

来看一张我常用的元数据表结构设计：

字段名	类型	说明
dataset_id	VARCHAR(64) PK	全局唯一标识，由 namespace + name 哈希生成
name	VARCHAR(256)	数据集名称
namespace	VARCHAR(256)	命名空间，用于隔离不同业务线
location	TEXT	存储路径，支持 HDFS、S3、本地文件
format	VARCHAR(32)	文件格式：parquet / orc / csv / json
partition_keys	TEXT	JSON 数组，如 ["dt", "hour"]
update_frequency	VARCHAR(16)	hourly / daily / weekly
last_updated	TIMESTAMP	最近一次数据变更时间
version	INT	乐观锁，用于并发控制

避坑指南：千万不要把 location 字段设成唯一索引。我遇到过同一个数据集因为路径大小写不一致，被注册成两条记录，下游任务全乱了。正确的做法是用 namespace + name 做联合唯一索引。

缓存层我推荐用 Redis。key 设计成 dataset:{namespace}:{name}，value 存整个 Schema 的 JSON 序列化。TTL 设 5 分钟，配合数据库的变更通知来刷新。

4.4 整体流程一览

说了这么多，咱们用一张图把整个流程串起来。从 Schema 定义到注册，再到元数据存储，每一步都环环相扣。

你看，从 Schema 定义到缓存更新，一共五步。每一步都有对应的错误处理机制。校验失败返回错误码，持久化失败回滚事务，缓存更新失败触发告警——这才是一个健壮的系统该有的样子。

个人建议：在实际项目中，把注册流程做成「异步 + 回调」模式。提交注册请求后立即返回一个 task_id，后台异步执行校验和持久化，完成后通过 webhook 通知调用方。这样用户体验好，系统压力也小。

好了，Dataset 的定义与注册就聊到这儿。记住三个关键词：Schema 要全、注册要幂等、元数据要稳。把这三点做到位，数据驱动调度的地基就算打牢了。