数仓命名规范

本文档是 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`	测试表	开发测试用

3.9 DataX ini 文件命名

按数据流向分三类，各自命名规则不同；ini 文件名全局唯一，等于生成的 JSON 文件名（去扩展名）和 JOB_NAME。

场景	方向	命名模板	存放位置	示例
采集	外部源 → Hive	`{目标 Hive 表名}.ini`	`jobs/raw/{域}/`	`raw_trd_order_pay_inc_d.ini`
导出	Hive → 外部服务	`{源 Hive 表名}__{目标 db_type}_{目标 instance}.ini`	`jobs/ads/{域}/`	`ads_trd_gmv_d__mysql_bi.ini`、`ads_trd_gmv_d__pg_api.ini`
一次性	任意	`{yyyymmdd}_{描述}.ini`	`manual/{子类}/`	`20260415_backfill_hobby_orders.ini`

导出类双下划线规则：

__（双下划线）是"导出"的视觉标志，和五段式表名内部的单下划线分层，一眼能识别"这是 Hive 往外写"
前段 = 源 Hive 表名（五段式），后段 = {目标 db_type}_{目标 instance}，直接对应 writer 里的 dataSource = {db_type}/{instance}，写 ini 时不用二次翻译
同一张 Hive 表扇出多个下游时（如 ads_trd_gmv_d 同时导出到 MySQL BI 库和 PG API 库）不撞名；撞名的唯一可能是同源表 + 同目标实例，那本来就是同一个任务

通用约定：

一套代码跑多环境：不在 ini 文件名里加 prod / dev / test 前缀。环境差异体现在 datasource/{db_type}/{env}/{instance}.ini，由脚本根据 -env 参数注入
ini 内 reader/writer 的 dataSource 字段只写 {db_type}/{instance}（不含 env），例如 dataSource = mongo/hobby
DataX 生成引擎（dw_base/datax/job_config_generator.py）对文件名不做校验，上述命名规则是人/AI 写作约定，靠 code review 保证
命名唯一性保证 JSON 输出目录 conf/datax-json/{env}/{ini_basename}.json 不会互相覆盖

参考样板：conf/templates/datax/{raw,ads,manual}/*.template.ini 提供各类同步场景的字段齐全样本，新开发者和 AI 写新 ini 时抄这里。

为什么不按老项目的 {from}-{to}-{db}-{table}.ini 命名：

同步方向已经在 ini 的 [reader] / [writer] section 的 dataSource 里体现，文件名再写一遍是冗余
目标/源表名命名能与 manual/ddl/{表名}.sql 和 jobs/{layer}/{域}/{表名}.sql 一一对应，便于 grep 追一张表的完整生命周期

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_{域}_{用途描述}`	应用场景	无
DataX ini 采集	`{目标 Hive 表名}.ini`（见 §3.9）	五段式表名	`.ini`
DataX ini 导出	`{源 Hive 表名}__{目标 db_type}_{目标 instance}.ini`（见 §3.9）	双下划线分隔源/目标	`.ini`
DataX ini 一次性	`{yyyymmdd}_{描述}.ini`（见 §3.9）	日期前缀避撞	`.ini`

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 层表名不带时间窗口后缀，窗口信息在字段名中体现

21-命名规范.md 19 KB История Директен файл