21-命名规范.md 16 KB
数仓命名规范
本文档是
poyee-data-warehouse数据仓库的命名权威规范。所有建表、字段、文件、目录命名必须遵循本规范。 给人看：作为开发手册；给 AI 看：作为代码生成和 Review 的依据。
1. 核心原则
- 全部
snake_case，全小写，单词之间用下划线 - 全英文，禁止拼音（除约定俗成的专有名词如
tid、sku） - 表名、字段名长度 ≤ 30 字符
- 优先级：行业通用缩写（gmv/dau/uv）> 技术术语词根（agg/cnt/sum）> 业务术语词根
- 一个词根（root word）对应一个语义，不允许同义多词（例如
cnt表计数，就不再用num/count）
2. 公共组件
以下组件被各层命名规则共享引用。
2.1 Domain（业务域代码）
| 代码 | 中文 | 说明 |
|---|---|---|
trd |
交易域 | 订单、支付、退款、购物车、拼团 |
usr |
用户域 | 用户注册、登录、画像、会员、行为埋点 |
prd |
商品域 | 商品、SKU、SPU、价格 |
shp |
店铺域 | 店铺、商家 |
pub |
公共域 | 平台、日历、地理等公共数据 |
2.2 Snapshot Type（快照类型）
| 代码 | 含义 | 使用场景 |
|---|---|---|
inc |
增量快照 | 数据创建后会变更（订单状态、用户信息） |
ful |
全量快照 | 每次重刷全表（维度表的日常同步） |
apd |
追加（append） | 数据创建后不再变更（埋点日志、交易流水） |
zip |
拉链表（SCD Type 2） | 属性可反复无规律变更的实体（用户改地址、改手机号、改会员等级），用 start_date / end_date 追踪每次变更 |
acc |
累积快照（Accumulating Snapshot） | 有固定生命周期里程碑的实体（拼团：发起→成团→失败/过期；订单：下单→支付→发货→签收），每个里程碑对应一列时间戳，状态单向推进 |
his |
一次性历史快照 | 历史数据回刷、vendor 单批交付，导入后永不更新、永不调度；周期段固定写 o |
zip vs acc 选择依据：
acc 适用于实体状态按固定路径单向推进的场景（如拼团的生命周期），里程碑是可枚举的，每个阶段填一列时间戳，填完不改。 zip 适用于实体属性可反复、无规律变更的场景（如用户改手机号），无法预知变更次数和内容，需要用
start_date/end_date记录每个历史版本。
inc vs apd 判断依据： 数据产生后还会不会变。会变 → inc；不会变 → apd。
一句话：状态机用 acc，属性变更用 zip。
acc 的前提条件：同一个实体的同一个状态只会经过一次（每个里程碑时间戳列只写入一次，不会被覆盖）。如果业务流程存在循环（如审核不通过→重新提交→再审核），同一个状态会经过多次，此时 acc 的时间戳列会丢失历史。循环场景的做法：主表用
inc（保留当前状态 + 最终里程碑时间），另建一张状态流水表用apd（每次状态变更追加一行，不丢历史）。
2.3 Refresh Cycle（刷新周期）
| 代码 | 含义 |
|---|---|
r |
realtime 实时 |
h |
hourly 小时 |
d |
daily 日 |
w |
weekly 周 |
m |
monthly 月 |
q |
quarterly 季 |
y |
yearly 年 |
o |
once 一次性 |
2.4 DWS 时间窗口后缀
dws 层使用时间窗口后缀替代 {快照类型}_{刷新周期} 二段（详见 §3.6）。
聚合粒度（单个周期内的汇总）：
| 代码 | 含义 |
|---|---|
1d |
单日汇总 |
1w |
单周汇总 |
1m |
单月汇总 |
1q |
单季汇总 |
1y |
单年汇总 |
滑动窗口（回看最近 n 天）：
| 代码 | 含义 |
|---|---|
7d / 30d / 90d / nd |
最近 n 天滑动窗口 |
累计：
| 代码 | 含义 |
|---|---|
td |
to date，历史至今累计 |
注意：
wtd（本周至今）、mtd（本月至今）、ytd（本年至今）等自然周期截断汇总不单独建表，在 ads 层从_1w/_1m基础数据按需计算。
3. 各层命名规则
各层表名结构不同，以下逐层说明。
3.1 raw 层
raw_{域}_{源表名}_{快照类型}_{周期}
{源表名}：保留数据源原始表名（snake_case 化），保持与源端的可追溯性- 快照类型通常为
inc（CDC 增量）或his（一次性历史导入） - raw 层全字段 STRING，不做类型转换
| 示例 | 说明 |
|---|---|
raw_trd_order_info_inc_d |
交易域，源表 order_info，增量，日 |
raw_trd_legacy_order_his_o |
交易域，历史订单 CSV 一次性导入 |
3.2 ods 层
ods_{域}_{源表名}_{快照类型}_{周期}
- 表名结构与 raw 层一致，
{源表名}保留数据源原始表名 - ods 做的事：类型转换、空值处理、脏数据标记，但不改表名，保持与 raw / 源端的对应关系
| 示例 | 说明 |
|---|---|
ods_trd_order_info_inc_d |
交易域，源表 order_info，增量，日 |
ods_prd_product_ful_d |
商品域，源表 product，全量，日 |
ods_prd_category_ful_d |
商品域，源表 category，全量，日 |
3.3 dim 层
dim_{域}_{实体}_{快照类型}_{周期}
{实体}：维度实体名，来自多张源表宽表化后的统一命名（不再是源表名）- 快照类型通常为
ful（默认）或zip（需要回溯属性变更历史时） - dim 直接从 ods 构建，不经过 dwd
| 示例 | 说明 |
|---|---|
dim_prd_product_ful_d |
商品维表，每日全量快照 |
dim_prd_sku_ful_d |
SKU 维表（与商品一对多，独立粒度） |
dim_usr_user_zip_d |
用户维表，拉链表（需追溯地址/等级变更） |
dim_pub_calendar_ful_o |
日历维表，一次性全量 |
3.4 dwd 层
dwd_{域}_{业务过程}_{快照类型}_{周期}
{业务过程}：用业务术语词根描述（见 §5），如order_pay、group_buy、page_view- 快照类型根据业务性质选择：
| 业务性质 | 快照类型 | 示例 |
|---|---|---|
| 不可变事件（埋点、流水） | apd |
dwd_usr_page_view_apd_d |
| 有生命周期里程碑的实体（拼团、订单） | acc |
dwd_trd_group_buy_acc_d |
| 有变更但无固定里程碑 | inc |
dwd_trd_order_detail_inc_d |
| 示例 | 说明 |
|---|---|
dwd_trd_group_buy_acc_d |
拼团明细，累积快照（里程碑：发起/成团/失败/过期） |
dwd_trd_order_pay_inc_d |
订单支付明细，增量 |
dwd_usr_page_view_apd_d |
页面浏览明细，追加 |
dwd_usr_click_apd_d |
点击明细，追加 |
3.5 dws 层
dws_{域}_{实体}_{主题}_{时间窗口}
dws 层使用时间窗口后缀替代五段式的 {快照类型}_{周期} 二段，因为 dws 的快照语义与聚合窗口天然绑定，合并表达更清晰。
{实体}：聚合维度（user / product / shop）{主题}：聚合的业务主题（trade / action / group_buy）{时间窗口}：见 §2.4，常用1d/7d/30d/td
dws 只提供原子粒度的聚合（日/周/月/累计），当年周累计、当月周累计等组合窗口在 ads 层按需计算，不在 dws 单独建表。
| 示例 | 说明 |
|---|---|
dws_usr_user_trade_1d |
用户交易日汇总 |
dws_usr_user_trade_td |
用户交易历史累计 |
dws_usr_user_action_1d |
用户行为（浏览/点击）日汇总 |
dws_prd_product_trade_1d |
商品交易日汇总 |
dws_prd_product_trade_30d |
商品交易近30天汇总 |
dws_trd_shop_gmv_1d |
店铺 GMV 日汇总 |
3.6 tdm 层
TDM 层采用长表（明细）+ 宽表（服务）+ 人群包（远期）三级结构，按实体类型分表，不按标签主题拆表。详见 23-标签体系.md。
标签明细长表（EAV 结构，所有标签值纵向存放）：
tdm_{域}_tag_ful_d
| 示例 | 说明 |
|---|---|
tdm_usr_tag_ful_d |
用户标签明细长表，全量，日 |
tdm_prd_tag_ful_d |
商品标签明细长表，全量，日 |
tdm_shp_tag_ful_d |
商家标签明细长表，全量，日 |
核心标签宽表（高频标签 pivot 为列，供下游直接 JOIN）：
tdm_{域}_profile_ful_d
| 示例 | 说明 |
|---|---|
tdm_usr_profile_ful_d |
用户核心画像宽表，全量，日 |
tdm_prd_profile_ful_d |
商品核心画像宽表，全量，日 |
tdm_shp_profile_ful_d |
商家核心画像宽表，全量，日 |
人群包（单表，每行一个人群，crowd_code 区分）：
tdm_{域}_crowd_ful_d
| 示例 | 说明 |
|---|---|
tdm_usr_crowd_ful_d |
用户人群包（阶段 1 用 ARRAY<BIGINT>，阶段 2+ 升级为 bitmap BINARY） |
3.7 ads 层
ads_{域}_{用途描述}
ads 是面向具体应用场景的输出表（报表、接口、导出），表名反映"给谁用、干什么"，不带时间窗口后缀。一张 ads 表里通常混合多个窗口的指标列（如 order_cnt_1d、order_cnt_7d、gmv_30d），窗口信息体现在字段名里而不是表名里。
| 示例 | 说明 |
|---|---|
ads_trd_daily_operation_report |
交易域，运营日报 |
ads_usr_user_tag |
用户域，用户标签宽表（给推荐系统） |
ads_trd_shop_ranking |
交易域，店铺排行榜 |
ads_prd_category_analysis |
商品域，品类分析报表 |
3.8 辅助表前缀
| 前缀 | 含义 | 说明 |
|---|---|---|
smp |
样本表 | 抽样、调试用 |
tmp |
临时表 | ETL 中间结果 |
test |
测试表 | 开发测试用 |
4. 字段命名规则
| 字段类型 | 规则 | 示例 |
|---|---|---|
| 主键 ID | {entity}_id |
user_id、order_id、product_id |
| 布尔 | is_{state} |
is_active、is_deleted、is_weekend |
| 时间戳 | {action}_time |
create_time、update_time、pay_time |
| 日期 | {action}_date |
order_date、reg_date |
| 金额 | {business}_amt_{currency} 必须带币种后缀 |
order_amt_cny、paid_amt_usd、dct_amt_cny |
| 数量 | {business}_cnt |
order_cnt、pv_cnt |
| 比率 | {business}_rto |
conv_rto、retn_rto |
| 等级 | {business}_lvl |
user_lvl、vip_lvl |
| 状态 | {business}_status |
order_status、pay_status |
5. 术语词根字典
5.1 业务术语（按域）
表格说明：
- 后端惯用名称：源系统数据库中的字段名，raw/ods 层保留原名，dwd 及以上统一为标准缩写
- 英文全称：字段命名的语义依据
- 标准缩写：数仓 dwd 及以上层使用的字段名词根
- 类型：实体 / 动作 / 属性 / 金额 / 状态 / 指标 / 枚举值
buyc1
5.2 数仓技术术语
| 词根 | 含义 |
|---|---|
agg |
aggregate 聚合 |
sum / avg / max / min |
求和/平均/最大/最小 |
cnt |
count 计数 |
dist |
distinct 去重 |
pct |
percentage 百分比 |
rto |
ratio 比率 |
rnk |
rank 排名 |
tot |
total 总计 |
src |
source 来源 |
etl |
ETL 标识 |
dt |
分区日期 |
hr |
分区小时 |
5.3 行业通用缩写（最高优先级，直接使用）
pv uv dau wau mau gmv arpu arppu ltv cac roi ctr cvr cpa sku spu
5.4 源系统字典（ODS 层使用）
两段式 {source_type}_{ingestion_method}：
- 源类型：
pg/es/csv/excel/api - 接入方式：
datax/cdc/excel/csv/manual - 常见组合：
pg_datax、pg_cdc、es_file、csv_manual
6. 技术字段规范（所有表均需包含）
| 字段 | 出现在 | 类型 | 含义 |
|---|---|---|---|
etl_time |
所有层 | timestamp | ETL 处理时间 |
src_sys |
ODS | string | 源系统标识 |
src_tbl |
ODS | string | 源表名 |
dt |
分区字段 | string | 分区日期 yyyy-MM-dd |
hr |
分区字段（可选） | string | 分区小时 |
start_date / end_date |
拉链表（zip） | string | 有效期，end_date=9999-12-31 表示当前 |
7. SQL 示例
ODS 层：
CREATE TABLE IF NOT EXISTS ods.ods_trd_order_info_inc_d (
order_id BIGINT COMMENT '订单ID',
user_id BIGINT COMMENT '用户ID',
shop_id BIGINT COMMENT '店铺ID',
order_amt_cny DECIMAL(18,2) COMMENT '订单金额(人民币)',
order_status STRING COMMENT '订单状态',
create_time TIMESTAMP COMMENT '创建时间',
update_time TIMESTAMP COMMENT '更新时间',
is_deleted BOOLEAN COMMENT '是否删除',
src_sys STRING COMMENT '源系统',
src_tbl STRING COMMENT '源表',
etl_time TIMESTAMP COMMENT 'ETL时间'
) COMMENT '订单贴源增量表'
PARTITIONED BY (dt STRING)
STORED AS ORC;
DWD 层（acc 累积快照）：
CREATE TABLE IF NOT EXISTS dwd.dwd_trd_group_buy_acc_d (
group_buy_id BIGINT COMMENT '拼团ID',
initiator_user_id BIGINT COMMENT '发起人用户ID',
product_id BIGINT COMMENT '商品ID',
required_cnt INT COMMENT '成团所需人数',
current_cnt INT COMMENT '当前参团人数',
status STRING COMMENT '状态: initiated/succeeded/failed/expired',
initiate_time TIMESTAMP COMMENT '发起时间',
succeed_time TIMESTAMP COMMENT '成团时间',
fail_time TIMESTAMP COMMENT '失败时间',
expire_time TIMESTAMP COMMENT '过期时间',
group_duration_sec BIGINT COMMENT '成团耗时(秒)',
etl_time TIMESTAMP COMMENT 'ETL时间'
) COMMENT '拼团累积快照明细表'
PARTITIONED BY (dt STRING)
STORED AS ORC;
DWS 层：
CREATE TABLE IF NOT EXISTS dws.dws_usr_user_trade_1d (
user_id BIGINT COMMENT '用户ID',
order_cnt BIGINT COMMENT '当日订单数',
pay_amt_cny DECIMAL(18,2) COMMENT '当日支付金额',
refund_cnt BIGINT COMMENT '当日退款数',
group_buy_cnt BIGINT COMMENT '当日参团数',
etl_time TIMESTAMP COMMENT 'ETL时间'
) COMMENT '用户交易日汇总'
PARTITIONED BY (dt STRING)
STORED AS ORC;
ADS 层：
CREATE TABLE IF NOT EXISTS ads.ads_trd_daily_operation_report (
order_cnt_1d BIGINT COMMENT '当日订单数',
pay_amt_1d_cny DECIMAL(18,2) COMMENT '当日支付金额',
order_cnt_7d BIGINT COMMENT '近7天订单数',
pay_amt_30d_cny DECIMAL(18,2) COMMENT '近30天支付金额',
group_buy_succeed_rto_1d DECIMAL(5,4) COMMENT '当日成团率',
etl_time TIMESTAMP COMMENT 'ETL时间'
) COMMENT '运营日报'
PARTITIONED BY (dt STRING)
STORED AS ORC;
8. 各层命名速查
| 层 | 表名结构 | 第三段含义 | 末段 |
|---|---|---|---|
| raw | raw_{域}_{源表名}_{快照}_{周期} |
数据源原始表名 | 快照+周期 |
| ods | ods_{域}_{源表名}_{快照}_{周期} |
数据源原始表名 | 快照+周期 |
| dim | dim_{域}_{实体}_{快照}_{周期} |
维度实体名 | 快照+周期 |
| dwd | dwd_{域}_{业务过程}_{快照}_{周期} |
业务过程名 | 快照+周期 |
| dws | dws_{域}_{实体}_{主题}_{窗口} |
聚合维度+主题 | 时间窗口后缀 |
| tdm | tdm_{域}_{tag\|profile\|crowd_*}_ful_d |
表类型（长表/宽表/人群包） | ful_d |
| ads | ads_{域}_{用途描述} |
应用场景 | 无 |
9. 合规 Checklist（建表前自检）
- 表名符合所在层的命名结构（见 §3 和 §8 速查表）
- 表名全小写 snake_case，长度 ≤ 30
- 字段全小写 snake_case，无拼音
- 金额字段带币种后缀
_amt_cny/_amt_usd - 布尔字段以
is_开头 - 时间字段以
_time（时间戳）或_date（日期）结尾 - 包含
etl_time字段 - ODS 表包含
src_sys、src_tbl - 分区字段为
dt（必须）、hr（小时级可选） - 所有字段都有 COMMENT
- 存储格式为 ORC
- 词根使用了 §5 字典，未引入同义新词
- dwd 层快照类型选择正确：不可变事件→
apd，有里程碑→acc，有变更→inc - dim 层快照类型选择正确：默认→
ful，需追溯属性变更→zip - dws 层使用时间窗口后缀而非快照+周期
- ads 层表名不带时间窗口后缀，窗口信息在字段名中体现