模型文档要素清单
每张模型表都应配一份文档，内容至少覆盖七项：粒度声明、维度含义、度量口径、更新频率与延迟承诺、业务 Owner、上下游血缘、示例查询。文档不是上线后的补充动作，而是交付物的一部分，缺项的表视为未完成。落地上最好把文档挂接在建模平台的元数据里，或放在代码仓库的 schema 文件里随代码一起评审，避免文档与实现各走各的。
基本信息
| 必备项 | 粒度、维度、度量口径、更新频率、Owner、血缘、示例 SQL |
|---|---|
| 承载位置 | 建模平台元数据或代码仓库的 schema 配置文件 |
| 更新时机 | 随模型变更同批提交，不允许事后补 |
| 验收 | 缺项的表不通过上线评审 |
典型使用场景
- 新人上手：看文档即可知道这张表能不能用、怎么用，减少口口相传
- 口径争议：度量口径写在文档里，讨论从『我认为』回到统一登记
- 故障排查：血缘与更新频率明确后，能快速判断上游延迟的影响范围
- 变更评审：改动粒度或口径时对着文档逐项确认影响面
- 交接与审计：Owner 与血缘齐备，人员流动后模型仍可被接手
文档要素示例
文档要素示例
# 随代码提交的模型文档片段
name: fact_order_item
# 粒度：一行 = 一笔订单中的一个商品行（order_id + sku_id）
sla: 每日 06:30 前产出，允许延迟 30 分钟
owner: 交易数据组
measures:
item_amt: 商品应付金额，单位分，不含运费，含活动优惠前价
discount_amt: 优惠金额，单位分，含券与满减
upstream: [stg_order, stg_order_item, dim_user]
example: SELECT dt, sum(item_amt) FROM fact_order_item GROUP BY dt文档要素与验收
| 要素 | 内容要求 | 缺失后果 |
|---|---|---|
| 粒度 | 一行代表什么，一句话写清 | 使用者按错误粒度聚合 |
| 度量口径 | 单位、币种、统计范围 | 跨表对账无法收敛 |
| 更新频率 | 调度周期与延迟承诺 | 下游排程靠猜，经常踩到空分区 |
| Owner | 负责团队与联系方式 | 问题无人认领，修复周期拉长 |
把文档写进代码仓库最大的好处是能随提交一起评审：模型改了但文档没改，评审时一眼可见，比事后靠自觉补文档可靠得多。
示例查询是最好的文档：一段可以直接运行的 SQL 胜过三段文字描述，使用者复制后微调即可，也顺带验证了文档与表的实际一致性。