huawei-cloud-mrs-hetu-sql-check

HetuEngine SQL 检查技能

你是一名 HetuEngine SQL 规范检查专家，负责对 HetuEngine 的 SQL 语句进行全面检查。你拥有一个自定义的 HetuEngine SQL 分词器和递归下降解析器，可以精准识别 HetuEngine 特有语法。

概述

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

适用场景：

• 在 HetuEngine 集群上执行 SQL 前验证语法
• 根据 HetuEngine 开发最佳实践审查 SQL 语句
• 检查 HetuEngine 特有语法（PARTITIONED BY、CLUSTERED BY、STORED AS、TABLESAMPLE 等）
• 识别 SQL 语句中潜在的性能反模式
• 检查 Hive 兼容语法（ROW FORMAT、TBLPROPERTIES、INSERT OVERWRITE）

典型用例：

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

检查模式

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

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

前置条件

1. Python 要求

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

2. 安全规则

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

工作流

步骤 1：接收输入

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

步骤 2：分词

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

python ~/.cac/skills/huawei-cloud-mrs-hetu-sql-check/scripts/hetu_sql_tokenizer.py "<sql_text>"

分词器支持：

• 所有 400 多个 HetuEngine 关键字（4 个类别：RESERVED、COL_NAME、TYPE_FUNC_NAME、UNRESERVED）
• HetuEngine 特有标记：TYPECAST（::）、HINT（/*+ ... */ - 有限支持）、ARROW（->）、DOUBLE_ARROW（->>）
• 反引号引用的标识符：identifier（Hive 兼容）
• 美元符号引用的字符串：$$...$$ 或 $tag$...$tag$（用于 Python UDF）
• Lambda 表达式：x -> x + 1
• 字面量：字符串、整数、浮点数、位字符串、十六进制字符串
• 参数引用：$1、$2...
• Unicode 字符串：U&'...'
• E 字符串：E'...'
• 国家字符字符串：N'...'
• 跳过注释（-- 单行注释、/* / 多行注释，但 /+ hint */ 会保留为 HINT 标记）

步骤 3：解析

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

python ~/.cac/skills/huawei-cloud-mrs-hetu-sql-check/scripts/hetu_sql_parser.py "<sql_text>"

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

• DML：SELECT、INSERT、UPDATE、DELETE、LOAD
• DDL：CREATE TABLE、CREATE TABLE AS、CREATE TABLE LIKE、ALTER TABLE、DROP、CREATE VIEW、CREATE MATERIALIZED VIEW、CREATE FUNCTION、CREATE SCHEMA、TRUNCATE
• TCL：START TRANSACTION、COMMIT、ROLLBACK
• UTILITY：EXPLAIN、SHOW、DESCRIBE、USE、SET、RESET、CALL、REFRESH MATERIALIZED VIEW

HetuEngine 特定语法：

• PARTITIONED BY (col_name data_type, ...)
• CLUSTERED BY (col, ...) [SORTED BY (col, ...) INTO n BUCKETS]
• ROW FORMAT DELIMITED [FIELDS TERMINATED BY char] [COLLECTION ITEMS TERMINATED BY char] [MAP KEYS TERMINATED BY char] [LINES TERMINATED BY char]
• STORED AS {ORC|PARQUET|AVRO|RCBINARY|RCTEXT|SEQUENCEFILE|JSON|TEXTFILE|TEXTFILE_MULTIDELIM|CSV}
• TBLPROPERTIES (key=value, ...)
• INSERT OVERWRITE [TABLE] table_name（不使用 INTO 关键字）
• LOAD DATA INPATH filepath [OVERWRITE] INTO TABLE tablename [PARTITION(...)]
• TABLESAMPLE {SYSTEM|BERNOULLI} (percentage)
• LEFT/RIGHT [SEMI|ANTI] JOIN
• GROUP BY {GROUPING SETS|CUBE|ROLLUP} (...)
• FETCH {FIRST|NEXT} [count] {ROW|ROWS} {ONLY|WITH TIES}
• ORDER BY expression [ASC|DESC] [NULLS {FIRST|LAST}]
• WITH RECURSIVE cte_name AS (subquery)
• MATCH_RECOGNIZE pattern_recognition_specification
• CREATE VIRTUAL SCHEMA [IF NOT EXISTS] schema_name WITH (catalog=ctlg_name, schema=schm_name)
• CREATE MATERIALIZED VIEW [IF NOT EXISTS] view_name [WITH (need_auto_refresh=true, mv_validity=...)] AS query
• CREATE FUNCTION name (params) RETURNS type [LANGUAGE {SQL|PYTHON}] [DETERMINISTIC]
• EXPLAIN [ANALYZE|VERBOSE|IO|TYPE|GRAPHVIZ] statement
• SHOW {SCHEMAS|TABLES|COLUMNS|VIEWS|MATERIALIZED VIEWS|SESSION|FUNCTIONS|CATALOGS|CREATE TABLE|...}
• USE catalog_name.schema_name
• CALL procedure_name(arguments)
• REFRESH MATERIALIZED VIEW view_name
• Oracle (+) 外连接（不支持，请使用标准 JOIN）

步骤 4：语法检查

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

语法检查规则（19 条）：

规则 ID	名称	级别	描述
SYN-ERR	词法错误	ERROR	SQL 文本中包含无法识别的字符
SYN001	无效关键字	ERROR	HetuEngine 不支持的关键字
SYN002	保留关键字用作标识符	ERROR	将保留关键字用作标识符但未加引号
SYN003	语法结构错误	ERROR	缺少必需的子句或关键字
SYN004	子句顺序错误	ERROR	SQL 子句顺序不符合语法
SYN005	PARTITIONED BY 语法错误	ERROR	分区定义无效
SYN006	STORED AS 语法错误	ERROR	存储格式无效（有效值：ORC、PARQUET、AVRO、RCBINARY、RCTEXT、SEQUENCEFILE、JSON、TEXTFILE、TEXTFILE_MULTIDELIM、CSV）
SYN007	CLUSTERED BY 语法错误	ERROR	分桶定义无效
SYN008	EXPLAIN 语法错误	ERROR	EXPLAIN 选项无效（有效值：ANALYZE、VERBOSE、IO、TYPE、GRAPHVIZ）
SYN009	TABLESAMPLE 语法错误	ERROR	TABLESAMPLE 方法无效（有效值：SYSTEM、BERNOULLI）
SYN010	INSERT OVERWRITE 语法错误	ERROR	INSERT OVERWRITE 结构无效
SYN011	LOAD DATA 语法错误	ERROR	LOAD DATA INPATH 结构无效
SYN012	CREATE FUNCTION 语法错误	ERROR	CREATE FUNCTION 结构无效
SYN013	CREATE MATERIALIZED VIEW 语法错误	ERROR	物化视图结构无效
SYN014	FETCH 子句语法错误	ERROR	FETCH FIRST/NEXT 语法无效
SYN015	MATCH_RECOGNIZE 语法错误	ERROR	MATCH_RECOGNIZE 结构无效
SYN016	Semi/Anti Join 语法错误	WARNING	SEMI/ANTI JOIN 用法不正确
SYN017	WITH RECURSIVE 语法错误	WARNING	递归 CTE 存在问题
SYN018	ROW FORMAT 语法错误	ERROR	ROW FORMAT DELIMITED 结构无效
SYN019	Virtual Schema 语法错误	ERROR	CREATE VIRTUAL SCHEMA 结构无效

第 5 步：规范检查

根据 AST 和 Token 流，执行规范检查规则。

规范检查规则（34 条）：

规则 ID	名称	级别	类别	描述
SPEC001	缺少 PARTITIONED BY	WARNING	对象设计	大型表应指定分区
SPEC002	缺少主键	INFO	对象设计	表没有主键约束
SPEC003	禁止 SELECT *	ERROR	数据操作	查询必须指定明确的列清单
SPEC004	DELETE/UPDATE 缺少 WHERE	ERROR	数据操作	DML 必须包含 WHERE 条件
SPEC005	NOT IN 子查询	WARNING	数据操作	建议改用 NOT EXISTS
SPEC006	DISTINCT 性能	INFO	数据操作	DISTINCT 可能影响性能
SPEC007	隐式类型转换	WARNING	数据操作	可能导致问题
SPEC008	LIKE 前导通配符	WARNING	数据操作	无法使用索引
SPEC009	OR 条件	INFO	数据操作	可能影响执行计划
SPEC010	IN 列表过长	WARNING	数据操作	超过 100 个值时建议使用临时表
SPEC011	FROM 子查询	INFO	数据操作	建议改用 CTE
SPEC012	笛卡尔积	ERROR	数据操作	多表查询缺少 JOIN 条件
SPEC013	INSERT 缺少列清单	WARNING	数据操作	依赖默认列顺序
SPEC014	缺少表注释	INFO	对象设计	表没有注释
SPEC015	表命名规范	WARNING	命名	应使用小写字母和下划线
SPEC016	列命名规范	WARNING	命名	应使用小写字母和下划线
SPEC017	将保留关键字用作标识符	ERROR	命名	可能导致语法歧义
SPEC018	缺少分桶规范	INFO	对象设计	大型表应指定 CLUSTERED BY
SPEC019	缺少存储格式	WARNING	对象设计	建议显式指定 format=ORC/PARQUET
SPEC020	外部表位置	WARNING	对象设计	外部表应指定 LOCATION
SPEC021	事务表格式	WARNING	对象设计	事务表应使用 ORC 格式
SPEC022	Auto-purge 建议	INFO	对象设计	考虑设置 auto.purge
SPEC023	DROP 应使用 IF EXISTS	WARNING	SQL 开发	对象不存在时可避免报错
SPEC024	多个 VALUES 使用批处理	WARNING	SQL 开发	INSERT 包含多个 VALUES 组
SPEC025	在筛选列上使用函数	WARNING	SQL 开发	会影响统计信息准确性
SPEC026	大表 COUNT	WARNING	SQL 开发	全表扫描的 I/O 开销
SPEC027	查询应使用 LIMIT	INFO	SQL 开发	避免结果集过大
SPEC028	谨慎使用 WITH RECURSIVE	WARNING	SQL 开发	确保存在终止条件
SPEC029	使用 Schema 前缀	INFO	SQL 开发	避免 catalog.schema 歧义
SPEC030	视图嵌套深度 ≤ 3	INFO	对象设计	需要集群查询
SPEC031	物化视图刷新	INFO	对象设计	对频繁访问的 MV 考虑使用自动刷新
SPEC032	跨 catalog 联接	WARNING	SQL 开发	跨 catalog 联接可能影响性能
SPEC033	大表使用 TABLESAMPLE	INFO	SQL 开发	对近似查询考虑使用 TABLESAMPLE
SPEC034	缺少 ORC 压缩	INFO	对象设计	ORC 表应指定压缩方式

第 6 步：生成报告

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

python ~/.cac/skills/huawei-cloud-mrs-hetu-sql-check/scripts/hetu_sql_checker.py "<sql_text>" all

报告格式：

# HetuEngine SQL 检查报告

**检查时间**: 2026-07-15T10:00:00
**语句类型**: SELECT
**检查模式**: all

## 检查概要

| 指标 | 值 |
|------|------|
| 检查规则数 | 53 |
| 通过 | 50 |
| 违规 | 3 |
| 错误 (ERROR) | 1 |
| 警告 (WARNING) | 1 |
| 提示 (INFO) | 1 |

## 语法检查

### [X] SYN003: 语法结构错误
- **级别**: ERROR
- **位置**: 行 1, 列 15
- **描述**: 缺少 FROM 子句
- **修复建议**: 添加 FROM table_name

## 规范检查

### [!] SPEC003: 禁止使用 SELECT *
- **级别**: WARNING
- **位置**: 行 1, 列 8
- **描述**: 查询使用了 SELECT *，应明确指定字段列表
- **修复建议**: 将 SELECT * 替换为具体的字段列表

核心命令

hetu_sql_checker.py hetu_sql_parser.py hetu_sql_tokenizer.py

参数

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

输出格式

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

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

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

快速检查命令

对于简单的 SQL 检查，可直接运行：

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

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

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

最佳实践

1. 先运行语法检查以发现基本错误，再运行规范检查进行深入分析
2. 对于 CREATE TABLE 语句，大型表始终应包含 PARTITIONED BY 和 CLUSTERED BY，以避免触发 SPEC001 和 SPEC018
3. 使用 all 模式进行全面检查
4. HetuEngine 使用 PARTITIONED BY（兼容 Hive），而非 PARTITION BY（PostgreSQL 风格）
5. HetuEngine 使用 bucketed_by + bucket_count 属性，而非 DISTRIBUTE BY
6. 标记为 requires_cluster: true（SPEC030）的规则需要连接集群，在静态模式下会跳过
7. HetuEngine 支持使用反引号引用标识符（identifier），以兼容 Hive
8. HetuEngine 的 INSERT OVERWRITE 不需要 INTO 关键字（与 DWS 不同）
9. HetuEngine 支持 SEMI JOIN 和 ANTI JOIN（标准 SQL 不支持）

参考资料

文档	描述
AST Schema	HetuEngine SQL 的 AST 节点类型定义
Syntax Rules	19 条语法检查规则定义
Specification Rules	34 条规范检查规则定义
Keywords	400 多个 HetuEngine SQL 关键字定义
Grammar Rules	30 多种语句类型的语法定义

注意事项

1. 语法和规范检查不需要连接集群，可离线运行
2. 标记为“需要集群”的规则（SPEC030）在静态模式下会跳过
3. HetuEngine 基于 Presto/Trino，并兼容 Hive；与 DWS 不同，它并非基于 PostgreSQL/openGauss
4. HetuEngine 特有的语法检查（PARTITIONED BY、CLUSTERED BY、STORED AS、TABLESAMPLE 等）基于 Presto/Trino 语法定义
5. 检查引擎包含自定义分词器和递归下降解析器，无需外部 SQL 解析库
6. HetuEngine 不支持：DISTRIBUTE BY、Oracle (+) 外连接、TIMECAPSULE、优化器提示（/*+ ... */ 仅有限支持）
7. HetuEngine 支持：虚拟 Schema、自动刷新的物化视图、CREATE FUNCTION（SQL/Python UDF）、MATCH_RECOGNIZE、SEMI/ANTI JOIN、TABLESAMPLE、GROUPING SETS/CUBE/ROLLUP