align hierarchy outputs with DWS naming
This commit is contained in:
@@ -2,16 +2,77 @@
|
||||
|
||||
## 1. 范围和原则
|
||||
|
||||
本规范适用于 CHPA Databricks 数仓脚本。第一阶段目标是在不改变业务结果的前提下提高可维护性。
|
||||
本规范适用于 CHPA Databricks 数仓脚本。第一阶段目标是在不改变业务口径的前提下提高可维护性。
|
||||
|
||||
- 先保持业务口径，再做性能优化。
|
||||
- 每个脚本只负责一个主要目标表。
|
||||
- 文件头声明源表、目标表、数据粒度、写入方式和依赖。
|
||||
- 文件头声明源表、目标表、数据粒度、写入方式和迁移关系。
|
||||
- 持久化写入必须显式列出目标列和查询列，禁止使用 `SELECT *`。
|
||||
- 逻辑重构与生产表改名分开实施。
|
||||
- 为行数、唯一性、非空约束和未匹配记录建立验证查询或任务检查。
|
||||
- 为行数、唯一性、非空约束和未匹配记录建立验证检查。
|
||||
|
||||
## 2. 文件和目录命名
|
||||
## 2. 数仓分层
|
||||
|
||||
数仓固定为三层，依赖方向为：
|
||||
|
||||
```text
|
||||
DWD -> DWS -> DM
|
||||
```
|
||||
|
||||
### DWD
|
||||
|
||||
- 保存清洗、标准化后的原子明细和基础主数据。
|
||||
- 保持源数据可追溯性和稳定粒度。
|
||||
- 不承载面向报表的层级拉宽、跨主题指标聚合。
|
||||
|
||||
### DWS
|
||||
|
||||
- 引用 DWD 构建公共维度、层级宽表和可复用事实表。
|
||||
- 统一编码、公共口径和跨明细关联结果。
|
||||
- 本批 ATC/NFC 层级宽维表属于 DWS，不再写回 DWD。
|
||||
|
||||
### DM
|
||||
|
||||
- 引用 DWS 构建具体业务主题、指标和报表数据集。
|
||||
- 允许面向使用场景组织字段，但不得反向成为 DWD/DWS 的依赖。
|
||||
|
||||
读取关系保持清晰：DWS 读取 DWD，DM 读取 DWS。DWD 不读取 DWS/DM，DWS 不读取 DM；DWS/DM 的派生结果不得写回 DWD，DM 的派生结果不得写回 DWS。
|
||||
|
||||
## 3. 表命名
|
||||
|
||||
表名由“层级 + ext + 对象类型 + 业务实体”组成：
|
||||
|
||||
```text
|
||||
[<catalog>.]<schema>.<layer>_ext_<object_type>_<business_entity>
|
||||
```
|
||||
|
||||
固定前缀如下：
|
||||
|
||||
| 层级 | 对象 | 表名前缀 |
|
||||
| --- | --- | --- |
|
||||
| DWS | 维度/主数据 | `dws_ext_td_` |
|
||||
| DWS | 事实数据 | `dws_ext_tf_` |
|
||||
| DM | 维度/主数据 | `dm_ext_td_` |
|
||||
| DM | 事实数据 | `dm_ext_tf_` |
|
||||
|
||||
命名规则：
|
||||
|
||||
- `<schema>` 与 `<layer>` 保持一致，例如 `dws.dws_ext_td_xxx`。
|
||||
- `td` 表示维度或主数据，`tf` 表示事实数据。
|
||||
- `<business_entity>` 使用小写 snake_case。
|
||||
- 需要区分来源系统时，将来源放在业务实体开头，例如 `ims_atc_hierarchy`。
|
||||
- `atc`、`nfc`、`ims` 等已形成业务共识的缩写可以保留。
|
||||
|
||||
首批及后续建议映射：
|
||||
|
||||
| 旧表 | 新表 | 类型 |
|
||||
| --- | --- | --- |
|
||||
| `dwd.dwd_ims_atc_hierarchy` | `dws.dws_ext_td_ims_atc_hierarchy` | DWS 维度 |
|
||||
| `dwd.dwd_ims_nfc_hierarchy` | `dws.dws_ext_td_ims_nfc_hierarchy` | DWS 维度 |
|
||||
| `dwd.dwd_ims_td_manufacturer_corp` | `dws.dws_ext_td_ims_manufacturer_corporation` | DWS 维度，后续处理 |
|
||||
| `dwd.dwd_ims_td_pack_property` | `dws.dws_ext_td_ims_pack_property` | DWS 维度，后续处理 |
|
||||
| `dwd.dwd_gnd_pharbers_prov_fact` | `dws.dws_ext_tf_pharbers_province_sales` | DWS 事实，需先确认粒度 |
|
||||
|
||||
## 4. 文件和目录命名
|
||||
|
||||
目录结构统一为：
|
||||
|
||||
@@ -21,63 +82,31 @@ sql/<业务域>/<阶段>/<序号>_<目标表>.sql
|
||||
|
||||
规则：
|
||||
|
||||
- 目录和文件名使用小写 snake_case。
|
||||
- 路径和文件名不使用空格。
|
||||
- 使用两位序号明确 notebook/job 的执行顺序。
|
||||
- 一个脚本只写入一个主要持久化目标。像 `01 dwd_update.sql` 这种多目标脚本，应按目标表和职责拆分。
|
||||
- 目录和文件名使用小写 snake_case，不使用空格。
|
||||
- 目录阶段必须和输出层一致，例如 DWS 脚本放在 `02_dws`。
|
||||
- 使用两位序号明确 notebook/job 执行顺序。
|
||||
- 一个脚本只写入一个主要持久化目标。
|
||||
- 多目标脚本按目标表和职责拆分。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
sql/chpa/01_dwd/01_dwd_ims_atc_hierarchy.sql
|
||||
sql/chpa/02_dws/01_dws_ext_td_ims_atc_hierarchy.sql
|
||||
```
|
||||
|
||||
## 3. 物理表命名
|
||||
|
||||
新表使用以下格式：
|
||||
|
||||
```text
|
||||
[<catalog>.]<分层_schema>.<来源系统>_<对象类型>_<业务实体>[_<限定词>]
|
||||
```
|
||||
|
||||
未启用 Unity Catalog 或依赖默认 catalog 时可以省略 catalog。分层已经由 schema 表达，表名不再重复 `dwd`、`dws` 或 `dm`。
|
||||
|
||||
- 来源系统：如 `ims`、`gnd`、`pharbers`。
|
||||
- 对象类型：`td` 表示维度/主数据，`tf` 表示事实数据。
|
||||
- 业务实体：使用稳定的业务名词，如 `atc_hierarchy`、`pack_property`。
|
||||
- 限定词：按需表达粒度或变体，如 `monthly`、`province`。
|
||||
|
||||
`01` 组表名建议：
|
||||
|
||||
| 现有物理表名 | 推荐规范表名 | 首批处理方式 |
|
||||
| --- | --- | --- |
|
||||
| `dwd.dwd_ims_atc_hierarchy` | `dwd.ims_td_atc_hierarchy` | 保留现名 |
|
||||
| `dwd.dwd_ims_nfc_hierarchy` | `dwd.ims_td_nfc_hierarchy` | 保留现名 |
|
||||
| `dwd.dwd_ims_td_manufacturer_corp` | `dwd.ims_td_manufacturer_corporation` | 后续 review |
|
||||
| `dwd.dwd_ims_td_pack_property` | `dwd.ims_td_pack_property` | 后续 review |
|
||||
| `dwd.dwd_gnd_pharbers_prov_fact` | `dwd.pharbers_tf_province_sales` | 先确认业务粒度 |
|
||||
|
||||
推荐迁移顺序：
|
||||
|
||||
1. 创建规范名称的新表，并用兼容视图暴露旧表名。
|
||||
2. 新旧表并行运行，对比数据结果。
|
||||
3. 在一次受控发布中修改全部下游引用。
|
||||
4. 所有消费者迁移后再移除旧名称兼容视图。
|
||||
|
||||
## 4. 字段命名
|
||||
## 5. 字段命名
|
||||
|
||||
- 新字段使用小写 snake_case。
|
||||
- 标识使用 `_id`，业务编码使用 `_code`，名称或描述使用 `_name`、`_description`。
|
||||
- 日期时间后缀按真实类型使用 `_date`、`_timestamp` 或 `_at`。
|
||||
- `atc`、`nfc`、`prod`、`pack` 等已形成业务共识或受输出契约约束的缩写可以保留。
|
||||
- 纯逻辑重构中不直接修改持久化输出字段名。
|
||||
- 纯逻辑重构中不直接修改已有输出字段契约。
|
||||
|
||||
## 5. SQL 结构和格式
|
||||
## 6. SQL 结构和格式
|
||||
|
||||
脚本统一按以下顺序组织：
|
||||
|
||||
1. Databricks notebook 标记和脚本契约头。
|
||||
2. 带显式目标列的 `INSERT OVERWRITE`。
|
||||
2. 带显式目标列的写入语句。
|
||||
3. 源数据标准化 CTE。
|
||||
4. 业务规则 CTE。
|
||||
5. 按目标表字段顺序显式编写最终 `SELECT`。
|
||||
@@ -86,27 +115,21 @@ sql/chpa/01_dwd/01_dwd_ims_atc_hierarchy.sql
|
||||
|
||||
- SQL 关键字使用大写。
|
||||
- CTE 和别名使用小写 snake_case。
|
||||
- 使用四个空格缩进。
|
||||
- `SELECT` 每行一个字段。
|
||||
- 每个 JOIN 条件单独成行。
|
||||
- 使用 `atc_level_1` 等有业务意义的别名，维护代码中不使用 `t1`、`a` 等无语义别名。
|
||||
- 使用四个空格缩进，`SELECT` 每行一个字段。
|
||||
- 使用有业务意义的别名，不使用 `t1`、`a` 等无语义别名。
|
||||
- 同一作用域出现多个关系时，所有字段都带关系限定符。
|
||||
|
||||
## 6. 写入和数据质量规则
|
||||
## 7. 写入和数据质量
|
||||
|
||||
- 只有可确定性重跑的全量任务可以使用 `INSERT OVERWRITE`。
|
||||
- 不在一个脚本中混合无关的 `UPDATE` 和目标表构建逻辑。
|
||||
- 编码补零等标准化逻辑集中到一个明确的处理阶段，避免在多个任务中重复表达式。
|
||||
- 编码补零等标准化逻辑集中到一个明确阶段。
|
||||
- 每个脚本必须声明预期目标粒度。
|
||||
- 最少验证以下指标：
|
||||
- 新结果与旧结果的总行数；
|
||||
- 声明业务键的重复数；
|
||||
- 必填键的空值数；
|
||||
- 层级关联新增的未匹配记录数。
|
||||
- 最少验证新旧行数、双向差集、业务键重复、必填键空值和层级未匹配数。
|
||||
|
||||
## 7. 首批兼容说明
|
||||
## 8. 首批兼容说明
|
||||
|
||||
ATC 和 NFC 脚本原样保留以下父级编码规则：
|
||||
ATC 和 NFC 脚本保留旧逻辑中的父级编码规则：
|
||||
|
||||
- ATC 2 级关联 1 级：取前 1 位。
|
||||
- ATC 3 级关联 2 级：取前 3 位。
|
||||
@@ -114,6 +137,4 @@ ATC 和 NFC 脚本原样保留以下父级编码规则：
|
||||
- NFC 2 级关联 1 级：取前 1 位。
|
||||
- NFC 3 级关联 2 级：取前 2 位。
|
||||
|
||||
任何口径简化都应先用生产样本验证这些规则。
|
||||
|
||||
首批上线前运行 `validation/chpa/01_dwd/validate_hierarchy_refactor.sql`。新旧双向差集必须为 0，行数必须一致；重复路径和未匹配层级作为业务 review 指标记录，不在未确认阈值前自动判定失败。
|
||||
两个 DWS 脚本执行后运行 `validation/chpa/02_dws/validate_hierarchy_refactor.sql`。新 DWS 输出与旧 DWD 基线的行数必须一致，双向差集必须为 0；重复路径和未匹配层级作为业务 review 指标记录。
|
||||
|
||||
Reference in New Issue
Block a user