为什么注释是硬要求
表注释与字段注释不是可选项，而是元数据采集、字段检索、血缘分析的输入。没有注释的表在元数据平台里等于不可检索，使用者只能去问作者。注释要写业务含义与口径（这个字段从哪来、什么单位、什么过滤条件），不写「字段1」这类占位文字。
基本信息
| 表注释 | 业务主题 + 粒度 + 负责人 |
|---|---|
| 字段注释 | 业务含义 + 单位或口径 |
| 分区字段 | 注明分区时间语义（如业务日期） |
| 禁止 | 占位注释、复制字段名的注释 |
| 用途 | 元数据检索、血缘分析、交接 |
典型使用场景
- 新人接手：靠注释就能读懂表结构与字段口径，不必逐个找人问
- 元数据平台检索：注释参与全文检索，是数据资产被找到的前提
- 建模评审：注释缺失率作为评审清单的一项硬性检查
- 口径对齐：把过滤条件写进注释，避免同名指标各算各的
- 影响面分析：字段注释帮助判断一次上游变更会波及哪些消费方
注释写法示例
注释写法示例
CREATE TABLE dws_trade_store_day (
store_id STRING COMMENT '门店ID，来源 dim_store.store_id',
order_cnt BIGINT COMMENT '支付订单数，按 order_id 去重后计数',
pay_amt DECIMAL(18,2) COMMENT '支付金额，单位元，已剔除取消单'
)
COMMENT '交易主题-门店粒度-日汇总；负责人：data-zhang'
PARTITIONED BY (dt STRING COMMENT '业务日期，按 Asia/Shanghai 切分');各对象该写什么
| 对象 | 必写内容 | 常见反例 |
|---|---|---|
| 表 | 主题、粒度、负责人 | 「临时表」 |
| 度量字段 | 单位与口径 | 「金额」 |
| 比率字段 | 分子与分母 | 「比率」 |
| 布尔字段 | 1 与 0 的含义 | 「是否有效」 |
| 分区字段 | 时间语义与时区 | 「日期」 |
注释缺失率可以做成数据资产巡检指标，按周统计并纳入建模评审；比事后追着补注释更容易落地。
注释与实现不一致比没有注释更危险：使用者会按注释理解数据，等发现口径早就离题很远。逻辑变更时必须同步改注释。