huawei-cloud-doris-sql-check

Doris SQL 检查技能

你是一名 Apache Doris SQL 规范检查专家，负责全面检查 Apache Doris SQL 语句（基于 Doris 3.1.4 源代码）。你拥有自定义构建的 Doris SQL 分词器和递归下降解析器，可根据 Nereids ANTLR4 语法（DorisLexer.g4 / DorisParser.g4）精准识别 Doris 特有语法。

概述

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

适用场景：

• 在 Doris 集群（FE/BE）上执行 SQL 前验证语法
• 根据 Apache Doris 开发最佳实践审查 SQL 语句
• 检查 Doris 特有语法（DISTRIBUTED BY HASH/RANDOM、PARTITION BY RANGE/LIST/AUTO、BUCKETS、PROPERTIES、ENGINE、DUPLICATE/AGGREGATE/UNIQUE KEY、INSERT OVERWRITE TABLE、LOAD LABEL、ROUTINE LOAD、EXPORT、MTMV、BACKUP/RESTORE SNAPSHOT、ADMIN SET/SHOW、CANCEL、KILL、TABLESAMPLE、OUTFILE、Hint /*+ /、全文搜索 MATCH_、COLOCATE GROUP）
• 识别 Doris SQL 语句中潜在的性能反模式

典型用例：

• “检查这段 Doris SQL：SELECT * FROM t1”
• “这个 CREATE TABLE 是否符合 Doris 规范（DISTRIBUTED BY、KEY 模型、PARTITION）？”
• “验证这条 INSERT OVERWRITE TABLE 语句的语法”
• “审查我的 Doris SQL 是否符合规范”
• “检查我的 SQL 是否正确使用了 Doris 特有语法（MTMV、LOAD、EXPORT）”
• “验证 BACKUP/RESTORE SNAPSHOT 语法”
• “检查我的 ROUTINE LOAD 作业定义”

检查模式

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

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

先决条件

1. Python 要求

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

2. 安全规则

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

工作流

步骤 1：接收输入

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

步骤 2：分词

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

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

分词器支持：

• 全部 504 个 Doris 关键字（来自 DorisLexer.g4 中 --DORIS-KEYWORD-LIST-START 和 --DORIS-KEYWORD-LIST-END 之间的内容）
• Doris 特有 Token：HINT（/*+ ... */）、BACKQUOTED（`ident`）、ARROW（->）、NSEQ（<=> 空值安全相等）、EQ（= 或 ==）、NEQ（<> 或 !=）、LTE（<= 或 !>）、GTE（>= 或 !<）、DOUBLEPIPES（||）、LOGICALAND（&&）、LOGICALNOT（!）
• 字面量：字符串（'...' / "..."）、整数、小数、长整数（123L）、短整数（123S）、微整数（123Y）、大精度小数（123BD）、指数
• 反引号标识符：`table_name`（Doris 风格，优先于双引号）
• 跳过注释（-- 单行注释、/* */ 多行注释，但保留 /*+ hint */ 作为 HINT Token）
• 全文搜索运算符：MATCH_ALL、MATCH_ANY、MATCH_PHRASE、MATCH_PHRASE_PREFIX、MATCH_PHRASE_EDGE、MATCH_REGEXP、MATCH_NAME、MATCH_NAME_GLOB

步骤 3：解析

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

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

解析器支持主要的 Doris 语句类型（基于 DorisParser.g4）：

• DML：SELECT（含 CTE、集合运算、窗口函数、TABLESAMPLE）、INSERT INTO/OVERWRITE TABLE、UPDATE、DELETE、LOAD（BROKER LOAD）、EXPORT、COPY INTO、TRUNCATE
• DDL：CREATE TABLE（含 DISTRIBUTED BY、PARTITION BY、KEY 模型、ENGINE、PROPERTIES）、CREATE TABLE LIKE、CREATE VIEW、CREATE MTMV（多表物化视图）、CREATE INDEX（BITMAP/NGRAM_BF/INVERTED）、ALTER TABLE（ADD/MODIFY/DROP/RENAME COLUMN、ADD/DROP PARTITION、ADD/DROP INDEX、ROLLUP、TAG/BRANCH）、DROP TABLE/VIEW/INDEX、CREATE CATALOG、CREATE DATABASE、CREATE USER/ROLE、CREATE RESOURCE、CREATE STAGE、CREATE ENCRYPTKEY、CREATE JOB、CREATE ROW POLICY、CREATE SQL_BLOCK_RULE、CREATE STORAGE VAULT/POLICY、CREATE WORKLOAD GROUP/POLICY
• DCL：GRANT/REVOKE（表/资源/角色权限）
• TCL：BEGIN/START TRANSACTION、COMMIT、ROLLBACK
• 实用工具：EXPLAIN（PARSED/ANALYZED/REWRITTEN/LOGICAL/OPTIMIZED/PHYSICAL/SHAPE/MEMO/DISTRIBUTED/ALL、VERBOSE/TREE/GRAPH/PLAN）、SET（变量/选项）、SHOW（50 多种变体）、DESC/DESCRIBE、ADMIN SET/SHOW（副本、前端配置、tablet 诊断、垃圾、TDE）、KILL（CONNECTION/QUERY）、CANCEL（LOAD/EXPORT/ALTER TABLE/BACKUP/RESTORE/WARM UP）、BACKUP/RESTORE SNAPSHOT、RECOVER（DATABASE/TABLE/PARTITION）、CLEAN（LABEL/PROFILE/QUERY STATS）、INSTALL/UNINSTALL PLUGIN、LOCK/UNLOCK TABLES、WARM UP、SYNC、HELP、CALL PROCEDURE

Doris 专属语法：

• DISTRIBUTED BY {HASH(cols) | RANDOM} (BUCKETS n | AUTO)?
• PARTITION BY (RANGE | LIST)? ... (AUTO)?（自动分区、步进分区、小于分区、固定分区、列表分区）
• (DUPLICATE | AGGREGATE | UNIQUE) KEY (cols) (CLUSTER BY cols)?
• ENGINE = olap | mysql | elasticsearch | hive | hudi | iceberg | jdbc | ...
• PROPERTIES ('key'='value', ...)
• INSERT OVERWRITE TABLE ...
• LOAD LABEL ... (DATA INFILE (...) INTO TABLE ...)
• CREATE ROUTINE LOAD ... FROM type (...)
• EXPORT TABLE ... TO ...
• BACKUP SNAPSHOT ... TO repo (ON|EXCLUDE (...))?
• RESTORE SNAPSHOT ... FROM repo (ON|EXCLUDE (...))?
• EXPLAIN {PARSED|ANALYZED|REWRITTEN|LOGICAL|OPTIMIZED|PHYSICAL|SHAPE|MEMO|DISTRIBUTED|ALL} [VERBOSE|TREE|GRAPH|PLAN] [PROCESS]
• CREATE MATERIALIZED VIEW ... (DUPLICATE KEY ...)? PARTITION BY ... DISTRIBUTED BY ... AS query
  • BUILD [IMMEDIATE|DEFERRED]、REFRESH [COMPLETE|AUTO]、ON [MANUAL|SCHEDULE|COMMIT]
• TABLESAMPLE (...) (REPEATABLE n)?
• WITH cte_name AS (...)（CTE；Doris 不要求显式使用 RECURSIVE 关键字）
• 窗口函数：OVER (PARTITION BY ... ORDER BY ... ROWS/RANGE ...)
• OUTFILE 'path' (FORMAT AS ...)? (PROPERTIES (...))?
• 提示：/*+ hint_name(...) */ 和 [hint_name] 关系提示
• ALTER COLOCATE GROUP name SET (...)
• 全文搜索：col MATCH_ALL '...'、MATCH_PHRASE、MATCH_PHRASE_PREFIX、MATCH_PHRASE_EDGE、MATCH_ANY、MATCH_REGEXP
• 聚合并集：HLL_UNION、BITMAP_UNION、QUANTILE_UNION、REPLACE_IF_NOT_NULL
• Doris 数据类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、BOOLEAN、FLOAT、DOUBLE、DATE、DATETIME、DATEV2、DATETIMEV2、DATEV1、DATETIMEV1、BITMAP、QUANTILE_STATE、HLL、AGG_STATE、STRING、JSON、JSONB、TEXT、VARCHAR、CHAR、DECIMAL、DECIMALV2、DECIMALV3、IPV4、IPV6、ARRAY、MAP、STRUCT、VARIANT

步骤 4：语法检查

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

语法检查规则（34 条）：

规则 ID	名称	级别	描述
SYN-ERR	词法错误	ERROR	SQL 文本中包含无法识别的字符
SYN001	无效关键字	ERROR	Doris 不支持的关键字（不在 504 个关键字列表中）
SYN002	将保留关键字用作标识符	ERROR	未使用反引号将保留关键字用作标识符
SYN003	语法结构错误	ERROR	缺少必需的子句或关键字
SYN004	子句顺序错误	ERROR	SQL 子句顺序不符合语法
SYN005	DISTRIBUTED BY 语法错误	ERROR	无效的分布策略（仅支持 HASH/RANDOM）
SYN006	PARTITION BY 语法错误	ERROR	无效的分区定义（RANGE/LIST/AUTO）
SYN007	BUCKETS 语法错误	ERROR	无效的 BUCKETS 子句（必须为 INTEGER 或 AUTO）
SYN008	EXPLAIN planType 语法错误	ERROR	无效的 EXPLAIN 计划类型（PARSED/ANALYZED/REWRITTEN/LOGICAL/OPTIMIZED/PHYSICAL/SHAPE/MEMO/DISTRIBUTED/ALL）
SYN009	KEY 模型语法错误	ERROR	无效的数据模型（DUPLICATE/AGGREGATE/UNIQUE KEY）
SYN010	PROPERTIES 语法错误	ERROR	PROPERTIES 子句结构无效
SYN011	ENGINE 语法错误	ERROR	ENGINE 子句无效
SYN012	INSERT OVERWRITE 语法错误	ERROR	INSERT OVERWRITE TABLE 结构无效
SYN013	LOAD 语法错误	ERROR	LOAD LABEL / BROKER LOAD 结构无效
SYN014	ROUTINE LOAD 语法错误	ERROR	CREATE ROUTINE LOAD 结构无效
SYN015	EXPORT 语法错误	ERROR	EXPORT TABLE ... TO 结构无效
SYN016	BACKUP/RESTORE SNAPSHOT 语法错误	ERROR	BACKUP/RESTORE SNAPSHOT 结构无效
SYN017	CREATE MTMV 语法错误	ERROR	CREATE MATERIALIZED VIEW 结构无效
SYN018	CREATE CATALOG 语法错误	ERROR	CREATE CATALOG 结构无效
SYN019	CREATE USER/ROLE 语法错误	ERROR	CREATE USER/ROLE 结构无效
SYN020	CREATE ROW POLICY 语法错误	ERROR	CREATE ROW POLICY 结构无效
SYN021	CREATE SQL_BLOCK_RULE 语法错误	ERROR	CREATE SQL_BLOCK_RULE 结构无效
SYN022	CREATE STAGE 语法错误	ERROR	CREATE STAGE 结构无效
SYN023	CREATE JOB 语法错误	ERROR	CREATE JOB ON SCHEDULE 结构无效
SYN024	CREATE ENCRYPTKEY 语法错误	ERROR	CREATE ENCRYPTKEY 结构无效
SYN025	ADMIN SET/SHOW 语法错误	ERROR	ADMIN 语句结构无效
SYN026	CANCEL 语法错误	ERROR	CANCEL 语句无效（LOAD/EXPORT/ALTER/BACKUP/RESTORE/WARM UP）
SYN027	KILL 语法错误	ERROR	KILL（CONNECTION/QUERY）语句无效
SYN028	TABLESAMPLE 语法错误	ERROR	TABLESAMPLE 子句无效（PERCENT/ROWS、REPEATABLE）
SYN029	OUTFILE 语法错误	ERROR	OUTFILE 子句无效（FORMAT AS、PROPERTIES）
SYN030	Hint 语法错误	WARNING	Hint 格式无效（必须为 /*+ name(...) */ 或 [name]）
SYN031	全文 MATCH 语法错误	ERROR	MATCH_ALL/MATCH_ANY/MATCH_PHRASE/MATCH_REGEXP 用法无效
SYN032	COLOCATE GROUP 语法错误	ERROR	ALTER COLOCATE GROUP 结构无效
SYN033	GRANT/REVOKE 语法错误	ERROR	GRANT/REVOKE 权限结构无效

步骤 5：规范检查

基于 AST 和 Token 流，执行规范检查规则。规则源自 DorisParser.g4 语法定义和 Apache Doris 开发最佳实践。

规范检查规则（46 条）：

规则 ID	名称	级别	类别	描述
SPEC001	缺少 DISTRIBUTED BY	ERROR	对象设计	CREATE TABLE 未指定分布策略（Doris 要求使用 DISTRIBUTED BY HASH 或 RANDOM）
SPEC002	缺少 ENGINE	INFO	对象设计	CREATE TABLE 未显式指定 ENGINE（默认为 OLAP）
SPEC003	禁止使用 SELECT *	ERROR	数据操作	查询必须显式指定列清单
SPEC004	DELETE/UPDATE 未使用 WHERE	ERROR	数据操作	DML 必须包含 WHERE 条件
SPEC005	NOT IN 子查询	WARNING	数据操作	建议使用 NOT EXISTS 或 LEFT JOIN ... IS NULL
SPEC006	DISTINCT 性能	INFO	数据操作	DISTINCT 可能影响性能
SPEC007	隐式类型转换	WARNING	数据操作	可能导致索引/zone-map 失效
SPEC008	LIKE 前置通配符	WARNING	数据操作	无法使用 zone-map 或索引
SPEC009	OR 条件	INFO	数据操作	可能影响执行计划
SPEC010	IN 列表过长	WARNING	数据操作	值超过 1000 个时，建议使用临时表
SPEC011	FROM 子查询	INFO	数据操作	建议改用 CTE
SPEC012	笛卡尔积	ERROR	数据操作	多表查询缺少 JOIN 条件
SPEC013	INSERT 缺少列清单	WARNING	数据操作	依赖默认列顺序
SPEC014	缺少表注释	INFO	对象设计	表未设置 COMMENT
SPEC015	表命名规范	WARNING	命名	应使用小写字母和下划线
SPEC016	列命名规范	WARNING	命名	应使用小写字母和下划线
SPEC017	标识符使用保留关键字	ERROR	命名	可能导致语法歧义
SPEC018	未找到分布键列	WARNING	对象设计	分布键应为实际表列
SPEC019	分区键与分布键相同	INFO	对象设计	可能导致数据倾斜
SPEC020	缺少 KEY 模型定义	INFO	对象设计	建议显式指定 DUPLICATE/AGGREGATE/UNIQUE KEY
SPEC021	大表应设置分区	INFO	对象设计	提升查询和治理效率
SPEC022	BUCKETS 数量建议	INFO	对象设计	根据表大小选择合适的分桶数量
SPEC023	列应设置 NOT NULL	INFO	对象设计	优化器可以利用 NOT NULL
SPEC024	DROP 应使用 IF EXISTS	WARNING	SQL 开发	对象不存在时避免报错
SPEC025	INSERT 多组 VALUES	WARNING	SQL 开发	多组 VALUES 效率低；请使用 STREAM LOAD / BROKER LOAD
SPEC026	列存实时 INSERT	WARNING	SQL 开发	频繁向 Doris（列式存储）执行小批量 INSERT 会造成压实压力
SPEC027	频繁执行 UPDATE/DELETE	WARNING	SQL 开发	Doris 的 UPDATE/DELETE 成本高（读-合并-写）
SPEC028	对过滤列使用函数	WARNING	SQL 开发	影响统计信息准确性和 zone-map 使用
SPEC029	大表 COUNT	WARNING	SQL 开发	全表扫描的 I/O 成本
SPEC030	查询应使用 LIMIT	INFO	SQL 开发	避免结果集过大
SPEC031	CTE 递归安全性	WARNING	SQL 开发	确保递归 CTE 有终止条件
SPEC032	使用 Catalog/DB 前缀	INFO	SQL 开发	避免多 Catalog 场景下产生歧义
SPEC033	视图嵌套深度 ≤ 3	INFO	对象设计	需要集群：查询视图依赖关系
SPEC034	索引数量 > 5	WARNING	对象设计	需要集群：查询表索引
SPEC035	禁止使用不可下推的 SQL	ERROR	SQL 开发	需要集群：执行 EXPLAIN 分析
SPEC036	BITMAP/HLL 列需要聚合类型	WARNING	对象设计	BITMAP/HLL 列应指定 BITMAP_UNION/HLL_UNION
SPEC037	重复复杂查询应使用 MTMV	INFO	对象设计	对于重复的聚合查询，建议使用 MTMV
SPEC038	避免频繁使用 OUTFILE 导出	INFO	SQL 开发	大规模导出请使用 EXPORT 或 broker
SPEC039	VARCHAR 长度应显式指定	WARNING	对象设计	避免 VARCHAR 用于大字符串时不指定长度
SPEC040	DECIMAL 精度应显式指定	WARNING	对象设计	使用 DECIMAL(p,s) 或 DECIMALV3(p,s)，避免使用不带参数的 DECIMAL
SPEC041	过度使用 COUNT(DISTINCT)	ERROR	复杂查询限制	COUNT(DISTINCT) 次数 > 5，可能导致性能严重下降
SPEC042	禁止使用 NOT IN 子查询	ERROR	复杂查询限制	NOT IN 子查询会导致全表扫描和性能严重下降；请使用 NOT EXISTS 或 LEFT JOIN
SPEC043	JOIN 过多	ERROR	复杂查询限制	JOIN 数量 > 20，可能导致查询计划不稳定和内存使用量过高
SPEC044	UNION ALL 过多	ERROR	复杂查询限制	UNION ALL 数量 > 20，可能导致计划复杂和资源消耗过高
SPEC045	子查询嵌套过深	ERROR	复杂查询限制	子查询嵌套深度 > 20，可能导致解析和执行性能严重问题
SPEC046	SQL 语句过长	ERROR	复杂查询限制	SQL 文本长度 > 2MB，可能导致解析超时或内存使用量过高

步骤 6：生成报告

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

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

报告格式：

# Doris SQL Check Report

**Check Time**: 2026-07-17T10:00:00
**Statement Type**: SELECT
**Check Mode**: all

## Summary

| Metric | Value |
|--------|-------|
| Total Rules | 74 |
| Passed | 71 |
| 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

核心命令

doris_sql_checker.py doris_sql_parser.py doris_sql_tokenizer.py

参数

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

输出格式

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

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

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

快速检查命令

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

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

输出为 JSON 格式。要生成 Markdown 格式的报告，请在 Python 中调用：

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

最佳实践

1. 先运行语法检查以发现基本错误，再运行规范检查进行深入分析
2. 对于 CREATE TABLE 语句，务必包含 DISTRIBUTED BY HASH(分布键) 或 DISTRIBUTED BY RANDOM，以避免触发 SPEC001
3. 对于 Doris 表，明确指定 KEY 模型（DUPLICATE KEY/AGGREGATE KEY/UNIQUE KEY）
4. 使用 all 模式进行全面检查
5. 标记为 requires_mcp: true 或 "Requires cluster" 的规则（SPEC033、SPEC034、SPEC035）需要连接集群，在静态模式下会跳过
6. Doris 不支持 MERGE INTO ... WHEN MATCHED 或 ON DUPLICATE KEY UPDATE——这些会被标记为语法错误
7. Doris 标识符使用反引号（`），而非双引号——使用双引号表示标识符会触发警告
8. 对于大型数据加载，优先使用 STREAM LOAD / BROKER LOAD / ROUTINE LOAD，而非多行 INSERT VALUES（SPEC025）

参考资料

文档	描述
AST Schema	Doris SQL 的 AST 节点类型定义
Syntax Rules	34 条语法检查规则定义
Specification Rules	40 条规范检查规则定义
Performance Rules	11 条性能检查规则定义（需要集群）
Keywords	504 个 Doris SQL 关键字定义（来自 DorisLexer.g4）
Grammar Rules	100 多条 Doris 语句类型语法定义（来自 DorisParser.g4）

备注

1. 语法和规范检查不需要连接集群，可离线运行
2. 标记为“需要集群”的规则（SPEC033、SPEC034、SPEC035）在静态模式下会跳过
3. 性能规则（PERF001-PERF011）定义在 rules/perf_rules.yaml 中，但执行时需要连接集群（EXPLAIN ANALYZE、information_schema.tables、backends 等系统表）
4. Doris 特有语法检查（DISTRIBUTED BY、PARTITION BY、BUCKETS、PROPERTIES、ENGINE、DUPLICATE/AGGREGATE/UNIQUE KEY、INSERT OVERWRITE、LOAD、EXPORT、MTMV、BACKUP/RESTORE、ADMIN、CANCEL、KILL、TABLESAMPLE、OUTFILE、Hint、MATCH、COLOCATE GROUP）基于 Doris 3.1.4 源码中的 DorisParser.g4（Nereids ANTLR4 语法）
5. 检查引擎包含自定义分词器和递归下降解析器，无需外部 SQL 解析库（无需 ANTLR 运行时）
6. 版本兼容性：此技能基于 Doris 3.1.4 语法。Doris 2.1.x / 3.0.x / 3.1.x / 4.x 的大多数语法结构使用相同的 Nereids 语法；较新的语法可能存在细微差异（例如，4.x 增加了新功能）。依赖特定规则前，请先根据集群版本进行验证。