huawei-cloud-mrs-clickhouse-sql-check

ClickHouse SQL チェック スキル

ClickHouse SQL 仕様チェックのエキスパートとして、ClickHouse の SQL 文を包括的にチェックします。ClickHouse 独自の構文を正確に識別できる、独自開発の ClickHouse SQL トークナイザーと文認識機能を備えています。

1. 概要

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

複数バージョンへの対応：バージョン固有の文法ルール（キーワード、文法、トークン型）は、 rules/v{version}/ ディレクトリに保存されています。共通の開発仕様ルールは rules/common/ にあります。ユーザーがこのスキルを呼び出したときは、セッションごとに 1 回、 使用する ClickHouse カーネルのバージョンを確認してください（以下のワークフローを参照）。 同じセッション内では、以前に選択したバージョンとモードを再利用し、再度確認しないでください。

対応バージョン：

| バージョン | キーワード | トークン型 | 文の型 | ソース | |---------|-------------|-----------------|--------| | 24.8 | 571 | 52 | 47 | CommonParsers.h APPLY_FOR_PARSER_KEYWORDS マクロ | | 23.3 | 462 | 49 | 47 | Parser*.cpp の ParserKeyword("...") 呼び出し（複数箇所） | | 22.3 | 422 | 48 | 46 | Parser*.cpp の ParserKeyword("...") 呼び出し（複数箇所） |

ソース：すべてのキーワードと文法ルールは、ClickHouse カーネルのソース（src/Parsers/CommonParsers.h、src/Parsers/Lexer.h、 src/Parsers/Parser*.cpp）から直接抽出されており、正確性と完全性が保証されています。

チェックモード：

モード	依存関係	説明
syntax	なし	構文チェック：キーワードの有効性、文の構造、句の完全性、ClickHouse 構文との互換性
spec	なし	仕様チェック：MRS 開発標準に基づく 35 の開発仕様ルール（SPEC001-SPEC035）
all	なし	構文チェックと仕様チェックの両方を実行

デフォルト：syntax モード。仕様ルールを有効にするには、spec または all を使用してください。

適用シナリオ：

• ClickHouse クラスターで実行する前に SQL 構文を検証する
• ClickHouse 固有の構文（ENGINE、ORDER BY、PARTITION BY、SAMPLE BY、 TTL、ARRAY JOIN、PREWHERE、GLOBAL JOIN、ASOF JOIN、FINAL など）をチェックする
• SQL 文に潜在的な構文エラーがないか特定する
• ClickHouse のバージョン固有の互換性について SQL を確認する

一般的な使用例：

• 「この SQL をチェックしてください：SELECT * FROM t1」
• 「この CREATE TABLE は ClickHouse の有効な構文ですか？」
• 「この MERGE 文の構文を検証してください」
• 「SQL で ClickHouse 固有の構文が正しく使われているかチェックしてください」
• 「この ClickHouse SQL の構文は正しいですか？」

2. 前提条件

2.1 Python の要件

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

2.2 セキュリティルール

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

2.3 環境

• ClickHouse クラスターへの接続は不要です
• KooCLI または clickhouse-client バイナリは不要です
• 完全にオフラインで動作します

3. ワークフロー

ステップ 1：入力を受け取り、バージョンを選択する

ユーザーから SQL 文を受け取ります。

バージョン選択（必須、セッションごとに 1 回）：新しいセッションでの最初の呼び出し時に、AskUserQuestion を使って ClickHouse カーネルのバージョンとチェックモードを同時に選択するようユーザーに尋ねます（質問は 2 つ：バージョンとモード）。同じセッション内では再度尋ねないでください — そのセッションで後続の SQL チェックを行う際は、選択済みのバージョンとモードを再利用します。新しいセッションでは、再選択が必要です。

質問を省略する条件：

• ユーザーがメッセージ内ですでにバージョンやモードを指定している場合は、尋ねずにその値を使い、セッション中はその値を記憶します。
• 同じセッション内の前回の呼び出しですでにバージョンとモードが設定されている場合は、何も伝えずにその値を再利用します。
• 過去のバージョンやモードのコンテキストがない新しいセッションでの最初の呼び出しの場合にのみ、AskUserQuestion による質問を行います。

構文チェックに使用するキーワードリストと文法規則は、バージョンによって決まります。

チェックモード：バージョンと同じ AskUserQuestion 呼び出しで一緒に尋ねます。ユーザーがモードを指定していない場合は、構文をデフォルトにします。

ステップ 2：トークン化

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

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_tokenizer.py "<sql_text>" [version]

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

• バージョン固有の ClickHouse キーワード（24.8：571 個、23.3：462 個、大文字と小文字を区別しません）
• ClickHouse 固有のトークン：::（型キャスト）、->（矢印／ラムダ）、||（連結）、 <=>（NULL セーフ等価演算子、24.8 のみ）、<>／!=（等しくない）
• リテラル：文字列（一重引用符）、数値（整数／浮動小数点／16 進数）、識別子（引用符なし／バッククォート／引用符付き）
• コメントのスキップ（-- 1 行コメント、/* */ 複数行コメント、ネストに対応）
• 複合キーワードの認識（ORDER BY、GROUP BY、CREATE TABLE など）
• エラー検出（閉じられていない文字列、無効な文字など）

ステップ 3：文の認識と解析

パーサーを実行し、文の種類を特定して構文エラーを検出します。

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_parser.py "<sql_text>" [version]

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

• DML：SELECT（すべての ClickHouse 拡張機能を含む）、INSERT、INSERT SELECT、DELETE、UPDATE、OPTIMIZE
• DDL：CREATE TABLE/DATABASE/VIEW/MATERIALIZED VIEW/DICTIONARY/FUNCTION/INDEX、 ALTER TABLE（すべての操作）、DROP、RENAME、ATTACH、DETACH、UNDROP、CHECK、DESCRIBE
• DCL：GRANT、REVOKE
• TCL：BEGIN TRANSACTION、COMMIT、ROLLBACK、SET TRANSACTION SNAPSHOT
• ユーティリティ：EXPLAIN、SHOW、SET、KILL、SYSTEM、BACKUP、RESTORE、WATCH、USE

ClickHouse 固有の構文：

• SELECT：SAMPLE、FINAL、ARRAY JOIN、PREWHERE、GLOBAL JOIN、ASOF JOIN、 WITH FILL、INTERPOLATE、WITH TIES、TOP N、LIMIT BY、WITH TOTALS/ROLLUP/CUBE、 WINDOW、QUALIFY（24.8 のみ）、GROUP BY ALL、ORDER BY ALL、DISTINCT ON、FETCH FIRST/NEXT
• CREATE TABLE：ENGINE、ORDER BY、PARTITION BY、PRIMARY KEY、SAMPLE BY、 TTL、SETTINGS、CODEC、STATISTICS、PROJECTION、CONSTRAINT
• ALTER TABLE：ADD/MODIFY/DROP/RENAME/CLEAR/MATERIALIZE COLUMN、 ADD/DROP/CLEAR/MATERIALIZE INDEX/PROJECTION/STATISTICS、 パーティション操作（DROP/DETACH/ATTACH/MOVE/REPLACE/FETCH/FREEZE PARTITION）
• SYSTEM：RELOAD/FLUSH/START/STOP/DROP/SYNC/ENABLE/DISABLE コマンド群
• BACKUP/RESTORE：TABLE/DATABASE/DICTIONARY/ALL TO/FROM Disk/File/S3/Azure

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

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

構文チェックルール：

ルール ID	名前	レベル	説明
SYN-ERR	字句エラー	ERROR	認識できない文字、閉じられていない文字列／コメント
SYN001	無効なキーワード	ERROR	選択した ClickHouse バージョンでサポートされていないキーワード
SYN002	識別子として使用された予約キーワード	WARNING	引用符で囲まずに識別子として使用された予約キーワード
SYN003	必須句の欠落	ERROR	必須句の欠落（例：列リストのない SELECT）
SYN004	句の順序エラー	ERROR	SQL の句の順序が文法に準拠していない
SYN005	閉じられていない文字列	ERROR	文字列リテラルが適切に閉じられていない
SYN006	閉じられていないコメント	ERROR	複数行コメントが適切に閉じられていない
SYN007	閉じられていない識別子	ERROR	引用符で囲まれた識別子が適切に閉じられていない
SYN008	無効な数値形式	ERROR	数値リテラルの形式が不正
SYN009	予期しない文字	ERROR	SQL テキスト内に認識できない文字がある
SYN010	CREATE TABLE に ENGINE がない	WARNING	ENGINE 句のない CREATE TABLE
SYN011	MergeTree に ORDER BY がない	WARNING	ORDER BY のない MergeTree ファミリーのテーブル
SYN012	DELETE に WHERE がない	WARNING	WHERE 句のない DELETE
SYN013	UPDATE に WHERE がない	WARNING	WHERE 句のない UPDATE
SYN014	無効な JOIN 構文	ERROR	無効な JOIN の組み合わせ（例：CROSS と ANY の併用）
SYN015	閉じられていない括弧	ERROR	括弧の対応が取れていない

ステップ 4b：仕様チェック

MRS ClickHouse 開発仕様（v01、2026-07-03）に基づいて、35 個の仕様ルールを実行します。有効にするには、spec または all モードを使用します。仕様ルールはバージョンに依存しません。

仕様チェックルール（SPEC001-SPEC035）：

ルール ID	名前	レベル	カテゴリ	説明
SPEC001	Buffer エンジンは禁止	ERROR	DDL	Buffer エンジンは、再起動や障害時にデータが失われるリスクがあります
SPEC002	Replicated エンジンを推奨	WARNING	DDL	信頼性を高めるため、Replicated*MergeTree を推奨します
SPEC003	テーブル名が標準形式ではない	WARNING	DDL	テーブル名は英字で始め、英数字とアンダースコアのみを使用してください
SPEC004	日付／時刻に String 型を使用しない	WARNING	DDL	日付には String ではなく Date／DateTime 型を使用してください
SPEC005	数値に String 型を使用しない	WARNING	DDL	数値には String ではなく数値型を使用してください
SPEC006	Nullable 列が多すぎる	INFO	DDL	Nullable 列が多すぎるとメモリを浪費します
SPEC007	数値型が最小化されていない	INFO	DDL	用途を満たす最小の数値型を使用してください
SPEC008	カーディナリティが低い列に LowCardinality が未使用	INFO	DDL	カーディナリティが 100k 未満の列には LowCardinality を使用してください
SPEC009	テーブルの列数が 5000 を超えている	WARNING	DDL	1 つのテーブルの列数は 5000 以下にしてください
SPEC010	TTL によるライフサイクル管理がない	INFO	DDL	テーブルには TTL を設定するか、定期的にパーティションを削除してください
SPEC011	ORDER BY のフィールドが多すぎる	WARNING	DDL	ORDER BY のフィールドは 4 つ以下にし、NULL 値を含めないでください
SPEC012	PRIMARY KEY がソートキーのプレフィックスではない	WARNING	DDL	PRIMARY KEY は ORDER BY のプレフィックスにしてください
SPEC014	NO DELAY を指定せずに DROP／ALTER を実行	INFO	DDL	即時実行するには NO DELAY を追加してください
SPEC015	スキップインデックスがテーブルあたり 5 個を超えている	WARNING	DDL	スキップインデックスはテーブルあたり 5 個以下にしてください
SPEC016	パーティション数が過剰になるリスク	INFO	DDL	パーティション数は 10000 以下にし、整数型のパーティション列を使用してください
SPEC017	MV の名前が標準形式ではない	INFO	DDL	集約テーブルには _{type}_agg、MV には _{type}_mv を使用してください
SPEC018	MV に明示的なターゲットテーブルがない	WARNING	DDL	TO キーワードを使用して、MV のターゲットテーブルを指定してください
SPEC019	MV 作成時の POPULATE は禁止	ERROR	DDL	POPULATE は作成中にデータが失われるリスクがあります
SPEC020	MV に TTL がない	INFO	DDL	MV のターゲットテーブルには、ソースと一致する TTL を設定してください
SPEC021	分散テーブルへの INSERT	WARNING	DML	分散テーブルではなく、ローカルテーブルに書き込んでください
SPEC022	INSERT が単一パーティションに限定されていない	INFO	DML	バッチ INSERT の対象は単一のパーティションにしてください
SPEC023	Kafka エンジンは禁止	ERROR	DML	ClickHouse Kafka エンジンは避け、アプリケーション側でデータを取り込んでください
SPEC024	SELECT * クエリは禁止	WARNING	Query	列を明示的に指定し、SELECT * は避けてください
SPEC025	distinct より uniqCombined を推奨	INFO	Query	uniqCombined は countDistinct／distinct より高速です
SPEC026	GLOBAL を指定しない分散 JOIN	WARNING	Query	分散クエリでは GLOBAL JOIN／IN／NOT IN を使用してください
SPEC027	複雑な複数テーブル JOIN が分割されていない	INFO	Query	複雑な複数テーブル JOIN は 2 テーブルずつの JOIN に分割してください
SPEC028	JOIN の順序：大きなテーブルと小さなテーブルを結合	INFO	Query	大きなテーブルを小さなテーブルと JOIN し、小さなテーブルを右側に配置してください
SPEC029	FINAL の使用には注意	INFO	Query	FINAL は全体のマージを実行するため、控えめに使用してください
SPEC030	DELETE／UPDATE ミューテーションの使用には注意	WARNING	DML	ミューテーションは処理が遅く、マージをブロックするため、控えめに使用してください
SPEC031	インデックス列の変更は禁止	ERROR	DML	ORDER BY／PRIMARY KEY の列は絶対に UPDATE しないでください
SPEC032	OPTIMIZE の使用には注意	INFO	DML	OPTIMIZE はマージを強制するため、負荷の低い時間帯に実行してください
SPEC033	バッチクリーンアップでパーティションを使用していない	INFO	DML	バッチクリーンアップには DROP PARTITION を使用してください
SPEC034	型に依存する関数で Decimal 型が不一致	WARNING	Query	coalesce／ifNull／nullIf で Decimal のスケールまたは精度が一致しないと、暗黙的な型変換が発生します
SPEC035	IN／NOT IN の列数が一致しない	ERROR	Query	IN／NOT IN の左辺と右辺の列数が一致しないと、実行時エラーや論理エラーが発生します

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

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

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

4. コアコマンド

4.1 全項目チェック（推奨）

構文と仕様をまとめてチェックします。

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_checker.py "<sql_text>" all 24.8

4.2 構文チェックのみ

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_checker.py "<sql_text>" syntax 24.8

4.3 仕様チェックのみ

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_checker.py "<sql_text>" spec 24.8

4.4 トークン化のデバッグ

デバッグ用にトークンストリームを確認します。

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_tokenizer.py "<sql_text>" 24.8

4.5 パーサーのデバッグ

解析されたステートメント構造を確認します。

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_parser.py "<sql_text>" 24.8

4.6 Python API の使用方法

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

5. パラメーター

パラメーター	必須／任意	説明	デフォルト
sql_text	必須	チェックする SQL ステートメント	なし
version	必須	ClickHouse カーネルのバージョン：24.8、23.3、22.3	デフォルトなし。セッションごとの初回呼び出し時にユーザーが選択する必要があり、セッション内で再利用されます
check_mode	任意	チェックモード：syntax／spec／all	syntax

6. 出力形式

レポート形式：

# ClickHouse SQL Check Report

**Check Time**: 2026-07-27T10:00:00
**ClickHouse Version**: 24.8
**Statement Type**: SELECT
**Check Mode**: all

## Summary

| Metric | Value |
|--------|-------|
| Total Rules | 51 |
| Passed | 48 |
| Violations | 3 |
| Errors (ERROR) | 1 |
| Warnings (WARNING) | 1 |
| Infos (INFO) | 1 |

## Syntax Check

### [X] SYN011: MergeTree Missing ORDER BY
- **Level**: WARNING
- **Position**: Line 1, Column 1
- **Description**: MergeTree family table without ORDER BY clause
- **Fix Suggestion**: Add ORDER BY (column1, column2, ...)

## Specification Check

### [!] SPEC010: Missing TTL lifecycle
- **Level**: INFO
- **Position**: Line 1, Column 1
- **Description**: Tables should have TTL or periodic partition cleanup
- **Fix Suggestion**: Add TTL column + toIntervalMonth(N) clause

## Original SQL

```sql
{original_sql}

**IMPORTANT: Always present check results in table format**, not as bullet lists or
paragraphs. When checking one or multiple SQL statements, always use three tables:
1. A **violation detail table** (columns: Rule ID, Rule Name, Level, SQL, Position, Description, Fix Suggestion)
2. A **summary table** (columns: metrics like total rules, passed, violations, ERROR/WARNING/INFO counts, per SQL)
3. A **fix suggestion table** (columns: SQL, Issue, Suggestion)

This table format is mandatory for all SQL check outputs.

## 7. Verification Methods

### 7.1 Verify Tokenization

Run the tokenizer independently to verify keyword recognition:

```bash
python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_tokenizer.py "SELECT * FROM t1 FINAL" 24.8

期待される結果：トークンストリームに、バージョン 24.8 の認識済みキーワードとして FINAL が含まれていること。

7.2 パーサーの認識を確認する

パーサーを実行して、ステートメントの種類が識別されることを確認します。

python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_parser.py "CREATE TABLE t (a UInt32) ENGINE = MergeTree ORDER BY a" 24.8

期待される結果：解析されたカラムと ENGINE の情報を含む statement_type: CREATE_TABLE が出力されること。

7.3 バージョン固有のキーワードを確認する

バージョン固有のキーワードが正しく認識されることをテストします。

キーワード	24.8	23.3	22.3
QUALIFY	✅	❌	❌
INTERPOLATE	✅	✅	❌
UNDROP	✅	✅	❌
GROUP BY ALL	✅	✅	❌

バージョンを変えてトークナイザーを実行し、キーワードが利用可能か確認します。

7.4 仕様ルールを確認する

既知の違反を仕様チェックにかけ、ルールが検出されることを確認します。

# Should trigger SPEC024 (SELECT * prohibited)
python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_checker.py "SELECT * FROM t1" spec 24.8

# Should trigger SYN011 (MergeTree missing ORDER BY)
python ~/.cac/skills/huawei-cloud-mrs-clickhouse-sql-check/scripts/ck_sql_checker.py "CREATE TABLE t (a UInt32) ENGINE = MergeTree" spec 24.8

8. ベストプラクティス

1. まず構文チェックを実行して基本的なエラーを検出し、次に仕様チェックでより詳細に分析します
2. 正確なキーワードと文法の検証を行うため、対象クラスターに合った ClickHouse のバージョンを必ず指定します
3. 本番環境へのデプロイ前に、包括的なチェックを行うため all モードを使用します
4. バージョン固有のキーワードに注意します（例：QUALIFY は 24.8 以降のみ、INTERPOLATE は 23.3 以降のみ）
5. 分散テーブルの場合は、SPEC026（GLOBAL JOIN）と SPEC021（分散テーブルへの INSERT）をチェックします
6. MergeTree テーブルの場合は、ORDER BY（SYN011）を必ず確認し、TTL（SPEC010）の使用を検討します
7. マテリアライズドビューの場合は、SPEC017～SPEC020 に従います：命名規則、明示的なターゲットテーブル、POPULATE を使用しないこと、TTL の一致

9. 参考資料

ドキュメント	説明
Keywords v24.8	ClickHouse 24.8 のキーワード定義 571 件
Keywords v23.3	ClickHouse 23.3 のキーワード定義 462 件
Keywords v22.3	ClickHouse 22.3 のキーワード定義 422 件
Token Types v24.8	24.8 のレクサー・トークン型定義
Token Types v23.3	23.3 のレクサー・トークン型定義
Token Types v22.3	22.3 のレクサー・トークン型定義
Grammar v24.8	24.8 のステートメント型文法定義
Grammar v23.3	23.3 のステートメント型文法定義
Grammar v22.3	22.3 のステートメント型文法定義
Spec Rules	開発仕様ルール 35 件（SPEC001～SPEC035）
Token Types Ref	トークン型のリファレンスドキュメント
SELECT Grammar	SELECT ステートメントの文法リファレンス
DDL Grammar	DDL ステートメントの文法リファレンス
DML Grammar	DML およびユーティリティステートメントの文法リファレンス

10. 注意事項

1. 構文チェックではクラスターへの接続は不要で、オフラインで実行できます
2. マルチバージョン：各バージョンのルールは個別に保存されるため、新しいバージョンを追加しても既存のバージョンには影響しません
3. キーワードは、対応する ClickHouse カーネルのソースから直接抽出されます
4. 文法ルールでは、カーネルの Parser クラスに含まれる 47 種類のステートメントを対象とします
5. 仕様ルール（35 ルール、SPEC001-SPEC035）は、MRS Development Specification v01（2026-07-03）の Chapter 1: ClickHouse Application Development Standards に基づいており、DDL テーブル設計、DDL 操作、マテリアライズドビュー、DML データ読み込み、クエリ標準、データ変更標準を対象とします
6. 一部の仕様ルール（パーティション数、データ量、JOIN 順序など）では実行時の情報が必要なため、静的なヒューリスティックによって近似します
7. チェックエンジンにはカスタムトークナイザーとステートメント認識機能が含まれており、外部の SQL 解析ライブラリは不要です

ディレクトリ構成

rules/
  common/
    spec_rules.py          # Version-independent dev-spec rules (SPEC001-SPEC035)
  v24.8/
    keywords.py            # 571 keywords (from CommonParsers.h APPLY_FOR_PARSER_KEYWORDS)
    grammar_rules.py       # 47 statement types
    token_types.py         # 52 token types (includes Spaceship <=>)
  v23.3/
    keywords.py            # 462 keywords (from Parser*.cpp ParserKeyword("...") calls)
    grammar_rules.py       # 47 statement types (no QUALIFY/PASTE JOIN/MODIFY REFRESH)
    token_types.py         # 49 token types (no Spaceship/Caret/Ellipsis)
  v22.3/
    keywords.py            # 422 keywords (from Parser*.cpp ParserKeyword("...") calls)
    grammar_rules.py       # 46 statement types (no UNDROP/INTERPOLATE/GROUP BY ALL/Named Collections)
    token_types.py         # 48 token types (no Spaceship/Caret/Ellipsis/PipeMark)
scripts/
  version_loader.py        # Dynamic version module loader
  ck_sql_tokenizer.py      # Tokenizer (version-aware via init_version())
  ck_sql_parser.py         # Parser (version-aware via init_version())
  ck_sql_checker.py        # Check engine (version-aware)

新しい ClickHouse バージョンを追加するには：

1. rules/v{version}/ ディレクトリを作成します
2. そのバージョンのカーネルソースから keywords、grammar_rules、token_types を抽出します
3. スキルが新しいバージョンを自動的に検出してサポートします