huawei-cloud-dws-sql-check

DWS SQL チェック スキル

あなたはDWS SQL仕様チェックのエキスパートとして、DWS向けSQL文を包括的にチェックします。DWS固有の構文を正確に識別できる、独自開発のDWS SQLトークナイザーと再帰下降パーサーを備えています。

概要

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

対象シナリオ：

• DWSクラスターで実行する前にSQL構文を検証する
• DWS開発設計仕様に照らしてSQL文をレビューする
• DWS固有の構文（DISTRIBUTE BY、PARTITION BY、MERGEなど）をチェックする
• SQL文に潜むパフォーマンス上のアンチパターンを特定する

一般的な使用例：

• 「このSQLをチェックしてください：SELECT * FROM t1」
• 「このCREATE TABLEはDWS仕様に準拠していますか？」
• 「このMERGE文の構文を検証してください」
• 「仕様への準拠という観点でSQLをレビューしてください」
• 「SQLでDWS固有の構文が正しく使われているかチェックしてください」

チェックモード

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

デフォルト：構文＋仕様モード（外部依存関係は不要）。

前提条件

1. Python の要件

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

2. セキュリティルール

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

ワークフロー

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

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

ステップ2：トークン化

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

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

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

• DWSキーワード594個すべて（4カテゴリ：RESERVED=91、COL_NAME=68、TYPE_FUNC_NAME=28、UNRESERVED=407）
• DWS固有のトークン：ORA_JOINOP（Oracle (+) 結合）、TYPECAST（::）、HINT（/*+ ... */）
• リテラル：文字列、整数、浮動小数点数、ビット文字列、16進数文字列
• パラメーター参照：$1、$2...
• コメントのスキップ（-- 単一行、/* / 複数行。ただし、/+ hint */ はHINTトークンとして保持）

ステップ3：解析

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

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

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

• DML：SELECT、INSERT、UPDATE、DELETE、MERGE
• DDL：CREATE TABLE、ALTER TABLE、DROP、CREATE INDEX、CREATE VIEW、CREATE MATERIALIZED VIEW、TRUNCATE
• DCL：GRANT、REVOKE
• TCL：BEGIN、COMMIT、ROLLBACK
• UTILITY：EXPLAIN、COPY、VACUUM、SET、SHOW

DWS固有の構文：

• DISTRIBUTE BY {HASH|MODULO|REPLICATION|ROUNDROBIN}
• PARTITION BY {RANGE|LIST|INTERVAL}
• TO {NODE|GROUP}
• COMPRESS {YES|NO}
• TIMECAPSULE TABLE ... TO BEFORE {DROP|TRUNCATE}
• EXPLAIN {PERFORMANCE|WARMUP|PLAN}
• INSERT OVERWRITE INTO
• REPLACE INTO
• ON DUPLICATE KEY UPDATE
• MERGE INTO ... USING ... ON ... WHEN MATCHED/NOT MATCHED
• CREATE RESOURCE POOL / WORKLOAD GROUP / REDACTION POLICY / OUTLINE
• Oracle (+) 外部結合
• オプティマイザーヒント（/*+ ... */）

Step 4: 構文チェック

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

構文チェックルール（19 件）：

ルール ID	名前	レベル	説明
SYN-ERR	字句エラー	ERROR	SQL テキストに認識できない文字があります
SYN001	無効なキーワード	ERROR	DWS でサポートされていないキーワードです
SYN002	識別子としての予約語	ERROR	引用符で囲まずに予約語を識別子として使用しています
SYN003	構文構造エラー	ERROR	必須の句またはキーワードがありません
SYN004	句の順序エラー	ERROR	SQL の句の順序が文法に準拠していません
SYN005	DISTRIBUTE BY 構文エラー	ERROR	無効な分散方式です
SYN006	PARTITION 構文エラー	ERROR	パーティション定義の構文が無効です
SYN007	MERGE 構文エラー	ERROR	MERGE 文の構造が不完全です
SYN008	EXPLAIN 構文エラー	ERROR	EXPLAIN オプションが無効です
SYN009	COMPRESS 構文エラー	ERROR	COMPRESS オプションが無効です
SYN010	TIMECAPSULE 構文エラー	ERROR	TIMECAPSULE 文の構造が無効です
SYN011	RESOURCE POOL 構文エラー	ERROR	CREATE RESOURCE POOL の構造が無効です
SYN012	WORKLOAD GROUP 構文エラー	ERROR	CREATE WORKLOAD GROUP の構造が無効です
SYN013	REDACTION POLICY 構文エラー	ERROR	CREATE REDACTION POLICY の構造が無効です
SYN014	OUTLINE 構文エラー	ERROR	CREATE OUTLINE の構造が無効です
SYN015	TO NODE/GROUP 構文エラー	ERROR	TO NODE/GROUP 句の構文が無効です
SYN016	INSERT OVERWRITE 構文エラー	ERROR	INSERT OVERWRITE の構造が無効です
SYN017	ON DUPLICATE KEY 構文エラー	ERROR	ON DUPLICATE KEY UPDATE 句が無効です
SYN018	Oracle (+) 結合構文エラー	WARNING	(+) 演算子の使い方が正しくありません
SYN019	オプティマイザーヒント構文エラー	WARNING	ヒントの形式が無効です

Step 5: 仕様チェック

AST とトークンストリームに基づいて、仕様チェックルールを実行します。ルールは gram.y の文法定義と DWS の開発設計仕様に基づいています。

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

ルール ID	名前	レベル	カテゴリ	出典	説明
SPEC001	DISTRIBUTE BY の欠落	ERROR	オブジェクト設計	ルール 2.9	分散方式を指定せずに CREATE TABLE を実行しています
SPEC002	主キーの欠落	INFO	オブジェクト設計	-	主キー制約のないテーブルです
SPEC003	SELECT * の禁止	ERROR	データ操作	推奨 3.14	クエリでは明示的な列リストを指定する必要があります
SPEC004	WHERE を指定しない DELETE/UPDATE	ERROR	データ操作	-	DML には WHERE 条件を含める必要があります
SPEC005	NOT IN サブクエリ	WARNING	データ操作	-	代わりに NOT EXISTS を推奨します
SPEC006	DISTINCT のパフォーマンス	INFO	データ操作	-	DISTINCT はパフォーマンスに影響する可能性があります
SPEC007	暗黙的な型変換	WARNING	データ操作	ルール 3.9	インデックスが無効になる可能性があります
SPEC008	LIKE の先頭ワイルドカード	WARNING	データ操作	-	インデックスを使用できません
SPEC009	OR 条件	INFO	データ操作	-	実行計画に影響する可能性があります
SPEC010	IN リストが長すぎます	WARNING	データ操作	-	値が 100 個を超える場合は一時テーブルを推奨します
SPEC011	FROM サブクエリ	INFO	データ操作	-	代わりに CTE を推奨します
SPEC012	直積	ERROR	データ操作	ルール 3.8	複数テーブルで JOIN 条件がありません
SPEC013	Oracle 外部結合	INFO	データ操作	-	標準の JOIN を推奨します
SPEC014	INSERT の列リストの欠落	WARNING	データ操作	-	既定の列順序に依存しています
SPEC015	テーブルコメントの欠落	INFO	オブジェクト設計	-	コメントのないテーブルです
SPEC016	テーブルの命名規則	WARNING	命名	-	小文字とアンダースコアを使用してください
SPEC017	列の命名規則	WARNING	命名	-	小文字とアンダースコアを使用してください
SPEC018	識別子に予約語を使用	ERROR	命名	-	構文が曖昧になる可能性があります
SPEC019	分散キーの列が見つかりません	WARNING	オブジェクト設計	-	分散キーには実際のテーブル列を指定してください
SPEC020	パーティションキーと分散キーが同じ	INFO	オブジェクト設計	-	データの偏りが発生する可能性があります
SPEC021	大規模テーブルでの REPLICATION	WARNING	オブジェクト設計	-	大規模テーブルでは REPLICATION を使用しないでください
SPEC022	ROUNDROBIN のパフォーマンス	INFO	オブジェクト設計	ルール 2.9	ローカル結合をサポートしません
SPEC023	カスタム TABLESPACE	WARNING	オブジェクト設計	ルール 2.8	カラムストア v3 テーブルを除きます
SPEC024	ストレージ形式の欠落	WARNING	オブジェクト設計	ルール 2.10	ストレージ形式を明示することを推奨します
SPEC025	行ストアでの COMPRESS の禁止	ERROR	オブジェクト設計	ルール 2.10	行ストアの圧縮テーブルは禁止されています
SPEC026	大規模テーブルにはパーティションを設定してください	INFO	オブジェクト設計	ルール 2.11	クエリとガバナンスの効率を向上させます
SPEC027	列に NOT NULL を指定してください	INFO	オブジェクト設計	推奨 2.12	オプティマイザーは NOT NULL を活用できます
SPEC028	SERIAL 型を避ける	WARNING	オブジェクト設計	推奨 2.13	SERIAL は GTM に負荷をかけます
SPEC029	インデックス数が 5 を超えています	WARNING	オブジェクト設計	ルール 2.14	クラスターが必要です：pg_indexes を照会してください
SPEC030	DROP では IF EXISTS を使用してください	WARNING	SQL 開発	ルール 3.2	オブジェクトが見つからない場合のエラーを防ぎます
SPEC031	複数の VALUES には COPY を使用してください	WARNING	SQL 開発	ルール 3.3	INSERT VALUES は効率がよくありません
SPEC032	カラムストアでのリアルタイム INSERT	WARNING	SQL 開発	推奨 3.4	小さな CU の肥大化
SPEC033	カラムストアでの UPDATE/DELETE	WARNING	SQL 開発	推奨 3.6	CU の肥大化とデッドロックのリスク
SPEC034	プッシュダウンされない SQL の禁止	ERROR	SQL 開発	ルール 3.7	クラスターが必要です：EXPLAIN で分析してください
SPEC035	フィルター列への関数適用	WARNING	SQL 開発	推奨 3.10	統計情報の精度に影響します
SPEC036	行ストアの大規模テーブルでの COUNT	WARNING	SQL 開発	ルール 3.12	全テーブルスキャンの I/O コスト
SPEC037	クエリでは LIMIT を使用してください	INFO	SQL 開発	推奨 3.13	過大な結果セットを避けます
SPEC038	WITH RECURSIVE の使用に注意	WARNING	SQL 開発	推奨 3.15	終了条件を必ず設定してください
SPEC039	スキーマプレフィックスを使用してください	INFO	SQL 開発	推奨 3.16	search_path に関する問題を避けます
SPEC040	ビューのネスト深度は 3 以下	INFO	オブジェクト設計	推奨 2.16	クラスターが必要です：ビューの依存関係を照会してください

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

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

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

レポート形式：

# DWS SQL Check Report

**Check Time**: 2026-06-18T10:00:00
**Statement Type**: SELECT
**Check Mode**: all

## Summary

| Metric | Value |
|--------|-------|
| Total Rules | 41 |
| Passed | 38 |
| 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

パラメーター

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

出力形式

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

• 概要テーブル：ルールの合計数、合格数、レベル別の違反数
• 構文チェックセクション：構文ルール（SYN-ERR、SYN001-SYN019）による違反
• 仕様チェックセクション：仕様ルール（SPEC001-SPEC040）による違反
• 元の SQL：チェック対象の SQL 文

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

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

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

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

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

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

ベストプラクティス

1. まず構文チェックを実行して基本的なエラーを検出し、次に仕様チェックで詳細な分析を行います
2. CREATE TABLE 文では、SPEC001 を回避するために必ず DISTRIBUTE BY を指定します
3. 包括的なチェックには all モードを使用します
4. requires_mcp: true または「Requires cluster」と記されたルール（SPEC029、SPEC034、SPEC040）にはクラスター接続が必要であり、静的モードではスキップされます

参考資料

ドキュメント	説明
AST スキーマ	DWS SQL の AST ノード型定義
構文ルール	19 個の構文チェックルール定義
仕様ルール	40 個の仕様チェックルール定義
パフォーマンスルール	11 個のパフォーマンスチェックルール定義（クラスター接続が必要）
キーワード	594 個の DWS SQL キーワード定義
文法ルール	160 種類以上の文型の文法定義

注記

1. 構文チェックと仕様チェックにはクラスター接続が不要で、オフラインで実行できます
2. 「Requires cluster」と記されたルール（SPEC029、SPEC034、SPEC040）は静的モードではスキップされます
3. パフォーマンスルール（PERF001-PERF011）は rules/perf_rules.yaml で定義されていますが、実行にはクラスター接続が必要です
4. DWS 固有の構文チェック（DISTRIBUTE BY、PARTITION BY、MERGE など）は、gram.y の文法定義に基づいています
5. チェックエンジンにはカスタムトークナイザーと再帰下降パーサーが含まれており、外部の SQL 解析ライブラリは必要ありません