EXPLAIN の種類
AST— 抽象構文木。SYNTAX— AST レベルでの最適化後のクエリテキスト。QUERY TREE— クエリツリー レベルでの最適化後のクエリツリー。PLAN— クエリ実行プラン。PIPELINE— クエリ実行パイプライン。
EXPLAIN AST
SELECT だけでなく、あらゆる種類のクエリをサポートします。
設定:
graph– DOT グラフ記述言語で記述されたグラフとして AST を出力します。デフォルト: 0。
EXPLAIN SYNTAX
oneline– クエリを1行で表示します。デフォルト:0。run_query_tree_passes– クエリツリーをダンプする前にクエリツリーパスを実行します。デフォルト:0。query_tree_passes–run_query_tree_passesが設定されている場合、実行するパス数を指定します。query_tree_passesを指定しない場合は、すべてのパスが実行されます。
Query
Response
run_query_tree_passes を指定した場合:
Query
Response
EXPLAIN QUERY TREE
run_passes— クエリツリーをダンプする前に、すべてのクエリツリーパスを実行します。デフォルト:1。dump_passes— クエリツリーをダンプする前に、使用されるパスの情報をダンプします。デフォルト:0。passes— 実行するパスの数を指定します。-1に設定すると、すべてのパスを実行します。デフォルト:-1。dump_tree— クエリツリーを表示します。デフォルト:1。dump_ast— クエリツリーから生成されたクエリ AST を表示します。デフォルト:0。
EXPLAIN PLAN
optimize— プランを表示する前に、クエリプランの最適化を適用するかどうかを制御します。デフォルト: 1。header— ステップの出力ヘッダーを表示します。デフォルト: 0。description— ステップの説明を表示します。デフォルト: 1。indexes— 使用された索引、フィルタリングされたパーツ数、および適用された各索引についてフィルタリングされたグラニュール数を表示します。デフォルト: 0。MergeTree テーブルでサポートされています。ClickHouse >= v25.9 以降、このステートメントが適切な出力を示すのは、SETTINGS use_query_condition_cache = 0, use_skip_indexes_on_data_read = 0とともに使用した場合のみです。projections— 解析されたすべてのプロジェクションと、プロジェクションの主キー条件に基づくパーツレベルのフィルタリングへの影響を表示します。各プロジェクションについて、このセクションには、プロジェクションの主キーを使って評価されたパーツ数、行数、マーク数、範囲数などの統計が含まれます。また、このフィルタリングにより、プロジェクション自体を読み取ることなくスキップされた data parts の数も表示します。プロジェクションが実際に読み取りに使用されたのか、それともフィルタリングのために解析されただけなのかは、descriptionフィールドで判別できます。デフォルト: 0。MergeTree テーブルでサポートされています。actions— ステップの actions に関する詳細情報を表示します。デフォルト: 1。sorting— ソート済みの出力を生成する各プランステップについて、ソートの説明を表示します。デフォルト: 0。keep_logical_steps— joins について、物理的な join 実装に変換せずに、論理プランステップを保持します。デフォルト: 0。json— クエリプランのステップを JSON フォーマットの 1 行として出力します。デフォルト: 0。不要なエスケープを避けるため、TabSeparatedRaw (TSVRaw) フォーマットの使用を推奨します。input_headers— ステップの入力ヘッダーを表示します。デフォルト: 0。主に、入力ヘッダーと出力ヘッダーの不一致に関する問題をデバッグする開発者にのみ有用です。column_structure— ヘッダー内のカラム構造を、名前と型に加えて表示します。デフォルト: 0。主に、入力ヘッダーと出力ヘッダーの不一致に関する問題をデバッグする開発者にのみ有用です。distributed— 分散テーブルまたは並列レプリカについて、リモートノードで実行されるクエリプランを表示します。jsonと同時にはサポートされません。デフォルト: 0。compact— 有効にすると、プランから expression ステップと詳細な action 情報 (入力、関数、別名、出力位置) を非表示にします。actions = 1の場合にのみ効果があります。デフォルト: 1。pretty— インデントの代わりに罫線文字 (├──、└──、│) を使ってプランツリーを表示し、階層構造を視覚化します。さらに、join ステップのプロパティもインラインで整形して表示します。デフォルト: 1。
デフォルトでは、
explain_query_plan_default = 'pretty' であるため、actions、compact、pretty は 1 に初期化され、プランはコンパクトで見やすく、action 注釈付きの形式で描画されます。EXPLAIN ステートメントでこれらのオプションのいずれかを明示的に指定した場合 (たとえば、EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) は、常にその指定がデフォルトを上書きします。ClickHouse 26.7 より前では、actions、compact、pretty のデフォルトは 0 でした。その出力は、explain_query_plan_default = 'legacy' を設定する (グローバル、またはクエリごとの SETTINGS で設定する) か、compatibility を 26.7 より古い任意のバージョンに設定することで、引き続き取得できます。json と distributed オプションでは、explain_query_plan_default = 'pretty' の場合でも、pretty のデフォルト (actions、compact、pretty) は有効になりません。出力に action の詳細を含めるには、actions = 1 を手動で設定してください。Step およびクエリのコスト見積もりはサポートされていません。
json = 1 の場合、クエリプランは JSON フォーマットで表されます。各ノードは辞書で、常に Node Type、Node Id、Plans のキーを持ちます。Node Type はステップ名を表す文字列で、Node Id は一意のステップ識別子です (数値の接尾辞が付いたステップ名。例: Union_10) 。Plans は子ステップの説明を含む配列です。その他の任意のキーは、ノードの種類や設定に応じて追加されることがあります。
例:
description = 1 の場合、Description キーがステップに追加されます。
header = 1 の場合、Header キーがカラムの配列としてステップに追加されます。
例:
indexes = 1 の場合、Indexes キーが追加されます。これには、使用された索引の配列が含まれます。各索引は JSON で記述され、Type キー (文字列 Partition Min-Max、Partition、Statistics、PrimaryKey または Skip) と、必要に応じて以下のキーを持ちます。
Name— 索引名 (現在はSkip索引でのみ使用) 。Keys— 索引で使用されるカラムの配列。Condition— 使用された条件。Description— 索引の説明 (現在はSkip索引でのみ使用) 。Parts— 索引の適用後/適用前のパーツ数。Granules— 索引の適用後/適用前のグラニュール数。Ranges— 索引の適用後のグラニュール範囲数。
projections = 1 を指定すると、Projections キーが追加されます。これには、分析されたプロジェクションの配列が含まれます。各プロジェクションは、以下のキーを持つ JSON として記述されます：
Name— プロジェクション名。Condition— プロジェクションで使用された主キー条件。Description— プロジェクションの使用方法の説明 (例: パーツレベルのフィルタリング) 。Selected Parts— プロジェクションによって選択されたパーツ数。Selected Marks— 選択されたマーク数。Selected Ranges— 選択された範囲数。Selected Rows— 選択された行数。Filtered Parts— パーツレベルのフィルタリングによってスキップされたパーツ数。
actions = 1 の場合、追加されるキーはステップの種類によって異なります。
例：
compact = 0 かつ actions = 1 を指定すると、Expression ステップとともに式に関する詳細情報を確認できます：
distributed = 1 を指定すると、出力にはローカルのクエリプランだけでなく、リモートノードで実行されるクエリプランも含まれます。これは、分散クエリの分析やデバッグに役立ちます。
distributed は、pretty 出力ではリモート分片のプランがプランツリーに統合されないため、legacy (非pretty) 形式でのみ表示されます。このため、distributed を有効にすると、explain_query_plan_default の値に関係なく、pretty のデフォルト設定 (actions、compact、pretty) は自動的に無効になります。なお、actions=1 は手動で設定できます。また、distributed オプションは json と併用できません。pretty = 1 を指定すると、プランツリーはインデントの代わりに罫線文字で表示され、主要なステップの追加情報も表示されます：
- クエリ出力カラム はプランの先頭に表示されます。
- フィルタ、集約キー、ソートの説明、ウィンドウ関数内の 式 は、人が読める SQL 風の表記で表示されます (例:
greater(plus(a, 1), 5)ではなくa + 1 > 5) 。わかりやすさのため、内部カラム識別子のプレフィックス (__table1.など) は削除されます。 - ソースステップ (
ReadFromMergeTreeなど) には、その出力カラムが表示されます。 - フィルタステップ には、SQL 表記のフィルタ条件が表示されます。ランタイム join フィルタが存在する場合は、それらは別個に表示されます。
- 集約ステップ には、キーと、引数付きの集約関数 (例:
sum(c)、count()) が表示されます。 - タプルリテラルの IN set にはその値が表示され (大きな set の場合は切り詰められます) 、サブクエリベースの set には
subquery1、subquery2などのラベルが付き、Setengine tables 由来の set にはテーブル名が表示されます。 - join ステップ には、数学的記法を用いた join 関係、推定結果行数、 およびどの出力カラムが左側と右側のどちらに由来するかが表示されます。異なる join タイプを 表すために、次の記号が使用されます：
たとえば、
t1 ⟕ t2 はテーブル t1 と t2 の left join を意味します。
テーブル名の後の角括弧内の数値 (例: t1[100]) は、テーブル統計が利用可能な場合の
推定行数を示します。
pretty オプションは compact = 1 と組み合わせると効果的で、Expression ステップと詳細な action 情報が非表示になるため、プランが読みやすくなります。
JOINを使った詳しい例:
EXPLAIN PIPELINE
header— 各出力ポートのヘッダーを表示します。デフォルト: 0。graph— DOT グラフ記述言語で記述されたグラフを表示します。デフォルト: 0。compact—graph設定が有効な場合、compact モードでグラフを表示します。デフォルト: 1。compact_repeated_processor_chains— テキスト出力で、隣接して繰り返されるプロセッサチェーンを、チェーンを 1 つだけ表示して繰り返し回数を付けることでコンパクトにします。これにより、たとえば JOIN で同じチェーンが何度も現れる場合に、並列パイプラインが読みやすくなります。グラフ出力には影響しません。デフォルト: 0。
compact=0 かつ graph=1 の場合、プロセッサ名には一意のプロセッサ識別子を示す追加の接尾辞が含まれます。
例:
EXPLAIN ESTIMATE
Query
Query
Response
EXPLAIN WHATIF
SELECT クエリにもたらす効果を見積もります。CREATE HYPOTHETICAL INDEX で 1 つ以上の候補を定義し、EXPLAIN WHATIF SELECT ... を実行すると、各候補について、適用可否、推定読み取りマーク数、推定バイト数、スキップ率を確認できます。
構文
empirical—1(デフォルト) では、スキップ率 (上限値) を測定するため、ベースラインで絞り込まれたグラニュールに対してメモリ内で索引を適用します。0ではその処理をスキップします。いずれの場合も、empiricalで結果が得られない場合 (無効になっている、または索引をメモリ内で評価できない場合) 、推定器はカラム STATISTICS にフォールバックし、それも利用できなければ、最終的に適用可否のみのサマリーにフォールバックします。
source— 推定値の算出方法を示します。empirical: ベースラインで pruned されたグラニュールを対象に、メモリ内で索引を構築し、その索引によってスキップされるグラニュール数を数えます。これは上限値です。制限事項についてはCREATE HYPOTHETICAL INDEXを参照してください。statistical: カラム STATISTICS から導出されます。empirical が無効化されている場合 (empirical = 0) 、または empirical で結果を生成できず、かつ関連するカラムにカラム STATISTICS が定義されている場合に使用されます。applicability_only: 索引は predicate に適用可能ですが、empirical と statistical のいずれでも結果を生成できなかったことを示します (たとえばempirical = 0でカラム STATISTICS が定義されていない場合) 。保守的な上限としてskip_ratio: 0.0%を返します。
sampled_parts/sampled_marks—<baseline-pruned> / <total in the table>。テーブル全体のうち、PK、partition、既存の索引による pruning を通過した割合、つまり仮想索引への入力となる部分を示します。est_bytes— 読み取られるバイト数の推定値です。テーブルの平均行サイズから導出されるため概算であり、ストレージや圧縮によって変動します。ベースラインの行はクエリが行を読み取る場合にのみ表示され、候補ごとの行はベースラインのバイト推定値がわかっている場合にのみ表示されます。
WHATIF と SELECT の間にインラインで記述します。SETTINGS キーワードはありません (これは、他の EXPLAIN バリアントでオプションを受け付ける方法と一致しています) 。
テーブルに仮想索引が定義されていない場合、EXPLAIN WHATIF は status: not_applicable を返し、作成を促すヒントを表示します。
Empirical の例
minmax を使うと、100 個のマークを 1 個まで絞り込めます — skip_ratio: 99.0%。(est_bytes は平均行サイズに基づく推定値のため、正確な値は変動します。)
統計の例
カラム STATISTICSはデフォルトで無効になっています。statistical パスを試すには、まず対象のカラムでこれらを定義し、materialize mutation が完了するまで待ちます:
b < 10 のカラム STATISTICS における選択性 (10000 行中およそ 10 行) に基づくもので、skip_ratio の上限として報告されます。sampled_parts / sampled_marks はなく、データは読み取られていません。
どちらの方法も利用できない場合 (たとえば empirical = 0 で、かつカラム STATISTICS が定義されていない場合) 、推定器は source: applicability_only と保守的な skip_ratio: 0.0% を報告します。
EXPLAIN TABLE OVERRIDE
Query
Query
Response
検証は完全ではないため、クエリが成功しても、そのオーバーライドが問題を引き起こさないことは保証されません。