join_* セッション設定

これらの設定は system.settings で参照でき、ソースコード から自動生成されています。

使用する JOIN アルゴリズムを指定します。

複数のアルゴリズムを指定できます。特定のクエリでは、kind/strictness とテーブルエンジンに基づいて、利用可能なアルゴリズムが選択されます。

ほとんどのアルゴリズムは、クエリに対して選択された場合にのみ影響します。ただし、一部は、最終的に選択されない低優先度のフォールバックとして列挙されているだけでも、アルゴリズムの選択前に決定が行われるため、プランニングを変更します。このような影響は 2 つあります。

• 結合キーの型推論がより厳格になります (たとえば、merge join では String と Nullable(String) のように異なる型のキーを結合できません)。これにより USING カラムの結果型が変わる可能性があり、Join エンジンテーブルへの join が TYPE_MISMATCH で失敗することがあります。full_sorting_merge と parallel_full_sorting_merge によりトリガーされます。
• join の保持側にある ORDER BY ... LIMIT は、join によって順序付き読み取りが崩れるとみなされるため、primary-key 順の読み取りではなく明示的なソートを行います (merge join は join 前の独自のソートを挿入し、partial merge join は左 blocks を再ソートします。また、遅延 blocks を生成できる join も順序付き読み取りを伝播しません)。結果は同じですが、プランの効率は低下します。full_sorting_merge、parallel_full_sorting_merge、partial_merge、prefer_partial_merge、grace_hash、auto、およびゼロ以外の max_bytes_before_external_join / max_bytes_ratio_before_external_join によりトリガーされます。

どちらも、最終的にクエリが hash または別のアルゴリズムで実行される場合にも適用されます。これが望ましくない場合は、影響を受けるクエリの join_algorithm に上記のアルゴリズムを列挙しないでください。

設定可能な値:

• grace_hash

Grace hash join を使用します。Grace hash は、メモリ使用量を抑えつつ、複雑な結合を高い性能で実行できるアルゴリズムです。

grace join の最初のフェーズでは、右テーブルを読み取り、キーカラムの hash 値に応じて N 個の buckets に分割します (初期値の N は grace_hash_join_initial_buckets です) 。これは、各 bucket を独立して処理できるようにするためです。最初の bucket の行はインメモリの hash table に追加され、それ以外はディスクに保存されます。hash table がメモリ制限 (たとえば max_bytes_in_join で設定) を超えるまで大きくなった場合は、bucket 数が増やされ、各行の割り当て先 bucket が変更されます。現在の bucket に属さない行はフラッシュされ、再割り当てされます。

INNER/LEFT/RIGHT/FULL ALL/ANY JOIN をサポートします。

• hash

ハッシュ結合アルゴリズム を使用します。kind と strictness のすべての組み合わせに加え、JOIN ON 句で OR によって結合された複数の結合キーをサポートする、最も汎用的な実装です。

hash アルゴリズムを使用する場合、JOIN の右側は RAM に読み込まれます。

• parallel_hash

hash join の一種で、データを buckets に分割し、1 つではなく複数の hashtables を並行して構築することで、この処理を高速化します。

parallel_hash アルゴリズムを使用する場合、JOIN の右側は RAM に読み込まれます。

• partial_merge

sort-merge algorithm の一種で、右テーブルのみを完全にソートします。

RIGHT JOIN と FULL JOIN は ALL strictness の場合にのみサポートされます (SEMI、ANTI、ANY、ASOF はサポートされません) 。

partial_merge アルゴリズムを使用する場合、ClickHouse はデータをソートしてディスクに書き出します。ClickHouse の partial_merge アルゴリズムは、従来の実装とは若干異なります。まず、ClickHouse は右テーブルを結合キーで block 単位にソートし、ソート済み block に対する min-max 索引を作成します。次に、左テーブルの part を join key でソートし、右テーブルに対して結合します。min-max 索引は、不要な右テーブル block をスキップするためにも使用されます。

• direct

direct (nested loop とも呼ばれます) アルゴリズムは、左テーブルの行をキーとして右テーブルをルックアップします。 Dictionary、EmbeddedRocksDB、MergeTree テーブルなどの特別なストレージでサポートされています。

MergeTree テーブルでは、このアルゴリズムは結合キーフィルタをストレージ層に直接プッシュダウンします。キーでテーブルの primary key index を使ってルックアップできる場合は、より効率的になることがあります。そうでない場合は、左テーブルの各 block ごとに右テーブル全体をフルスキャンします。

INNER と LEFT joins のみをサポートし、他の条件を含まない単一カラムの等価結合キーにのみ対応します。

• auto

auto に設定すると、まず ハッシュ結合 を試し、メモリ制限を超えた場合は実行中に別のアルゴリズムへ切り替えます。

• full_sorting_merge

結合前に結合対象テーブルを完全にソートする Sort-merge algorithm です。

• ie_join

結合対象テーブルの式間に 2 つの不等比較 (<、<=、>、>=) を含む ON 句を持つ JOIN 向けの、ソートベースの IEJoin アルゴリズムです。ALL INNER/LEFT/RIGHT/FULL JOIN および SEMI/ANTI LEFT/RIGHT JOIN をサポートします。

リスト内の位置で優先順位が決まります。デフォルト値のように他のアルゴリズムの後に記載した場合、IEJoin はそれらが適用されない場合にのみ使用されます (ON 句に等価条件がない場合)。先頭に記載した場合、ON 句に 2 つの不等条件があれば常に使用されます。残りの条件 (等価条件を含む) は、ALL INNER JOIN では結合結果に対するフィルタとして適用され、その他の kind ではマッチングに影響する残余条件として operator 内で評価されます。リストに ie_join がない場合、不等条件のみを持つ INNER JOIN はフィルタ付きの CROSS JOIN として実行され、その他の kind はサポートされません。

結合前に両方の入力がメモリに蓄積されます。max_rows_in_join と max_bytes_in_join は、両側の蓄積された入力の合計を制限します (右側のみではありません)。overflow 時の動作は join_overflow_mode で設定します。operator が蓄積された入力上に構築するソート索引は、この制限にカウントされません。結合 operator 自体は単一スレッドで実行されます。並列化されるのは、入力の結合前ソートのみです。

• parallel_full_sorting_merge

full_sorting_merge と同じですが、hash と互換性のある等価結合は、単一の merge join ではなく、結合キーの hash によって独立した分片ごとの merge join に分割され、並列に実行されます (最大 max_threads)。これにより、すべてのスレッドを使用しながら merge join の低いストリーミングメモリ使用量を維持しますが、結果は順序付けられません。

結合キーによる hash 分片化は、hash が merge join の比較と一致するキー型での単純な等価結合にのみ適用され、どちらの側もすでにソートされていない場合に限られます。以下の場合はスキップされます:

• ASOF joins、および浮動小数点 / JSON / Object / Dynamic キー型: これらの hash は merge join の比較と一貫しないため、等しいキーが異なる分片に配置される可能性があります。
• すでにソートされている側 (順序どおりの MergeTree 読み取り、または事前にソートされた入力): 分片ごとの merge への順序保持 scatter により、パイプラインがデッドロックする可能性があります。代わりに、順序どおりの読み取りとその read_in_order_use_virtual_row 最適化が維持されます。
• initiator が distributed プラン (make_distributed_plan) を構築する場合: scatter されたソートはリモート実行用にシリアライズできないためです。ローカルの単一フラグメント プラン と worker ごとのフラグメントは、その設定を無効にして再最適化されるため、引き続き分片化できます。

これをスキップしても無効になるのはこの書き換えのみであり、一般的な並列性は無効になりません。結合は単一の full_sorting_merge として実行され、順序どおりに読み取る MergeTree 側は、query_plan_join_shard_by_pk_ranges が有効な場合、プライマリキー範囲によってソースで引き続き分片化できます (この範囲は結合で使用される比較と同じ比較で順序付けられるため、等しいキーは同じ場所に保持されます)。

• prefer_partial_merge

ClickHouse は、可能であれば常に partial_merge join を使用し、そうでない場合は hash を使用します。非推奨であり、partial_merge,hash と同じです。

• default (deprecated)

従来の値のため、今後は使用しないでください。 direct,hash と同じです。つまり、direct join と ハッシュ結合 をこの順で使用しようとします。

右テーブルで、あるキーに一致する行が複数ある場合の、ANY strictness を持つ JOIN演算の動作を変更します。

設定可能な値:

• 0 — 右テーブルに一致する行が複数ある場合、最初に見つかった 1 行だけが結合されます。
• 1 — 右テーブルに一致する行が複数ある場合、最後に見つかった 1 行だけが結合されます。

関連項目:

• JOIN 句
• Join テーブルエンジン
• join_default_strictness

JOIN clauses のデフォルトの strictness を設定します。

設定可能な値:

• ALL — 右テーブルに一致する行が複数ある場合、ClickHouse は一致した行のデカルト積を作成します。これは Standard SQL における通常の JOIN の動作です。
• ANY — 右テーブルに一致する行が複数ある場合、最初に見つかった 1 行だけを結合します。右テーブルに一致する行が 1 行しかない場合、ANY と ALL の結果は同じです。
• ASOF — あいまいな一致条件で数列を結合する場合に使用します。
• Empty string — クエリで ALL または ANY が指定されていない場合、ClickHouse では例外がスローされます。

MergeJoin がディスク上で実行される場合に、並列ソートで使用できるファイル数を制限します。

この設定値を大きくするほど、使用するRAMは増え、必要なディスクI/Oは少なくなります。

設定可能な値:

• 2以上の任意の正の整数。

ハッシュ結合で行リストで出力するかどうかを判断するための、右テーブルにおけるキーごとの平均行数の下限。

join が次のいずれかの制限に達したときに、ClickHouse がどのような動作を行うかを定義します。

• max_bytes_in_join
• max_rows_in_join

この設定が適用されるのは、join_algorithm の値が hash、parallel_hash、または ie_join の場合のみです。その他の アルゴリズム (たとえば partial_merge、grace_hash、auto) では、これらの 制限は異なる方法で処理されます。たとえば、ディスクへのスピル、再パーティション化、または 戦略の切り替えです。詳しくは join_algorithm を参照してください。

設定可能な値:

• THROW — ClickHouse は例外をスローしてクエリを停止します。
• BREAK — ClickHouse はクエリを停止し、例外はスローしません。

デフォルト値: THROW。

関連項目

• JOIN 句
• Join テーブルエンジン

JOIN の動作を設定します。テーブルを結合する際、空のセルが生じることがあります。ClickHouse はこの設定に応じて、それらを異なる方法で補完します。

設定可能な値:

• 0 — 空のセルは、対応するフィールド型のデフォルト値で補完されます。
• 1 — JOIN は Standard SQL と同じように動作します。対応するフィールドの型は Nullable に変換され、空のセルは NULL で補完されます。