SQL 整形の仕組み
SQL 整形はレクサー駆動の書き換えで、クエリ内のすべてのトークンを走査し、選択した方言のルールに基づいてその周囲の空白を再出力します。クエリの意味は変わらず、レイアウトだけが変わります。
- 方言を選択する. MySQL のバッククォート、PostgreSQL の
::キャスト、BigQuery のドット区切りテーブルパス、T-SQL の角括弧識別子はそれぞれ専用のトークナイザーが必要です。方言セレクターが適用する文法を決定します。 - 入力をトークン化する. フォーマッターはクエリをトークンのストリームに分割します: キーワード（
SELECT、JOIN）、識別子、リテラル、演算子、括弧、コメント。文字列リテラルと引用符付き識別子はそのまま渡され、方言固有の構文が維持されます。 - レイアウトルールを適用する. トップレベルの節（
SELECT、FROM、WHERE、GROUP BY、ORDER BY）はそれぞれ独立した行に配置されます。選択リストと列リストのカンマ区切り式は各1行ずつ、選択したインデント単位でインデントされます。 - キーワードケースを適用する. キーワードケーストグルは認識されたSQL キーワードを大文字・小文字に書き換えるか、入力のケースをそのまま保持します。識別子は変更されません — 列名とテーブル名は常に記述どおりに出力されます。
- 整形済み文字列を出力する. トークンストリームはインデント文字（スペース2つ、4つ、またはタブ）と設定された改行ルールで一つの文字列に結合されます。リアルタイムモードでは入力中に 200ms のデバウンスでパイプライン全体が再実行されます。
SQL を整形する理由
- Pull request の diff 可読性. 200行のCTE を一行に書き換えるとコードレビューが推測ゲームになります。一貫した整形により diff が実際の変更 — 新しい列、追加の
JOIN、異なるWHERE条件 — に絞られ、レビュアーは空白を解読せずに変更を確認できます。 - デバッグの容易さ. クエリが間違った行数を返す場合、まず行単位で読みます。整形されたSQL は各
JOINを独立した行に配置し、WHERE条件を揃えるので、欠けたANDや余分なORが一目でわかります。 - チームスタイルの統一. 多くのチームがSQL スタイルガイドを採用し（dbt Labs、GitLab、Mode Analytics が公開）、コミットされたクエリがそれに従うことを望んでいます。コミット前にフォーマッターを実行することでレビューからスタイル議論を排除し、ロジックだけを議論できます。
- ドキュメントでSQL を共有する. ランブック、インシデントレトロ、Notion ドキュメントはいずれも上から下に読めるSQL から恩恵を受けます。整形済みSQL はフェンス付きコードブロックにきれいに貼り付けられ、PDF エクスポートでキーワードの途中で折り返すことなく予測どおりに印刷されます。
一般的な活用例
SQL 整形は分析エンジニアリング、バックエンド開発、運用作業において、クエリを書いていない人が読む必要があるときに常に登場します。
- 分析エンジニアリング: dbt プロジェクトの pre-commit フックで全モデルファイルを再整形し、PR diff がロジック変更に絞られ空白の乱れが含まれないようにする。
- データベース管理: slow-query ログの一行エントリを貼り付けて整形し、インシデントレトロを書きながらジョイン順序を確認する。
- ドキュメント作成: Looker Explore や Tableau ワークブックからクエリを取り出してランブック向けに整形し、オンコールチームがそのままコピー&ペーストできる例として埋め込む。
実際の例
SELECT u.id,u.email,COUNT(o.id) FROM users u LEFT JOIN orders o ON o.user_id=u.id WHERE u.created_at > '2024-01-01' GROUP BY u.id,u.email ORDER BY u.id; を入力パネルに貼り付け、方言 PostgreSQL、インデント スペース2つ、キーワードケース 大文字 で整形します。出力では SELECT、FROM、LEFT JOIN、WHERE、GROUP BY、ORDER BY がそれぞれ独立した行に配置され、選択リストと group-by リストの各列がインデントされた行を占め、ON 条件は所属する JOIN キーワードより一段深くインデントされます。
FAQ
どのSQL 方言をサポートしていますか？
方言ドロップダウンには標準SQL、MySQL、PostgreSQL、SQLite、MariaDB、Transact-SQL（SQL Server / Azure SQL）、BigQuery、Snowflake、Redshift が含まれます。基盤となる sql-formatter ライブラリは DuckDB、Spark SQL、Hive、Trino、Db2、N1QL、PL/SQL、ClickHouse、TiDB、SingleStoreDB も認識します — 最も近い方言を選べばリストにない対象でも妥当な出力が得られます。識別子、文字列リテラル、方言固有の演算子（PostgreSQL @>、BigQuery SAFE. プレフィックス）はそのまま保持されます。
このツールはSQL を検証しますか？
いいえ。フォーマッターは語彙的書き換えエンジンであり、パーサーではありません。入力をトークン化してレイアウトルールを適用し結果を出力するだけで、クエリが意味的に有効か、参照されたテーブルが存在するか、選択した方言で構文が正しいかは確認しません。実際の正しさを確認するには、整形済み出力を実際のデータベース（またはSQLFluff 等のSQL リンター）で実行してください。
キーワードが大文字に変換されるのはなぜですか？
キーワードケースのドロップダウンは、ほとんどの公開SQL スタイルガイド（dbt Labs、Mode、GitLab）の慣例に合わせてデフォルトが大文字です。チームが小文字の select / from を使う場合は 小文字 に切り替え、入力のケースを保持したい場合は 維持 を選択してください。識別子は一切変更されません。
クエリはどこかにアップロードされますか？
いいえ。バンドルされた sql-formatter ライブラリがブラウザー内で動作し、整形はローカルマシン上で行われ、クエリのテキストはネットワークを通りません。このページが行う唯一の外部リクエストは、tools.ultim8soft.com の全ページが共通して行う分析・広告リクエストであり、SQL テキストはそのいずれの一部でもありません。
整形されたSQL はフォーマッターが処理すればスタイル議論ではなくなります。このツールはブラウザー内で完全に動作し、クエリはページを離れることなく、sql-formatter npm パッケージと同じ方言対応トークナイザーが書き換えを行います。