huawei-cloud-mrs-hive-sql-check

MRS Hive SQL チェック スキル

Huawei Cloud MRS Hive の SQL 仕様チェックを専門とし、組み込みの自動チェッカーエンジンを使用して SQL 文をチェックします。

重要な制約：余計な分析をしない

自動チェッカーエンジンが検出した違反のみを報告してください。 チェッカースクリプトの出力を超える手動での分析、解釈、「詳細分析」を追加しないでください。これには、以下が含まれますが、これらに限定されません。

• SQL ロジックに矛盾、デッドコード、範囲の競合がないか、手動で調べないでください
• 二重引用符と一重引用符の違いに関する Hive の意味論についてコメントしないでください（Hive ではどちらも文字列リテラルとして使用できます）
• チェッカールールで定義されていない最適化の提案を追加しないでください
• チェッカーの結果に独自の分析を加えたり、結果を疑って追加の見解を示したりしないでください

チェッカーエンジンには、定義済みのすべてのルール（構文ルール 14 件＋仕様ルール 25 件＋インターセプトルール 11 件）が実装されています。チェッカーが違反 0 件と報告した場合、レポートにも違反 0 件と記載してください。追加の指摘事項を付け加えないでください。

概要

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

適用シナリオ：

• MRS Hive クラスターで実行する前に SQL 構文を検証する
• Hive の開発仕様に照らして SQL 文をレビューする
• Hive 固有の構文（PARTITIONED BY、CLUSTERED BY、STORED AS、ROW FORMAT など）をチェックする
• 定義済みのルールに基づいて、大規模 SQL のインターセプトリスクを検出する

一般的な使用例：

• 「この Hive SQL をチェックしてください：SELECT * FROM t1」
• 「この CREATE TABLE は Hive の仕様に準拠していますか？」
• 「この INSERT OVERWRITE 文の構文を検証してください」
• 「私の Hive SQL が仕様に準拠しているかレビューしてください」
• 「私の SQL にパーティションプルーニングの問題があるかチェックしてください」

チェックモード

モード	依存関係	説明
syntax	なし	構文チェック：キーワードの有効性、文の構造、句の完全性、Hive 構文との互換性
spec	なし	仕様チェック：オブジェクト設計基準、データ操作基準、命名規則、Hive 開発ルール
intercept	なし	大規模 SQL のインターセプトチェック：クラスターリソースを枯渇させる可能性のある高リスク SQL を検出する
all	なし	構文＋仕様＋インターセプトのチェックを実行する

デフォルト：all モード（外部依存関係は不要です）。

前提条件

1. Python の要件

• Python >= 3.8
• 追加パッケージは不要です（標準ライブラリのみ）

2. セキュリティルール

• このスキルは静的 SQL 分析のみを実行し、クラスターへの接続は不要です
• SQL テキストはローカルで処理され、外部にデータは送信されません
• 認証情報や認証は不要です

ワークフロー

ステップ 1：入力を受け取る

SQL 文とチェックモードをユーザーから受け取ります。モードが指定されていない場合は、デフォルトの all（構文＋仕様＋インターセプト）にします。

重要：複数文のコンテキスト：ユーザーが複数の SQL 文を（; で区切って）指定した場合は、すべての文をまとめて、1 回のチェッカー呼び出しに渡してください。 個別に分割してチェックしないでください。チェッカーエンジンには、次の組み込みの複数文サポートがあります。

1. 第 1 パス：すべての CREATE TABLE ... PARTITIONED BY 文をスキャンし、パーティションテーブルレジストリ（テーブル名＋パーティションフィールド名）を作成します
2. 第 2 パス：各文を個別にチェックしますが、パーティションテーブルのコンテキストを共有するため、パーティションテーブルを参照する SELECT／INSERT で SPEC022（パーティションプルーニングの欠落）を検出できます

これは、テーブルがパーティション化されているかどうかを把握する必要がある SPEC022（パーティションプルーニング）などのルールにとって重要です。この情報は SELECT 文自体ではなく、CREATE TABLE 文にのみ存在します。

正しい例：すべての SQL をまとめて渡します：

python ~/.cac/skills/huawei-cloud-mrs-hive-sql-check/scripts/hive_sql_checker.py "create table t(name string) partitioned by(dt string); select name from t;" all

誤った例：個別に分割してチェックします（SPEC022 が検出されません）：

python ~/.cac/skills/huawei-cloud-mrs-hive-sql-check/scripts/hive_sql_checker.py "create table t(name string) partitioned by(dt string);" all
python ~/.cac/skills/huawei-cloud-mrs-hive-sql-check/scripts/hive_sql_checker.py "select name from t;" all

ステップ 2：トークン化

トークナイザーを実行して、SQL テキストをトークンストリームに変換します。

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

トークナイザーは次をサポートします。

• すべての Hive SQL キーワード（4 カテゴリ：RESERVED、COL_NAME、TYPE_FUNC_NAME、UNRESERVED）
• Hive 固有のトークン：HINT（/*+ ... */）、BACKTICK_IDENT（`ident`）
• リテラル：文字列、整数、浮動小数点数
• コメントのスキップ（-- の単一行コメント、/* / の複数行コメント。ただし、/+ hint */ は HINT トークンとして保持）

ステップ 3：解析

パーサーを実行して AST を生成し、構文エラーを検出します。

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

パーサーは主要なステートメント型をサポートします。

• DML：SELECT、INSERT（INSERT OVERWRITE を含む）、UPDATE、DELETE
• DDL：CREATE TABLE、ALTER TABLE、DROP、CREATE VIEW、CREATE INDEX、TRUNCATE
• DCL：GRANT、REVOKE
• UTILITY：EXPLAIN、SET、SHOW、MSCK、ANALYZE

Hive 固有の構文：

• PARTITIONED BY (col type, ...)
• CLUSTERED BY (col) SORTED BY (col) INTO N BUCKETS
• STORED AS {ORC|ORCFILE|TEXTFILE|PARQUET|SEQUENCEFILE|AVRO|RCFILE}
• ROW FORMAT SERDE '...' STORED AS INPUTFORMAT '...' OUTPUTFORMAT '...'
• LOCATION 'hdfs_path'
• TBLPROPERTIES ('key'='value', ...)
• INSERT OVERWRITE TABLE ... PARTITION (...)
• /*+ MAPJOIN(table) */ および /*+ STREAMTABLE(table) */ ヒント
• LATERAL VIEW ... EXPLODE(...)
• LATERAL TABLE
• FROM ... INSERT OVERWRITE ... SELECT ...（複数 INSERT）

ステップ 4：構文チェック

トークン化と解析の結果に基づいて、構文チェックルールを実行します。

構文チェックルール（14 ルール）：

ルール ID	名前	レベル	説明
SYN-ERR	字句エラー	ERROR	SQL テキスト内に認識できない文字があります
SYN001	無効なキーワード	ERROR	Hive でサポートされていないキーワードです
SYN002	識別子として使用された予約語	ERROR	引用符で囲まずに予約語を識別子として使用しています
SYN003	構文構造エラー	ERROR	必須の句またはキーワードがありません
SYN004	句の順序エラー	ERROR	SQL の句の順序が文法に準拠していません
SYN005	PARTITIONED BY 構文エラー	ERROR	パーティション定義の構文が無効です
SYN006	CLUSTERED BY 構文エラー	ERROR	バケット定義の構文が無効です
SYN007	STORED AS 構文エラー	ERROR	ストレージ形式が無効です
SYN008	ROW FORMAT 構文エラー	ERROR	ROW FORMAT 定義が無効です
SYN009	INSERT OVERWRITE 構文エラー	ERROR	INSERT OVERWRITE の構造が無効です
SYN010	LATERAL VIEW 構文エラー	ERROR	LATERAL VIEW の構造が無効です
SYN011	サブクエリ構文エラー	ERROR	サブクエリの構造が無効です
SYN012	CREATE TABLE 構造エラー	ERROR	CREATE TABLE に必要な要素（列、AS SELECT、LIKE、TBLPROPERTIES、ROW FORMAT SERDE、または STORED BY）がありません
SYN013	ALTER TABLE 構文エラー	ERROR	ALTER TABLE のアクションが無効です

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

AST とトークンストリームに基づき、仕様チェックルールを実行します。ルールは Hive の開発仕様と MRS Hive のベストプラクティスに基づいています。

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

ルール ID	名前	レベル	カテゴリ	説明
SPEC001	SELECT * の使用禁止	WARNING	データ操作	クエリでは列を明示的に指定する必要があります
SPEC002	WHERE なしの DELETE/UPDATE	ERROR	データ操作	DML には WHERE 条件を含める必要があります
SPEC003	直積	ERROR	データ操作	複数テーブルで JOIN 条件が不足しています
SPEC004	暗黙的な型変換	WARNING	データ操作	想定外の結果を招く可能性があります
SPEC005	先頭にワイルドカードを含む LIKE	WARNING	データ操作	パーティションプルーニングを利用できません
SPEC006	パーティションフィールドに対する関数	WARNING	データ操作	パーティションフィールドに関数を適用するとプルーニングが妨げられます
SPEC007	INSERT の列リスト不足	WARNING	データ操作	デフォルトの列順序に依存します
SPEC008	テーブルコメントの不足	INFO	オブジェクト設計	コメントのないテーブル
SPEC009	識別子としての予約語の使用	ERROR	命名	構文が曖昧になる可能性があります
SPEC010	列名が長すぎる	WARNING	命名	列名が 30 文字を超えています
SPEC012	金額に対する FLOAT/DOUBLE の使用	ERROR	オブジェクト設計	金額フィールドには DECIMAL を使用してください
SPEC013	列数が多すぎる	WARNING	オブジェクト設計	テーブルの列数は 100 を超えないようにしてください
SPEC014	パーティションフィールドが多すぎる	WARNING	オブジェクト設計	パーティションフィールドは 3 つを超えないようにしてください
SPEC015	列コメントの不足	INFO	オブジェクト設計	コメントのない列
SPEC016	CASE WHEN に ELSE がない	WARNING	データ操作	CASE WHEN には ELSE 句を含めてください
SPEC017	NULL 値の処理	WARNING	データ操作	条件式での NULL の処理
SPEC018	文字列 'null' の使用禁止	ERROR	データ操作	文字列 'NULL' を使用しないでください
SPEC019	JOIN フィールドの型不一致	WARNING	データ操作	JOIN フィールドは同じ型にしてください
SPEC020	INSERT INTO VALUES	WARNING	SQL 開発	代わりに LOAD DATA または INSERT SELECT を使用してください
SPEC021	サブクエリのネスト深度	WARNING	SQL 開発	サブクエリのネストは 3 階層を超えないようにしてください
SPEC022	パーティションプルーニングの不足	ERROR	データ操作	パーティションフィルターなしでのパーティションテーブルのクエリ
SPEC023	標準外の JOIN 条件	WARNING	データ操作	JOIN ON に IF/CASE WHEN を含めないでください
SPEC024	CASCADE 使用時の警告	WARNING	SQL 開発	ALTER TABLE での CASCADE は慎重に使用してください
SPEC025	Hive on Spark の使用禁止	WARNING	SQL 開発	Hive on Tez を使用してください

ステップ 6：大規模 SQL のインターセプトチェック

クラスターのリソースを使い果たす可能性のある、高リスクな SQL を検出します。

ルール ID	名前	レベル	説明
INTERCEPT001	COUNT(DISTINCT) の上限超過	ERROR	1 つのステートメント内に COUNT(DISTINCT) が 10 個を超えている
INTERCEPT002	NOT IN サブクエリー	WARNING	NOT IN サブクエリーが検出された
INTERCEPT003	JOIN 数の上限超過	ERROR	1 つのステートメント内に JOIN が 20 個を超えている
INTERCEPT004	UNION ALL 数の上限超過	ERROR	1 つのステートメント内に UNION ALL が 20 個を超えている
INTERCEPT005	サブクエリーのネスト上限超過	ERROR	サブクエリーのネスト深度が 20 を超えている
INTERCEPT006	SQL 長の上限超過	WARNING	SQL 文字列の長さが 10KB を超えている
INTERCEPT007	直積	ERROR	直積が検出された

ステップ 7：レポートを生成する

チェックエンジンを使用して、Markdown 形式のレポートを生成します。

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

重要：レポートは、チェッカースクリプトの出力のみをもとに生成する必要があります。手動の分析、「詳細な分析」、またはチェッカーの報告にない追加の検出事項を追記しないでください。チェッカーが違反件数 0 を返した場合は、違反件数 0 のままレポートを提示してください。

レポート形式：

# MRS Hive SQL Check Report

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

## Summary

| Metric | Value |
|--------|-------|
| Total Rules | 60 |
| Passed | 55 |
| Violations | 5 |
| Errors (ERROR) | 2 |
| Warnings (WARNING) | 2 |
| 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

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

## Large SQL Interception

### [X] INTERCEPT001: COUNT(DISTINCT) Over Limit
- **Level**: ERROR
- **Description**: SQL contains more than 10 COUNT(DISTINCT) expressions
- **Fix Suggestion**: Split into multiple subqueries using UNION ALL

主なコマンド

hive_sql_checker.py hive_sql_parser.py hive_sql_tokenizer.py

パラメーター

パラメーター	必須／任意	説明	デフォルト
sql_text	必須	チェックする SQL ステートメント	N/A
check_mode	任意	チェックモード：syntax/spec/all	syntax+spec

出力形式

チェックレポートは Markdown 形式で出力され、次の内容が含まれます。

• 概要テーブル：ルールの合計数、合格数、レベル別の違反数
• 構文チェックセクション：構文ルール（SYN-ERR、SYN001-SYN013）による違反
• 仕様チェックセクション：仕様ルール（SPEC001-SPEC025）による違反
• 大規模 SQL インターセプトセクション：インターセプトルール（INTERCEPT001-INTERCEPT011）による違反
• 元の SQL：チェック対象の SQL ステートメント

各違反の項目には、ルール ID、ルール名、レベル、位置（行／列）、説明、コードスニペット、修正の提案が含まれます。

クイックチェックコマンド

簡単な SQL チェックを行う場合は、次のコマンドを直接実行します。

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

出力は JSON 形式です。Markdown 形式のレポートを出力するには、Python から呼び出します。

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

ベストプラクティス

1. まず構文チェックを実行して基本的なエラーを検出し、次に仕様チェックでより詳細に分析します。
2. CREATE TABLE ステートメントでは、大きなテーブルに対して必ず PARTITIONED BY を含めてください。
3. 圧縮率とクエリのパフォーマンスを向上させるため、ORC ストレージ形式を使用してください。
4. パーティション分割されたテーブルをクエリする際は、必ずパーティションフィルター条件を追加してください。
5. 包括的なチェックには all モードを使用してください。

参考資料

ドキュメント	説明
AST Schema	Hive SQL の AST ノード型の定義
Syntax Rules	14 件の構文チェックルールの定義
Specification Rules	25 件の仕様チェックルールの定義
Performance Rules	11 件の大規模 SQL インターセプトルールの定義
Keywords	Hive SQL のキーワード定義
Grammar Rules	ステートメント型の文法定義

注意事項

1. 構文および仕様のチェックではクラスターへの接続は不要で、オフラインで実行できます
2. 大規模な SQL のインターセプトルールは、クラスターリソースの枯渇を防ぐために設計されています
3. Hive 固有の構文チェック（PARTITIONED BY、CLUSTERED BY、STORED AS など）は、HiveQL の文法定義に基づいています
4. チェックエンジンにはカスタムトークナイザーと再帰下降パーサーが含まれており、外部の SQL 解析ライブラリは必要ありません
5. 厳守事項：チェッカーエンジンの出力のみを報告してください。 手動での分析、「詳細な分析」、ロジックのレビュー、または定義されたルール（SYN-ERR/SYN001-SYN013、SPEC001-SPEC025、INTERCEPT001-INTERCEPT011）で検出される内容以外の指摘を追加しないでください。チェッカーが違反 0 件と判定した場合、回答も違反 0 件です。追加の指摘はしないでください。