poyee-data-warehouse/kb/20-数仓分层与建模.md

数仓分层与建模

本文档记录 poyee-data-warehouse 数据仓库的分层架构、建模方法论与总线矩阵。 与命名规范（数仓命名规范.md）配套阅读。

1. 架构原则

• 横向分层：提高数据复用率，明确数据血缘
• 竖向分域：指导指标体系的建设

2. 分层定义

二维视图（横向分层 × 公共维度侧柱）：

                                                ┌────────────┐
┌───────────────────────────────────────────┐   │            │
│  ADS  应用层：业务指标、面向服务端宽表      │   │            │
├───────────────────────────────────────────┤   │            │
│  TDM  标签层：长表明细 + 宽表 + 人群包      │◄──┤    DIM     │
├───────────────────────────────────────────┤   │            │
│  DWS  汇总层：主题聚合、提供公共指标        │◄──┤  公共维度   │
├───────────────────────────────────────────┤   │            │
│  DWD  明细层：清洗加工 + 维度退化           │◄──┤            │
├───────────────────────────────────────────┤   │            │
│  ODS  贴源层：类型转换、脏数据识别          │   │            │
├───────────────────────────────────────────┤   └────────────┘
│  RAW  采集层：全字段 STRING，原样落盘       │
└───────────────────────────────────────────┘

  竖向分域（贯穿 DWD 及以上）：交易 trd / 用户 usr / 商品 prd / 店铺 shp / 公共 pub

分层定义表：

层	代码	定位	典型操作
原始采集层	raw	从源系统/外部文件落地的原始数据，全字段 STRING，同步任务不做任何类型转换	DataX 直接同步、CSV 解析、字段原样落盘
贴源层	ods	类型转换、空值处理、脏数据识别的唯一入口，输出类型化的干净表	从 raw STRING 字段做 CAST/TRY_CAST、空值兜底、去重
维度层	dim	公共维度（时间、地区、渠道等），贯穿 DWD/DWS/TDM/ADS	维度退化、缓慢变化维
明细层	dwd	标准化、维度补全、异常处理；星型模型	宽表化、维度退化、数据质量校验
汇总层	dws	建立汇总宽表，提供公共指标	多维聚合、主题整合
主题域模型层	tdm	标签明细长表（EAV）+ 核心标签宽表（pivot）+ 人群包（远期 bitmap）；按实体类型分表（usr/prd/shp），Hive 离线计算，远期可加 HBase（在线标签服务）/ ClickHouse（人群包交叉计算）	标签计算、pivot 宽表、bitmap 圈选
应用层	ads	提供数据展示、数据指标	面向消费端的定制聚合

数据流：

RDS PG / ES ──DataX──▶ RAW ──SparkSQL──▶ ODS ──▶ DWD ──▶ DWS ──▶ TDM ──▶ ADS
                                                                             │
                                                                             ▼ DataX / Broker Load
                                                            服务层（Doris / CK / ES / Mongo）

3. 主题域划分

当前划分为以下主题域，对应命名规范的 domain 代码：

域	代码	说明
交易域	trd	订单、支付、退款、购物车
用户域	usr	注册、登录、活跃、画像
商品域	prd	商品、SKU、SPU、价格
店铺域	shp	店铺、商家
公共域	pub	平台、日历、地理等

4. 数仓总线矩阵

总线矩阵用于指导维度建模和指标体系建设，列出各业务过程与公共维度/业务维度的关系。 以下是模板，还未整理成正式可用的矩阵

域	业务过程	说明	时间	用户	地区	渠道	商品	店铺	活动	支付
交易域	order_create	用户提交订单（未支付）	✓	✓	✓	✓	✓	✓	✓
	order_pay	用户完成订单支付	✓	✓	✓	✓	✓	✓	✓	✓
	order_cancel	用户取消订单	✓	✓	✓	✓	✓	✓	✓
	refund	用户发起退款/售后	✓	✓	✓	✓	✓	✓	✓
	cart_add	用户加入购物车	✓	✓	✓	✓	✓	✓
用户域	user_register	用户注册账号	✓		✓	✓
	user_login	用户登录行为	✓		✓	✓
	user_active	活跃行为（浏览/点击）	✓		✓	✓
商品域	product_expose	商品曝光（列表/推荐位）	✓	✓		✓		✓	✓	✓
	product_click	商品点击进入详情页	✓	✓		✓		✓	✓	✓
	product_favor	用户收藏商品	✓	✓		✓		✓	✓	✓
店铺域	shop_visit	用户访问店铺	✓	✓	✓	✓
	shop_follow	用户关注店铺	✓	✓	✓	✓

5. 维度建模方法论

OLTP 业务库采用范式建模；OLAP 数仓特别是 DWD 层采用维度建模（Kimball）。 模型类型：星型模型，维度退化在 DWD 或 DIM 层完成。

5.1 建模五步法

步骤	说明	示例（发券业务）
1. 确定主题域	选取所属业务域	交易域 / 营销域
2. 选择业务过程	从业务流程中提取可度量的动作	券发放 / 曝光 / 点击 / 领取 / 核销
3. 声明粒度	明确事实表每行表示什么；优先原子粒度	"每个用户每次领券记录"；主键 = 领取 id + 幂等 id
4. 确认维度	从哪些角度切分数据	权益类型、发放渠道、门槛、折扣、时间、用户
5. 确认事实	表示度量的数值字段	领取金额、核销金额、引导 GMV

5.2 关键原则

• 同一事实表粒度必须一致。跨业务过程合并的合并事实表，各自度量必须有同等级粒度。
• 维度退化：将常用维度属性冗余到事实表，减少运行时 JOIN。
• 一致性维度：公共维度全局统一（见 dim_pub_* 系列）。
• 原子粒度优先：最低粒度事实可以无限上卷，高粒度事实不可下钻。

5.3 建模示例

【业务过程】 券的核销
【粒度】      子订单 × 券 id （SKU 级）
【维度】      权益类型 / 领取场景 / 发放渠道 / 时间 / 用户 / 店铺
【事实】      核销金额 / 引导 GMV

5.4 从数仓规划到物理落地的推演

左侧是抽象的规划层级，右侧是一个零售业务的具体示例：

规划层级	示例（xxx 零售）	物理落地
业务板块	xxx 零售	—
数据域	交易域	Schema 划分
业务过程	支付	DWD 事实表切片
度量	下单金额	事实字段
维度建模	时间 / 区域 / 商品	维度表：订单表、商品表
原子指标	下单金额	order_amt_cny
派生指标	近 1 天 上海区域 支付下单金额	ADS 汇总表字段
汇总表	ads_trd_order_area_agg_inc_d	按区域聚合的下单金额日汇总

关键映射：业务过程 → DWD 事实表；度量 → 事实字段；维度 → DIM 表；派生指标 = 原子指标 + 时间周期 + 修饰词 → DWS/ADS 字段。

5.5 DWD 事实表设计（事件 vs 状态）

核心规则：DWD 事实表默认承载业务事件（不可变事实），实体当前状态进 DIM 拉链表（_zip_d）。

事件 vs 状态判别：

• 事件：某一时刻发生的业务动作（下单、支付、发货、签收、提交审核、审核通过 / 拒绝），不可变，写入即固定
• 状态：实体当前的属性或阶段（订单当前状态、用户等级、拼团当前状态），随时间演化，可变

建模规则：

类型	归属	命名（参考 21-命名规范.md）	示例
业务事件	DWD 事实表，每个业务过程一张	dwd_{域}_{业务过程}_apd_d	dwd_trd_order_create_apd_d、dwd_trd_order_pay_apd_d
实体状态	DIM 拉链表	dim_{域}_{实体}_zip_d	dim_trd_order_zip_d（含 current_status / 各阶段时间 / start_date / end_date）

为什么这么拆：

• DWD _apd_d 只追加，与 Hive 列存（ORC）"只追加 + 分区"模型天然契合，不需要 UPDATE
• 状态查询（"截止 dt 各状态订单数"）走拉链表 is_current 切片或按 dt 切片，直观
• 跨表 JOIN（"下单数 - 退单数 = 实际下单数"）是维度建模的正常能力，不是代价
• 这是 Hive / 列存数仓的事实标准做法（阿里 OneData / 字节 / 美团数仓主流）

典型场景：

场景	事件表（DWD _apd_d）	状态表（DIM _zip_d）
订单履约（下单 → 支付 → 发货 → 签收，单向）	4 张 _apd_d	dim_trd_order_zip_d
拼团（发起 → 审核 → 审核拒绝 → 重新提交 → ……，循环）	每个动作一张 _apd_d（含"审核拒绝"、"重新提交"等可重复事件）	dim_trd_group_zip_d，每次状态变更生成新拉链行
浏览 / 点击 / 加购（独立事件流，无状态实体）	各一张 _apd_d	无
订单 vs 订单明细行（一对多）	各一张 _apd_d（粒度不同必拆）	无

循环状态机的处理：业务流程若存在循环（如拼团审核可能多次反复："提交 → 拒绝 → 修改 → 再提交"），事件流水（_apd_d）天然支持任意次重复——每次状态变更追加一行，完整还原过程；DIM 拉链表（SCD Type 2）每次状态变更生成新行，旧行 end_date 置变更前一天，状态历史完整可回溯。

何时可考虑 acc：固定线性里程碑场景（不循环、里程碑可枚举且单向推进，如严格不可逆的合同审批流程），如有具体场景按需单独评估，不一刀切禁用。新建 acc 表时在 PR / 设计稿里说明选型理由。

自检：建表想给字段加"时间戳 + 若干状态字段"时，停一步问：这是事件还是状态？事件 → _apd_d；状态 → _zip_d。

6. 数据同步策略

ODS 层从业务库/埋点/爬虫数据接入。关键问题：数据是否存在物理删除，决定增量策略。

数据来源	接入方式	快照类型	备注
业务库 (PG/MySQL)	DataX + CDC	inc（增量）	如存在物理删除，后续推行软删除
埋点 (Sensors → Kafka)	Kafka → HDFS/Hive	apd（追加）	不可变事件流
爬虫数据	爬虫落库 → DataX	ful 或 inc	按源站特性决定
维度数据	手工上传 / 配置化	ful（全量）	如国家映射、汇率表
一次性历史 / vendor 单批交付	本地 CSV → bin/csv-to-hdfs-starter.py	his（一次性历史）	永不调度，导入后入档；周期段固定 _o

快照类型决策：

• 数据创建后会被修改 → inc（增量快照）
• 数据不可变 → apd（追加）
• 缓慢变化维、需要保留历史轨迹 → zip（拉链表）
• 每日重刷全表 → ful（全量）
• 一次性导入、永不再跑 → his（与 ful 严格区分：ful 是周期性调度的全量重刷，his 是导入后归档的一次性快照）

7. 分区与存储策略

• 分区字段：dt（必须），STRING 类型，格式 YYYYMMDD（如 20260101）；hr（小时，按需）
• 存储格式：ORC（列存）
• 纠删码：当前关闭（保持 3 副本），等 Worker 节点扩容后对冷数据启用

7.1 组合快照示例

拼团 DWD/DIM 组合：每个动作（发起 / 审核 / 拒绝 / 重新提交 / 成功 / 失败）独立 dwd_trd_group_{动作}_apd_d 事件表承载不可变流水；实体当前状态进 dim_trd_group_zip_d 拉链表，每次状态变更生成新拉链行。详见 §5.5。

7.2 各层分区语义

各层 dt 分区键代表的时间含义、对漂移和重复的容忍度、分区间关系不同，是设计 ETL 任务和理解查询行为的基础。

层	分区键语义	时间字段来源	漂移容忍	重复容忍	分区间关系
Raw	批次日（系统时间）	dt = stop - 1（抽取任务的逻辑日期）	容忍	容忍（同 pk 同 dt 内可多条）	独立，可含跨日漂移数据
ODS	记录最后写入日（系统时间）	DATE(update_time)	不容忍	分区内不容忍、跨分区容忍（保留 update_time 轨迹）	独立，同 pk 可跨多分区
DWD 事实表	业务行为发生日（业务时间）	DATE(order_create_time) / DATE(event_time) 等业务字段	不容忍	不容忍（事件不可变）	独立，追加写
DIM 拉链表	不按时间分区（或 is_current 二级分区）	——	——	多版本非重复（[start_date, end_date) 区间不重叠）	每行是状态生效区间
DIM 快照表	快照日（业务时间）	dt = today	不容忍	分区内不容忍；跨分区同 pk 多次出现是"每日快照"而非重复	独立，每分区是该日全量
DWS	统计截止日（业务时间）	聚合口径的截止点	不容忍	分区内不容忍；分区间原始明细冗余	分区间冗余（滑动窗口重叠）
ADS	报表快照日（业务时间）	报表生成日	不容忍	不容忍	独立，一行可含多统计周期指标

两个容忍度的概念：

• 漂移容忍 = "某条记录落在了错误的 dt 分区里，能不能接受？" 描述数据 vs 分区归属的正确性
  • Raw 容忍：9 号 update_time 数据落在 Raw dt=8 号 没关系，下游会归位
• 重复容忍 = "同一个 pk 在分区内或跨分区出现多次，能不能接受？" 描述分区内 / 跨分区的唯一性约束
  • Raw 容忍：一次抽取窗口内同 pk 可能被捞多次，不需要去重
  • ODS 分区内不容忍（需去重），跨 dt 容忍（保留轨迹）
  • DWD 事实表双不容忍：事件就是一次，多一条就是错
  • DIM 拉链表"多版本非重复"：同 pk 多行表示状态演化

两个容忍度的组合反映各层的核心取舍：

• Raw 双容忍 → 抽取简单，绝不丢数据
• ODS 漂移不容忍 + 跨分区重复容忍 → 归位 + 保留轨迹
• DWD 事实表双不容忍 → 事件唯一，业务语义精确
• DIM 拉链表特殊 → 多版本不是重复
• DWS / ADS 双不容忍 + 分区间明细冗余 → 聚合结果唯一，存储冗余换查询速度

7.3 各层职责与设计要点

各层基础职责见 §2 表格；本节聚焦每层的关键设计取舍。

Raw 层

基础职责见 §2 + §8.1。

• 写入窗口：抽取窗口 [day-start, day+1-stop)（48 小时宽），所有抓到的记录统一落 dt = stop - 1 分区
• 设计理由：宽窗覆盖"零点漂移"和"覆盖式更新下的永久丢失"，保证数据永不丢失
• 代价：分区里混有"未来时间"的记录 + 同 pk 可能重复出现，接受这两个代价换抽取逻辑简单

ODS 层

基础职责见 §2 + §8.2。

• 写入：Spark SQL 动态分区 PARTITION (dt)，按 DATE(update_time) 分发，把 Raw 漂移数据归位到正确分区
• 两种写入模式（可表级混用）：
  • 方案 A（INSERT OVERWRITE）：每次 ODS 跑批覆盖对应 dt 分区；数据不丢失，因为 Raw 最多漂一天，次日 Raw 必然抓到
  • 方案 B（INSERT INTO + 分区内 (pk, max(update_time)) 去重）：保留每日 ODS 跑时刻的 dt=X 版本轨迹，用于审计、回溯，防止覆盖后丢失中间快照
• 关键约束：跨 dt 不去重。同一 pk 允许在多个 dt 分区并存，每条代表一个"时间段状态快照"——是上层 DIM 拉链表（SCD Type 2）的必要基础

DWD 层（事实明细）

基础职责 + 事件 vs 状态拆分原则见 §5.5。

• 分区：业务时间（下单日、支付日、事件发生日），不是抽取日
• 写入：每天冗余跑近 3 日，兜底 ODS 漂移（虽然 ODS 已归位，但 ODS 漂移修正后 DWD 需要回算）

DIM 层（维度）

• 职责：承载业务实体的状态
• 建模：按表特征选型，不统一

表特征	建模方式	分区策略	写入模式
大 / 中维度表（用户、商品、商户）	拉链表 SCD2	不分区（或 is_current 二级分区）	当日变更 pk：原行 end_date 置昨天 + 新行 insert
小高频变更维表（类目、地区、配置）	每日全量快照	业务时间分区	每日全量覆盖 dt=today 分区
极小不变表（字典、枚举）	单表全量	不分区	偶尔全量覆盖

选型判据：变更率 × 保留天数

• 变更率低（< 1% / 日）+ 保留长：拉链更优
• 变更率高（> 20% / 日）+ 保留短：快照更优

拉链表分区的特殊性：

• 拉链表每行是"状态生效区间"，不是"时间点"，天然不适合按业务时间分区
• 可以按 is_current='Y'/'N' 做二级分区加速"当前状态"查询
• 大表可以按 start_date 年份 / 月份做粗粒度分区控制扫描范围

DWS 层

• 职责：面向分析主题的轻度汇总，用冗余存储换查询性能
• 组织方式：主题 × 粒度 × 统计周期 一张表
  • dws_user_order_1d、dws_user_order_7d、dws_user_order_30d
  • dws_shop_order_1d、dws_shop_order_7d、dws_shop_order_30d
• 分区语义：业务截止日。每个分区自包含完整周期聚合（7 日表每天分区含过去 7 天完整聚合）
• 分区间冗余是刻意设计：滑动窗口天然重叠，换取"一次分区裁剪命中答案"的查询速度
• 来源：DWD 事实表 + DIM 维度表 join 聚合
• 增量计算优化：7d = 今日 1d + 昨日 7d - 7 天前 1d，减少 DWD 扫描压力

ADS 层

• 职责：面向具体报表 / 应用，把多个统计周期拼成一行，BI 直接用
• 组织方式：报表主题 一张表，一行多周期
  • user_id | order_cnt_1d | order_cnt_7d | order_cnt_30d | gmv_1d | ... | dt
• 分区语义：报表快照日（历史报表不可被后续数据改动，保审计性）
• 生成方式：多张 DWS 同分区日 join 而来
• 可重放性：所有 ADS 数据都能从 DWS / DWD / DIM 重算；实务中用 TTL 定期删除历史分区，要查老报表就触发任务重放

7.4 分区与建模设计原则

原则 1：Raw / ODS 是系统时间，DWD 及以上是业务时间

• Raw / ODS：系统时间（update_time 及 ETL 批次时间）。贴源层不解释业务语义，只忠实反映"数据库里发生了什么"
• DWD / DIM / DWS / ADS：业务时间（order_create_time 等）。面向分析，分区语义对齐业务问题（"8 号下了多少单"指的是用户 8 号下单的行为，不是数仓 8 号抓到的数据）

原则 2：漂移容忍度和重复容忍度自下而上递减

• Raw：双容忍（漂移 + 重复都接受）
• ODS：漂移不容忍、分区内重复不容忍、跨分区重复容忍（保留 update_time 轨迹）
• DWD / DIM / DWS / ADS：漂移不容忍、分区内重复不容忍（DIM 拉链的"多版本"不算重复）

原则 3：分区语义和查询语义对齐

查询条件里的 where dt='8 号' 应该和用户的直觉对齐：

• 分析师问"8 号下单数" → 查 DWD 事实表 where dt='8 号'，分区键是业务下单日
• 运维排查"8 号这批抓了什么" → 查 Raw where dt='8 号'，分区键是批次日

两种"8 号"语义不同，分别由不同层承载，不混淆。

原则 4：事实与维度解耦（DWD vs DIM 并列）

• DWD 事实表：记录不可变业务事件，只追加，业务时间分区
• DIM 维度表：记录实体状态，拉链或快照，按规模和变更率选型
• 跨表计算（下单数 - 退单数 = 实际下单数）是维度建模的正常能力，不是代价
• 不把两者混在一层 → 建模方法、分区策略、更新方式清晰分离

原则 5：ODS 为下游保留最大灵活性

• ODS 跨 dt 不去重 → 保留 update_time 轨迹 → 支持 DIM 拉链表建设
• ODS 不预设下游建模方式 → DWD 可按表特征自由选事件化，DIM 可按规模选拉链 / 快照

原则 6：上层数据可重放，下层数据不可重放

• Raw / ODS：源头层，业务库覆盖式更新会导致历史无法还原，不可重放，要长期保留
• DWD / DIM：规整层，理论可从 ODS 重放，实务按"不可重放"管理，长期保留
• DWS / ADS：派生层，可重放（前提上游数据还在），用 TTL 控制存储成本
• 保留周期自下而上递减（越接近派生数据的层，TTL 越短）

8. raw 层与 ods 层的职责约定

这是本数仓的核心数据契约，所有 raw / ods 层作业都必须遵守。

8.1 raw 层：schema-on-read landing

• 全字段 STRING：raw 层所有表业务字段以及 dt 分区字段一律 STRING 类型
• 同步任务不做类型转换：DataX ini 里不写 columnType 的类型映射（或统一填 string），CSV 导入时 SparkSQL 读取后也不 CAST
• 外部表兜底：raw 层建表一律用 CREATE EXTERNAL TABLE，DROP TABLE 只删元数据，HDFS 数据保留；raw 作为链路兜底层，误删元数据时数据仍可 MSCK REPAIR / 重建元数据恢复，无需回源库重同步

8.2 ods 层：类型转换与脏数据识别

• ods 是类型化的第一层：从 raw 的 STRING 字段做 CAST / TRY_CAST，输出真正类型化的干净表
• ods 是脏数据拦截线：转换失败的数据不能静默丢弃，必须有可观测的出口（打标记字段、落到 _err 分区、或写入专门的数据质量日志表，具体策略 TBD）
• ods 不做业务语义加工：只做"把字符串变回正确类型 + 空值兜底 + 去重"，不做字段合并、维度关联、指标计算等 dwd 才做的事

8.3 其他框架字段

raw 层是否需要 etl_load_time / src_file / src_row_no 等框架字段，暂不做统一要求，后续实际接入第一批表时再根据需要补充到本节。

8.4 ods 层类型映射参考

总则：raw 层一律 STRING 兜底同步；类型化在 ods 层完成。下表为 ods 层 CAST 目标类型的参考表，具体字段可按业务需要微调（如小金额字段可下沉到 DECIMAL(16,2)）。

8.4.1 PostgreSQL → Hive

PG 类型	Hive 类型
int2 / smallint	BIGINT
int4 / integer / int	BIGINT
int8 / bigint	BIGINT
serial	BIGINT
bigserial	BIGINT
numeric / decimal	DECIMAL(20,4)
real / float4	DECIMAL(20,4)
float8 / double precision	DECIMAL(20,4)
char / character	STRING
varchar / character varying	STRING
text	STRING
timestamp / timestamp without time zone	STRING
timestamptz	STRING
date	STRING
time / timetz	STRING
boolean / bool	TINYINT
uuid	STRING
interval	STRING
tsvector	STRING
array	STRING（保留 JSON/文本形态，dwd 按需解析）
hstore	MAP<STRING,STRING>

说明：

• 整数统一 BIGINT：避免上游扩位（int4 → int8）时下游被动改表
• 小数统一 DECIMAL(20,4)：覆盖绝大多数金额/比率场景；特殊精度需求（如高精度科学计算）单独评估
• 布尔用 TINYINT（0/1）：Hive 的 BOOLEAN 与 ORC/Spark 生态兼容性没有 TINYINT 稳定
• 时间类型全部 STRING：保留源端字面量，dwd 层再按需 to_timestamp / to_date

8.4.2 Elasticsearch → Hive

（待补，首批 ES 埋点库接入时落地）

9. 相关文档

• 命名规范 — 表/字段命名五段式
• 指标体系 — 原子/派生指标定义
• 标签体系 — TDM 层画像/标签