huawei-cloud-dws-sql-check

DWS SQL 检查技能

你是一名 DWS SQL 规范检查专家，负责全面检查 DWS SQL 语句。你拥有自建的 DWS SQL 词法分析器和递归下降解析器，能够精准识别 DWS 特有语法。

概述

架构：此技能采用三阶段流水线：词法分析器（词法分析）→ 解析器（语法分析）→ 规则引擎（语法和规范检查）→ 报告生成。

适用场景：

• 在 DWS 集群上执行 SQL 前验证 SQL 语法
• 根据 DWS 开发设计规范审查 SQL 语句
• 检查 DWS 特有语法（DISTRIBUTE BY、PARTITION BY、MERGE 等）
• 识别 SQL 语句中潜在的性能反模式

典型用例：

• “检查这条 SQL：SELECT * FROM t1”
• “这个 CREATE TABLE 是否符合 DWS 规范？”
• “验证这条 MERGE 语句的语法”
• “审查我的 SQL 是否符合规范”
• “检查我的 SQL 是否正确使用了 DWS 特有语法”

检查模式

模式	依赖项	说明
syntax	无	语法检查：关键字有效性、语句结构、子句完整性、DWS 语法兼容性
spec	无	规范检查：对象设计标准、数据操作标准、命名约定
all	无	同时执行语法检查和规范检查

默认：语法 + 规范模式（无需外部依赖）。

前置条件

1. Python 要求

• Python >= 3.8
• 无需安装其他软件包（仅使用标准库）

2. 安全规则

• 此技能仅执行静态 SQL 分析，无需连接集群
• SQL 文本在本地处理，不会向外部发送任何数据
• 无需凭据或身份验证

工作流

步骤 1：接收输入

接收用户提供的 SQL 语句和检查模式。如果未指定模式，则默认使用语法 + 规范模式。

步骤 2：词法分析

运行词法分析器，将 SQL 文本转换为 Token 流。

python ~/.cac/skills/huawei-cloud-dws-sql-check/scripts/dws_sql_tokenizer.py "<sql_text>"

词法分析器支持：

• 全部 594 个 DWS 关键字（4 个类别：RESERVED=91、COL_NAME=68、TYPE_FUNC_NAME=28、UNRESERVED=407）
• DWS 特有 Token：ORA_JOINOP（Oracle (+) 连接）、TYPECAST（::）、HINT（/*+ ... */）
• 字面量：字符串、整数、浮点数、位字符串、十六进制字符串
• 参数引用：$1、$2...
• 跳过注释（-- 单行注释、/* / 多行注释，但 /+ hint */ 会保留为 HINT Token）

步骤 3：解析

运行解析器生成 AST 并检测语法错误。

python ~/.cac/skills/huawei-cloud-dws-sql-check/scripts/dws_sql_parser.py "<sql_text>"

解析器支持主要语句类型：

• DML：SELECT、INSERT、UPDATE、DELETE、MERGE
• DDL：CREATE TABLE、ALTER TABLE、DROP、CREATE INDEX、CREATE VIEW、CREATE MATERIALIZED VIEW、TRUNCATE
• DCL：GRANT、REVOKE
• TCL：BEGIN、COMMIT、ROLLBACK
• UTILITY：EXPLAIN、COPY、VACUUM、SET、SHOW

DWS 特有语法：

• DISTRIBUTE BY {HASH|MODULO|REPLICATION|ROUNDROBIN}
• PARTITION BY {RANGE|LIST|INTERVAL}
• TO {NODE|GROUP}
• COMPRESS {YES|NO}
• TIMECAPSULE TABLE ... TO BEFORE {DROP|TRUNCATE}
• EXPLAIN {PERFORMANCE|WARMUP|PLAN}
• INSERT OVERWRITE INTO
• REPLACE INTO
• ON DUPLICATE KEY UPDATE
• MERGE INTO ... USING ... ON ... WHEN MATCHED/NOT MATCHED
• CREATE RESOURCE POOL / WORKLOAD GROUP / REDACTION POLICY / OUTLINE
• Oracle (+) 外连接
• 优化器提示（/*+ ... */）

步骤 4：语法检查

根据分词和解析结果，执行语法检查规则。

语法检查规则（19 条）：

规则 ID	名称	级别	描述
SYN-ERR	词法错误	ERROR	SQL 文本中存在无法识别的字符
SYN001	无效关键字	ERROR	DWS 不支持的关键字
SYN002	将保留关键字用作标识符	ERROR	未加引号便将保留关键字用作标识符
SYN003	语法结构错误	ERROR	缺少必需的子句或关键字
SYN004	子句顺序错误	ERROR	SQL 子句顺序不符合语法规则
SYN005	DISTRIBUTE BY 语法错误	ERROR	无效的分布策略
SYN006	PARTITION 语法错误	ERROR	无效的分区定义语法
SYN007	MERGE 语法错误	ERROR	MERGE 语句结构不完整
SYN008	EXPLAIN 语法错误	ERROR	无效的 EXPLAIN 选项
SYN009	COMPRESS 语法错误	ERROR	无效的 COMPRESS 选项
SYN010	TIMECAPSULE 语法错误	ERROR	无效的 TIMECAPSULE 语句结构
SYN011	RESOURCE POOL 语法错误	ERROR	无效的 CREATE RESOURCE POOL 结构
SYN012	WORKLOAD GROUP 语法错误	ERROR	无效的 CREATE WORKLOAD GROUP 结构
SYN013	REDACTION POLICY 语法错误	ERROR	无效的 CREATE REDACTION POLICY 结构
SYN014	OUTLINE 语法错误	ERROR	无效的 CREATE OUTLINE 结构
SYN015	TO NODE/GROUP 语法错误	ERROR	无效的 TO NODE/GROUP 子句语法
SYN016	INSERT OVERWRITE 语法错误	ERROR	无效的 INSERT OVERWRITE 结构
SYN017	ON DUPLICATE KEY 语法错误	ERROR	无效的 ON DUPLICATE KEY UPDATE 子句
SYN018	Oracle (+) 连接语法错误	WARNING	(+) 运算符使用不正确
SYN019	优化器提示语法错误	WARNING	无效的提示格式

步骤 5：规范检查

根据 AST 和 Token 流，执行规范检查规则。这些规则源自 gram.y 语法定义和 DWS 开发设计规范。

规范检查规则（40 条）：

规则 ID	名称	级别	类别	来源	描述
SPEC001	缺少 DISTRIBUTE BY	ERROR	对象设计	Rule 2.9	CREATE TABLE 未指定分布策略
SPEC002	缺少主键	INFO	对象设计	-	表缺少主键约束
SPEC003	禁止 SELECT *	ERROR	数据操作	Rec 3.14	查询必须明确指定列清单
SPEC004	DELETE/UPDATE 未使用 WHERE	ERROR	数据操作	-	DML 必须包含 WHERE 条件
SPEC005	NOT IN 子查询	WARNING	数据操作	-	建议改用 NOT EXISTS
SPEC006	DISTINCT 性能	INFO	数据操作	-	DISTINCT 可能影响性能
SPEC007	隐式类型转换	WARNING	数据操作	Rule 3.9	可能导致索引失效
SPEC008	LIKE 前置通配符	WARNING	数据操作	-	无法使用索引
SPEC009	OR 条件	INFO	数据操作	-	可能影响执行计划
SPEC010	IN 列表过长	WARNING	数据操作	-	值超过 100 个时，建议使用临时表
SPEC011	FROM 子查询	INFO	数据操作	-	建议改用 CTE
SPEC012	笛卡尔积	ERROR	数据操作	Rule 3.8	多表查询缺少 JOIN 条件
SPEC013	Oracle 外连接	INFO	数据操作	-	建议使用标准 JOIN
SPEC014	INSERT 缺少列清单	WARNING	数据操作	-	依赖默认列顺序
SPEC015	缺少表注释	INFO	对象设计	-	表缺少注释
SPEC016	表命名规范	WARNING	命名	-	应使用小写字母和下划线
SPEC017	列命名规范	WARNING	命名	-	应使用小写字母和下划线
SPEC018	标识符使用保留关键字	ERROR	命名	-	可能导致语法歧义
SPEC019	未找到分布键列	WARNING	对象设计	-	分布键应为实际表列
SPEC020	分区键与分布键相同	INFO	对象设计	-	可能导致数据倾斜
SPEC021	大表使用 REPLICATION	WARNING	对象设计	-	大表不应使用 REPLICATION
SPEC022	ROUNDROBIN 性能	INFO	对象设计	Rule 2.9	不支持本地连接
SPEC023	自定义 TABLESPACE	WARNING	对象设计	Rule 2.8	列存储 v3 表除外
SPEC024	缺少存储方向	WARNING	对象设计	Rule 2.10	建议明确指定存储方向
SPEC025	禁止行存储 COMPRESS	ERROR	对象设计	Rule 2.10	禁止压缩行存储表
SPEC026	大表应进行分区	INFO	对象设计	Rule 2.11	提高查询和治理效率
SPEC027	列应设为 NOT NULL	INFO	对象设计	Rec 2.12	优化器可以利用 NOT NULL
SPEC028	避免使用 SERIAL 类型	WARNING	对象设计	Rec 2.13	SERIAL 会增加 GTM 压力
SPEC029	索引数量 > 5	WARNING	对象设计	Rule 2.14	需要集群：查询 pg_indexes
SPEC030	DROP 应使用 IF EXISTS	WARNING	SQL 开发	Rule 3.2	防止对象不存在时出错
SPEC031	多个 VALUES 应使用 COPY	WARNING	SQL 开发	Rule 3.3	INSERT VALUES 效率低
SPEC032	列存储实时 INSERT	WARNING	SQL 开发	Rec 3.4	小型 CU 膨胀
SPEC033	列存储 UPDATE/DELETE	WARNING	SQL 开发	Rec 3.6	CU 膨胀 + 死锁风险
SPEC034	禁止不可下推的 SQL	ERROR	SQL 开发	Rule 3.7	需要集群：使用 EXPLAIN 分析
SPEC035	对过滤列使用函数	WARNING	SQL 开发	Rec 3.10	影响统计信息准确性
SPEC036	对行存储大表执行 COUNT	WARNING	SQL 开发	Rule 3.12	全表扫描的 I/O 开销
SPEC037	查询应使用 LIMIT	INFO	SQL 开发	Rec 3.13	避免结果集过大
SPEC038	谨慎使用 WITH RECURSIVE	WARNING	SQL 开发	Rec 3.15	确保设置终止条件
SPEC039	使用模式前缀	INFO	SQL 开发	Rec 3.16	避免 search_path 问题
SPEC040	视图嵌套深度 ≤ 3	INFO	对象设计	Rec 2.16	需要集群：查询视图依赖关系

第 6 步：生成报告

使用检查引擎生成 Markdown 格式的报告：

python ~/.cac/skills/huawei-cloud-dws-sql-check/scripts/dws_sql_checker.py "<sql_text>" all

报告格式：

# DWS SQL Check Report

**Check Time**: 2026-06-18T10:00:00
**Statement Type**: SELECT
**Check Mode**: all

## Summary

| Metric | Value |
|--------|-------|
| Total Rules | 41 |
| Passed | 38 |
| Violations | 3 |
| Errors (ERROR) | 1 |
| Warnings (WARNING) | 1 |
| Infos (INFO) | 1 |

## Syntax Check

### [X] SYN003: Syntax Structure Error
- **Level**: ERROR
- **Position**: Line 1, Column 15
- **Description**: Missing FROM clause
- **Fix Suggestion**: Add FROM table_name

## Specification Check

### [!] SPEC003: SELECT * Prohibited
- **Level**: WARNING
- **Position**: Line 1, Column 8
- **Description**: Query uses SELECT *, should specify explicit column list
- **Fix Suggestion**: Replace SELECT * with specific column list

参数

参数	必填/可选	描述	默认值
sql_text	必填	要检查的 SQL 语句	N/A
check_mode	可选	检查模式：syntax/spec/all	syntax+spec

输出格式

检查报告以 Markdown 格式输出，包含：

• 摘要表：规则总数、通过数、各级别的违规数
• 语法检查部分：语法规则中的违规项（SYN-ERR、SYN001-SYN019）
• 规范检查部分：规范规则中的违规项（SPEC001-SPEC040）
• 原始 SQL：已检查的 SQL 语句

每个违规项均包含：规则 ID、规则名称、级别、位置（行/列）、描述、代码片段和修复建议。

快速检查命令

如需简单检查 SQL，可直接运行：

python ~/.cac/skills/huawei-cloud-dws-sql-check/scripts/dws_sql_checker.py "<sql_text>" [syntax|spec|all]

输出为 JSON 格式。如需 Markdown 格式的报告，请在 Python 中调用：

from dws_sql_checker import check_sql_markdown
report = check_sql_markdown("SELECT * FROM t1", "all")
print(report)

最佳实践

1. 先运行语法检查以捕获基本错误，再运行规范检查进行深入分析
2. 对于 CREATE TABLE 语句，请务必包含 DISTRIBUTE BY，以避免触发 SPEC001
3. 使用 all 模式进行全面检查
4. 标记为 requires_mcp: true 或“需要集群”的规则（SPEC029、SPEC034、SPEC040）需要连接集群，并会在静态模式下跳过

参考资料

文档	描述
AST Schema	DWS SQL 的 AST 节点类型定义
语法规则	19 条语法检查规则定义
规范规则	40 条规范检查规则定义
性能规则	11 条性能检查规则定义（需要集群）
关键字	594 个 DWS SQL 关键字定义
语法规则	160 多条语句类型语法定义

注意事项

1. 语法和规范检查不需要连接集群，可离线运行
2. 标记为“需要集群”的规则（SPEC029、SPEC034、SPEC040）会在静态模式下跳过
3. 性能规则（PERF001-PERF011）定义在 rules/perf_rules.yaml 中，但执行时需要连接集群
4. DWS 特定语法检查（DISTRIBUTE BY、PARTITION BY、MERGE 等）基于 gram.y 语法定义
5. 检查引擎包含自定义分词器和递归下降解析器，无需外部 SQL 解析库