120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
# Databricks SQL 重构规范
|
|
|
|
## 1. 范围和原则
|
|
|
|
本规范适用于 CHPA Databricks 数仓脚本。第一阶段目标是在不改变业务结果的前提下提高可维护性。
|
|
|
|
- 先保持业务口径，再做性能优化。
|
|
- 每个脚本只负责一个主要目标表。
|
|
- 文件头声明源表、目标表、数据粒度、写入方式和依赖。
|
|
- 持久化写入必须显式列出目标列和查询列，禁止使用 `SELECT *`。
|
|
- 逻辑重构与生产表改名分开实施。
|
|
- 为行数、唯一性、非空约束和未匹配记录建立验证查询或任务检查。
|
|
|
|
## 2. 文件和目录命名
|
|
|
|
目录结构统一为：
|
|
|
|
```text
|
|
sql/<业务域>/<阶段>/<序号>_<目标表>.sql
|
|
```
|
|
|
|
规则：
|
|
|
|
- 目录和文件名使用小写 snake_case。
|
|
- 路径和文件名不使用空格。
|
|
- 使用两位序号明确 notebook/job 的执行顺序。
|
|
- 一个脚本只写入一个主要持久化目标。像 `01 dwd_update.sql` 这种多目标脚本，应按目标表和职责拆分。
|
|
|
|
示例：
|
|
|
|
```text
|
|
sql/chpa/01_dwd/01_dwd_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. 字段命名
|
|
|
|
- 新字段使用小写 snake_case。
|
|
- 标识使用 `_id`，业务编码使用 `_code`，名称或描述使用 `_name`、`_description`。
|
|
- 日期时间后缀按真实类型使用 `_date`、`_timestamp` 或 `_at`。
|
|
- `atc`、`nfc`、`prod`、`pack` 等已形成业务共识或受输出契约约束的缩写可以保留。
|
|
- 纯逻辑重构中不直接修改持久化输出字段名。
|
|
|
|
## 5. SQL 结构和格式
|
|
|
|
脚本统一按以下顺序组织：
|
|
|
|
1. Databricks notebook 标记和脚本契约头。
|
|
2. 带显式目标列的 `INSERT OVERWRITE`。
|
|
3. 源数据标准化 CTE。
|
|
4. 业务规则 CTE。
|
|
5. 按目标表字段顺序显式编写最终 `SELECT`。
|
|
|
|
格式规则：
|
|
|
|
- SQL 关键字使用大写。
|
|
- CTE 和别名使用小写 snake_case。
|
|
- 使用四个空格缩进。
|
|
- `SELECT` 每行一个字段。
|
|
- 每个 JOIN 条件单独成行。
|
|
- 使用 `atc_level_1` 等有业务意义的别名，维护代码中不使用 `t1`、`a` 等无语义别名。
|
|
- 同一作用域出现多个关系时，所有字段都带关系限定符。
|
|
|
|
## 6. 写入和数据质量规则
|
|
|
|
- 只有可确定性重跑的全量任务可以使用 `INSERT OVERWRITE`。
|
|
- 不在一个脚本中混合无关的 `UPDATE` 和目标表构建逻辑。
|
|
- 编码补零等标准化逻辑集中到一个明确的处理阶段，避免在多个任务中重复表达式。
|
|
- 每个脚本必须声明预期目标粒度。
|
|
- 最少验证以下指标：
|
|
- 新结果与旧结果的总行数；
|
|
- 声明业务键的重复数；
|
|
- 必填键的空值数；
|
|
- 层级关联新增的未匹配记录数。
|
|
|
|
## 7. 首批兼容说明
|
|
|
|
ATC 和 NFC 脚本原样保留以下父级编码规则：
|
|
|
|
- ATC 2 级关联 1 级：取前 1 位。
|
|
- ATC 3 级关联 2 级：取前 3 位。
|
|
- ATC 4 级关联 3 级：取前 4 位。
|
|
- NFC 2 级关联 1 级：取前 1 位。
|
|
- NFC 3 级关联 2 级：取前 2 位。
|
|
|
|
任何口径简化都应先用生产样本验证这些规则。
|
|
|
|
首批上线前运行 `validation/chpa/01_dwd/validate_hierarchy_refactor.sql`。新旧双向差集必须为 0，行数必须一致；重复路径和未匹配层级作为业务 review 指标记录，不在未确认阈值前自动判定失败。
|