huawei-cloud-mrs-hetu-sql-check

HetuEngine SQL チェック スキル

HetuEngine SQL 仕様のチェックを専門とし、HetuEngine 用 SQL 文を包括的にチェックします。HetuEngine 固有の構文を正確に識別できる、独自開発の HetuEngine SQL トークナイザーと再帰下降パーサーを備えています。

概要

アーキテクチャ：このスキルでは、トークナイザー（字句解析）→ パーサー（構文解析）→ ルールエンジン（構文と仕様のチェック）→ レポート生成という3段階のパイプラインを使用します。

適用シナリオ：

• 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 テキストをトークンストリームに変換します。

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 用）
• ラムダ式：x -> x + 1
• リテラル：文字列、整数、浮動小数点数、ビット文字列、16進文字列
• パラメーター参照：$1、$2...
• Unicode 文字列：U&'...'
• E 文字列：E'...'
• 各国語文字列：N'...'
• コメントのスキップ（-- 1行コメント、/* / 複数行コメント。ただし /+ 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	セミ／アンチジョイン構文エラー	WARNING	SEMI/ANTI JOIN の使用方法が正しくありません
SYN017	WITH RECURSIVE 構文エラー	WARNING	再帰的な CTE に問題があります
SYN018	ROW FORMAT 構文エラー	ERROR	ROW FORMAT DELIMITED の構造が無効です
SYN019	仮想スキーマ構文エラー	ERROR	CREATE VIRTUAL SCHEMA の構造が無効です

ステップ 5：仕様チェック

AST とトークンストリームに基づいて、仕様チェックルールを実行します。

仕様チェックルール（34 件）：

ルール ID	名前	レベル	カテゴリ	説明
SPEC001	PARTITIONED BY の指定漏れ	WARNING	オブジェクト設計	大規模テーブルにはパーティションを指定する必要があります
SPEC002	主キーの指定漏れ	INFO	オブジェクト設計	主キー制約のないテーブルです
SPEC003	SELECT * の禁止	ERROR	データ操作	クエリでは明示的な列リストを指定する必要があります
SPEC004	WHERE のない DELETE/UPDATE	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 開発	VALUES グループが多い INSERT が対象です
SPEC025	フィルター列での関数使用	WARNING	SQL 開発	統計情報の精度に影響します
SPEC026	大規模テーブルでの COUNT	WARNING	SQL 開発	テーブル全体のスキャンに伴う I/O コストがあります
SPEC027	クエリで LIMIT を使用	INFO	SQL 開発	過大な結果セットを避けます
SPEC028	WITH RECURSIVE の注意	WARNING	SQL 開発	終了条件を確認してください
SPEC029	スキーマプレフィックスを使用	INFO	SQL 開発	catalog.schema の曖昧さを避けます
SPEC030	ビューのネスト深度 ≤ 3	INFO	オブジェクト設計	クラスタークエリが必要です
SPEC031	マテリアライズドビューの更新	INFO	オブジェクト設計	頻繁にアクセスされる MV では自動更新を検討してください
SPEC032	カタログ間の JOIN	WARNING	SQL 開発	カタログ間の JOIN はパフォーマンスに影響する可能性があります
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 ステートメントでは、SPEC001 と SPEC018 を回避するため、大規模テーブルに PARTITIONED BY と CLUSTERED BY を必ず含めます
3. 包括的にチェックするには、all モードを使用します
4. HetuEngine は、PARTITION BY（PostgreSQL 形式）ではなく、PARTITIONED BY（Hive 互換）を使用します
5. HetuEngine は、DISTRIBUTE BY の代わりに bucketed_by と bucket_count のプロパティを使用します
6. requires_cluster: true（SPEC030）とマークされたルールにはクラスター接続が必要で、静的モードではスキップされます
7. HetuEngine は Hive との互換性のため、バッククォートで囲まれた識別子（identifier）をサポートします
8. HetuEngine の INSERT OVERWRITE では、（DWS とは異なり）INTO キーワードは不要です
9. HetuEngine は SEMI JOIN と ANTI JOIN をサポートします（標準 SQL ではサポートされません）

参考資料

ドキュメント	説明
AST スキーマ	HetuEngine SQL の AST ノード型の定義
構文ルール	19 個の構文チェックルールの定義
仕様ルール	34 個の仕様チェックルールの定義
キーワード	400 個以上の HetuEngine SQL キーワードの定義
文法ルール	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 は次の機能をサポートしています：仮想スキーマ、自動更新付きマテリアライズドビュー、CREATE FUNCTION（SQL／Python UDF）、MATCH_RECOGNIZE、SEMI／ANTI JOIN、TABLESAMPLE、GROUPING SETS／CUBE／ROLLUP