📄 本页由源文件
rules/SQL_官方规范.mdc自动投影生成（单一权威源）。请勿直接编辑本页。
SQL_官方规范
你是一个专业的SQL助手，所有SQL代码必须严格遵循以下编码规范。
规范等级约定
- 必须（Mandatory）：必须采用
- 推荐（Preferable）：理应采用，但如有特殊情况，可以不采用
命名规范
通用规则
必须（Mandatory）：
- 不允许使用保留关键字，使用一致的、描述意义的命名
- 在命名只使用字母、数字和下划线，不包含空格或其他特殊字符
- 命名以字母开头，不能以数字、下划线开头，不能以下划线结尾
- 不允许在名字中出现连续下划线
- 不允许使用驼峰命名，建议使用下划线分割单词
推荐（Preferable）：
- 尽量不要用拼音，用贴切的英文单词
- 尽量避免使用缩写词，除非这个缩写词是简明易懂、约定俗成的
库命名
必须（Mandatory）：
- 全部小写命名，禁止出现大写
- 数据库名称不要超过30个字符，简洁明了，能够清晰地表达库的用途或内容
推荐（Preferable）：
- 按照业务模块、产品线和访问权限隔离需求，创建不同的数据库
表命名
必须（Mandatory）：
- 全部小写命名，禁止出现大写
- 表名不超过50个字符，简洁、清晰、易懂，能够表达表的用途和内容
推荐（Preferable）：
- 表名符合统一的数仓规范，包括分层、主题域、存储策略、存储周期等信息
- 使用通用的数仓分层（ods、dwd、dws、dim、ads、tmp）做为表前缀
- 表名不能和列名同名
字段命名
必须（Mandatory）：
- 全部小写命名，禁止出现大写
- 字段名不超过32个字符，简洁、清晰、易懂
推荐（Preferable）：
- 建议各表之间相同意义的字段应同名，并且一定使用相同的字段类型
- 尽量给每个字段添加注释，枚举型需指明主要值的含义
- 尽量不要出现uid、pid、cid这样的缩写，字段名尽量做到可以正确理解
编码格式规范
通用规范
必须（Mandatory）：
- 关键字必须保持一致，全部大写或者全部小写，禁止大小写混用
- 每行不超过120个字符，禁止所有SQL代码全部堆在一两行
- 使用4个空格而不是TAB作为1个缩进量，所有的缩进均为1个缩进量的整数倍，同一层级的SQL代码保持一致的缩进量来代表层次结构
- 在等号、不等于号、大于号、大于等于号、小于号、小于等于号前后增加一个空格
- 在逗号后面加一个空格
- 在成对的单引号或双引号前后增加1个空格，除非其在括号中，或其后面是逗号或分号
推荐（Preferable）：
- 建议每个子语句尽量不要超过100行（过长不易维护，且容易出错。若必须可以考虑with写法）
- 下列情况建议换行：
- 对子查询换行
- 代码长度超过120个字符长度时，选择合适的关键字（case when、and、or等）进行换行
- 新起一行编写一个完整的DQL、DDL、DML语句
- 在分号后（分隔语句以提高可读性）
- 将代码分隔成相关联的多个部分，帮助提高大段代码的可读性
代码注释规范
必须（Mandatory）：
- 每一个实现完整统计、可独立运行的SQL语句，均需要增加代码头部注释
- 头部注释必须包括：程序名称、功能描述、创建人/修改人、创建/修改日期
- 使用--开头进行单行注释，使用/.../包围进行多行注释
- 注释应简洁明了，直接说明代码的意图和逻辑，避免冗余，与代码保持一致更新
推荐（Preferable）：
- 代码头部注释中增加目标表、数据源表信息、需求来源、修改历史记录
- 建议每个嵌套子查询在select前添加注释说明该部分代码主要作用
- 任何使用常量、魔法数，或硬编码的地方均要注释
- 为复杂的字符串处理、时间计算、UDF函数等增加注释说明
- 对复杂或特殊的业务统计逻辑增加注释说明
代码缩进规范
必须（Mandatory）：
SELECT子句规范：
- 在关键字select、from、where、group by、having、order by、limit关键字的前后换行
- 在join（包括left join、right join、outer join、inner join）和on关键字的前后面换行
- 在where后面的每一个and前换行
- 显式声明当前查询结果保留的每一个字段名，不要使用select *（select * 影响对代码逻辑的理解，且影响引擎性能和查询效率）
- 在字段列表前后换行，每一行书写一个字段
- 对字段别名，必须显式使用as关键字
- select分层编排，每一层的多个select语句对齐缩进量，下一层select语句增加一级缩进量
JOIN和UNION子语句规范：
- from和join包含的子查询语句，换行后书写左括号（{）和右花括号（}），并保持同一对花括号缩进量一致
- 同一级的join查询，其join和on关键字保持缩进量一致
- 在union或union all的前后换行，前后并列的代码块保持缩进量一致
CASE WHEN子语句规范：
- 每个case when...else..end语句尽量在1行内缩写，如果语句较长时需要换行
- 换行缩写时：case和end关键字与其同级的子语句保持一致的缩进量
- 新起一行并增加一级缩进量缩写when子语句，同一级的when和else语句保持缩进量对齐
- 多个case when进行嵌套时，下一级的case when子语句在上一级的then后换行、增加一级缩进量后缩写
WITH子句规范：
- 在with后换行写as和别名
- 新起一行写左括号（{）和右花括号（}），并保持同一对花括号缩进量一致
- 多个with子查询时，换行写另一个as和别名
推荐（Preferable）：
- SELECT子语句规范：
- 把逗号写在select字段的前面（避免丢逗号，且方便批量编辑）
- JOIN和UNION子语句规范：
- 在union语句前后增加一个空行，用于分割并列的代码块
- 尽量不要用笛卡尔积
- 尽量避免使用union，而是使用union all（前者对结果进行去重，后者不去重）
- 大表关联小表时候使用map join（尽量使用sql hint指定）
- WITH子语句规范：
- 使用with来将模块化、可共用的代码抽取出来，使代码更简洁
- 对with语句子查询的别名应该具有描述性，可被理解
DDL和DML语句规范
必须（Mandatory）：
CREATE语句规范：
- 将create语句和表名写在第一行，换行后书写左括号（{）和右花括号（}）
- 规范化库、表、字段命名
- 每一个表字段独立一行，给每个字段写字段说明comment
- 表注释关键字comment前换行，给表写comment
- 显式声明表的存储格式
ALTER语句规范：
- 将alter语句和表名写在第一行，换行后书写每一种修改操作的语句
INSERT语句规范：
- 将insert语句和表名、插入分区写在第一行，换行后书写DQL语句
推荐（Preferable）：
- CREATE语句规范：
- 非临时表包含表的数仓分层、主题域、存储策略、存储周期等信息
- 数据类型不允许完全使用string类型，以免数据加工环节的数据质量问题无法及时暴露
- 带小数点数据使用double类型（金额也可以使用厘，存bigint），需要注释或字段说明单位
- 字符类数据使用string类型
- mpp引擎需要考虑准确的数据类型，减少内存消耗
- 表存储格式尽量使用parquet、orcfile，同时加上压缩关键字
- 大表需要按规范设置合理的生命周期
- DROP语句规范：
- 尽量避免使用drop语句，需要double check（删数据危险操作）
- ALTER语句规范：
- 谨慎删除列，确保不会影响现有数据和查询
- 修改列类型，确保新类型兼容旧类型，避免数据丢失或类型转换错误
- INSERT语句规范：
- 注意insert和insert overwrite的区别，前者追加数据到表中，后者覆盖原有数据
- 对分区表，insert语句显式声明插入的分区
- insert语句显式指定具体的字段名称，因为数据库的字段数量和顺序可能会被修改
最佳实践要点
- 优先使用规范化的命名，全小写+下划线分割
- 必须为SQL添加完整的头部注释和关键逻辑注释
- 严格按照缩进规范格式化代码，提高可读性
- 避免使用SELECT *，明确指定所需字段
- 合理使用分区和索引，优化查询性能