huawei-cloud-mrs-spark-sql-check

MRS Spark SQL チェック スキル

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

概要

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

適用シナリオ：

• MRS Spark クラスターで実行する前に SQL 構文を検証する
• Spark SQL 開発仕様に照らして SQL 文をレビューする
• Spark 固有の構文（USING、OPTIONS、CACHE TABLE、CREATE TEMP VIEW など）をチェックする
• Spark SQL 文における潜在的なパフォーマンス上のアンチパターンを特定する

一般的なユースケース：

• 「この Spark SQL をチェックしてください：SELECT * FROM t1」
• 「この CREATE TABLE USING PARQUET は Spark の仕様に準拠していますか？」
• 「この INSERT OVERWRITE 文の構文を検証してください」
• 「自分の Spark SQL が仕様に準拠しているかレビューしてください」

チェックモード

モード	依存関係	説明
syntax	なし	構文チェック：キーワードの有効性、文の構造、句の完全性、Spark SQL 構文との互換性
spec	なし	仕様チェック：オブジェクト設計標準、データ操作標準、命名規則、Spark SQL 開発ルール
all	なし	構文チェックと仕様チェックの両方を実行

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

前提条件

1. Python の要件

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

2. セキュリティルール

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

ワークフロー

ステップ 1：入力の受け取り

ユーザーから SQL 文とチェックモードを受け取ります。モードが指定されていない場合は、デフォルトで syntax + spec を使用します。

ステップ 2：トークン化

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

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

トークナイザーは以下をサポートします：

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

ステップ 3：解析

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

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

パーサーは、以下の主な文の種類をサポートします：

• DML：SELECT、INSERT（INSERT OVERWRITE を含む）、UPDATE、DELETE、MERGE
• DDL：CREATE TABLE（USING/OPTIONS を含む）、ALTER TABLE、DROP、CREATE VIEW/TEMP VIEW/GLOBAL TEMP VIEW、TRUNCATE
• DCL：GRANT、REVOKE
• ユーティリティ：EXPLAIN、SET、SHOW、DESCRIBE、ANALYZE TABLE
• Spark 固有：CACHE TABLE、UNCACHE TABLE、CLEAR CACHE、REFRESH TABLE/FUNCTION、ADD JAR、LIST JAR、RESET

Spark 固有の構文：

• CREATE TABLE ... USING {parquet|orc|json|csv|...} [OPTIONS (...)]
• CACHE [LAZY] TABLE table_name [AS SELECT ...]
• CREATE [OR REPLACE] [GLOBAL] TEMP [MATERIALIZED] VIEW
• REFRESH TABLE table_name / REFRESH FUNCTION func_name
• ADD JAR /path/to/file.jar
• /*+ BROADCAST(table) */ および /*+ COALESCE(N) */ ヒント
• LATERAL VIEW ... EXPLODE(...)
• PARTITIONED BY (col_name)（Spark スタイル。列名のみ）

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

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

構文チェックルール（20 個）：

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

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

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

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

ルール 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 開発	代わりに INSERT SELECT を使用してください
SPEC021	サブクエリのネスト深度	WARNING	SQL 開発	サブクエリのネストは 3 階層を超えないようにしてください
SPEC022	パーティションプルーニングがない	ERROR	データ操作	パーティションフィルターのないパーティションテーブルへのクエリです
SPEC023	非標準の JOIN 条件	WARNING	データ操作	JOIN ON に IF/CASE WHEN を含めないでください
SPEC024	CASCADE 使用時の警告	WARNING	SQL 開発	ALTER TABLE で CASCADE を使用する際は注意してください
SPEC025	STORED AS より USING を推奨	WARNING	SQL 開発	Spark ネイティブの USING 構文を使用してください
SPEC026	CACHE TABLE の推奨	INFO	SQL 開発	繰り返しアクセスするテーブルをキャッシュしてください
SPEC027	BROADCAST ヒントの推奨	INFO	SQL 開発	小さなテーブルにはブロードキャスト結合を使用してください
SPEC028	DROP に IF EXISTS がない	WARNING	SQL 開発	DROP では IF EXISTS を使用してください
SPEC029	ADD JAR の警告	INFO	SQL 開発	ADD JAR より --jars を使用してください

ステップ 6：レポートの生成

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

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

レポート形式：

# MRS Spark SQL Check Report

**Check Time**: yyyy-mm-ddThh:mm:ss
**Statement Type**: SELECT
**Check Mode**: all

## Summary

| Metric | Value |
|--------|-------|
| Total Rules | 56 |
| Passed | 51 |
| 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

### [!] SPEC001: 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-SYN020）による違反
• 仕様チェックセクション：仕様ルール（SPEC001-SPEC029）による違反
• 大規模 SQL インターセプトセクション：インターセプトルール（INTERCEPT001-INTERCEPT007）による違反
• 元の SQL：チェック対象の SQL 文

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

主なコマンド

spark_sql_checker.py spark_sql_parser.py spark_sql_tokenizer.py

ベストプラクティス

1. まず構文チェックを実行して基本的なエラーを検出し、次に仕様チェックでより詳細に分析します
2. CREATE TABLE 文では、STORED AS PARQUET より USING parquet を優先します
3. 圧縮率とクエリのパフォーマンスを高めるには、ORC または Parquet のストレージ形式を使用します
4. パーティション化されたテーブルをクエリする際は、必ずパーティションフィルター条件を追加します
5. 包括的にチェックするには、all モードを使用します
6. 小規模テーブルと大規模テーブルを結合する際は、/*+ BROADCAST(small_table) */ ヒントを使用します

参考資料

ドキュメント	説明
AST Schema	Spark SQL の AST ノード型の定義
Syntax Rules	20 個の構文チェックルールの定義
Specification Rules	29 個の仕様チェックルールの定義
Keywords	Spark SQL のキーワード定義
Grammar Rules	文型の文法定義

注意事項

1. 構文チェックと仕様チェックにはクラスターへの接続が不要で、オフラインで実行できます
2. Spark 固有の構文（USING、OPTIONS、CACHE TABLE など）のチェックは、Spark SQL の文法定義に基づいています
3. チェックエンジンにはカスタムトークナイザーと再帰下降パーサーが含まれており、外部の SQL 解析ライブラリは必要ありません
4. Spark SQL は HiveQL に由来するため、Hive 互換の構文（STORED AS、CLUSTERED BY、ROW FORMAT）にも対応しています