その他のセッション設定 - ClickHouse Documentation

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

adaptive_aggregator_freeze_threshold

アダプティブアグリゲータがスレッドのローカルハッシュテーブルを凍結するキー数です (enable_adaptive_aggregator を参照) 。値を小さくすると、凍結されたテーブルはキャッシュに収まりやすくなり、大きくすると頻出キーをより多く保持できます。0 を指定すると、最初の機会にテーブルを凍結します。この場合、アルゴリズムはキー hash による純粋な分片と同様に動作します。各キーは hash によってルーティングされ、単一の所有者によって集計されますが、スキャン中にスレッド間で交換されるのではなく、マージフェーズまで処理が延期されます。

adaptive_aggregator_freeze_threshold_bytes

アダプティブアグリゲータがスレッドのローカルハッシュテーブルを凍結するメモリサイズです (enable_adaptive_aggregator を参照) 。この値と adaptive_aggregator_freeze_threshold のうち、先に達した方でテーブルが凍結されます。サイズは、ローカルテーブル自体が割り当てたバイト数 (ハッシュテーブルの buffer とそのアリーナ) であり、block 間で確認されます。キーまたは aggregation state が wide な場合、このバイト上限が重要になります。キー数のしきい値だけでは、そのようなテーブルが CPU cache を超えるほど大きくなる可能性があります。デフォルト値では、通常のキー幅および state 幅のテーブルは引き続きキー数によって凍結されます。0 を指定するとバイト上限が無効になり、キー数のしきい値のみで決まります。

add_http_cors_header

HTTP CORS ヘッダーを追加して書き込みます。

analyze_index_with_space_filling_curves

テーブルの索引に空間充填曲線が含まれている場合 (例: ORDER BY mortonEncode(x, y) や ORDER BY hilbertEncode(x, y)) 、クエリにその引数に対する条件 (例: x >= 10 AND x <= 20 AND y >= 20 AND y <= 30) があるときは、索引解析に空間充填曲線を使用します。現在、曲線の実装では各引数に32ビットしか使用していないため、2次元解析では UInt64 引数を持つ曲線はスキップされます。

analyzer_inline_views

有効にすると、アナライザは通常の (非マテリアライズドかつ非パラメータ化された) ビューを、それを定義するサブクエリで置き換えます。これにより、述語プッシュダウンやカラムのプルーニングなど、ビュー境界をまたぐ最適化が可能になります。

any_join_distinct_right_table_keys

ANY INNER|LEFT JOIN 操作で従来の ClickHouse server の動作を有効にします。

この設定は、ユースケースが従来の JOIN の動作に依存している場合に限り、後方互換性のために使用してください。

従来の動作が有効な場合:

ClickHouse は左から右へのテーブルキーの多対一マッピングというロジックを使用するため、t1 ANY LEFT JOIN t2 と t2 ANY RIGHT JOIN t1 の結果は同一になりません。
ANY INNER JOIN 操作の結果には、SEMI LEFT JOIN 操作と同様に、左テーブルのすべての行が含まれます。

従来の動作が無効な場合:

ClickHouse は ANY RIGHT JOIN 操作で一対多のキーマッピングを行うロジックを使用するため、t1 ANY LEFT JOIN t2 と t2 ANY RIGHT JOIN t1 の結果は同一になります。
ANY INNER JOIN 操作の結果には、左テーブルと右テーブルの両方について、キーごとに 1 行が含まれます。

設定可能な値:

0 — 従来の動作は無効です。
1 — 従来の動作は有効です。

archive_adaptive_buffer_max_size_bytes

アーカイブファイル (たとえば tar アーカイブ) への書き込み時に使用されるアダプティブバッファの最大サイズを制限します

arrow_flight_request_descriptor_type

Arrow Flight リクエストで使用するディスクリプタの種類です。‘path’ はデータセット名をパスディスクリプタとして送信します。‘command’ は SQL クエリを command ディスクリプタとして送信します (Dremio では必須) 。設定可能な値:

‘path’ — FlightDescriptor::Path を使用します (デフォルト。ほとんどの Arrow Flight サーバーで動作します)
‘command’ — SELECT クエリとともに FlightDescriptor::Command を使用します (Dremio では必須)

backup_slow_all_threads_after_retryable_s3_error

true に設定すると、同じバックアップエンドポイントに対して S3 リクエストを実行しているすべてのスレッドが、いずれか 1 つの S3 リクエストで ‘Slow Down’ などの再試行可能な S3 エラーが発生した後に遅延されます。 false に設定すると、各スレッドは他のスレッドとは独立して、S3 リクエストのバックオフを処理します。

cache_warmer_threads

ClickHouse Cloudでのみ有効です。cache_populated_by_fetch が有効な場合に、新しいデータパーツをファイルシステムキャッシュへ先読み的にダウンロードするバックグラウンドスレッド数です。無効にするには 0 を指定します。

calculate_text_stack_trace

クエリ実行中に例外が発生した場合に、テキスト形式のスタックトレースを計算します。これがデフォルトです。これにはシンボルのルックアップが必要なため、大量の不正なクエリが実行されると、ファジングテストが遅くなることがあります。通常、このオプションを無効にすべきではありません。

cancel_http_readonly_queries_on_client_close

クライアントがレスポンスを待たずに接続を閉じた場合、HTTP の読み取り専用クエリ (例: SELECT) をキャンセルします。 Cloud でのデフォルト値: 1.

cascades_aggregation_pushdown

Cascades オプティマイザーにおいて、部分集約を join の下にプッシュダウンする (即時実行集約) ことを、コストベースの選択肢の1つとして検討します。 enable_cascades_optimizer = 1 および make_distributed_plan = 1 と併用した場合にのみ有効になります。

checksum_on_read

読み取り時にチェックサムを検証します。これはデフォルトで有効になっており、本番環境では常に有効にしておくべきです。この設定を無効にしても、利点が得られることはありません。使用するのは、実験やベンチマークの場合のみにしてください。この設定が適用されるのは、MergeTree family のテーブルのみです。その他のテーブルエンジンや、ネットワーク経由でデータを受信する場合は、チェックサムは常に検証されます。

圧縮

レスポンスボディに汎用圧縮を適用します。例: compression=gz。これは Content-Encoding (HTTP 圧縮) および従来の compress パラメータ (ClickHouse ネイティブ圧縮) とは独立しています。URL パスで圧縮ファイルの拡張子を指定することも同等です。これは HTTP インターフェイスのレスポンス整形設定です。クエリの実行前に処理され (レスポンスバッファは事前に設定されるため) 、HTTP URL パラメータ、URL パスのファイル拡張子、またはユーザープロファイルを介して指定する必要があります。クエリ内の SETTINGS 句で指定しても効果はなく、拒否されます。

connection_pool_max_wait_ms

接続プールが満杯の場合に、接続を待機する時間 (ミリ秒) 。接続プールはレプリカごとに1つ存在するため、この待機はレプリカ単位で適用されます。待機時間が経過すると、その試行は NO_FREE_CONNECTION で失敗します。分散 SELECT が使用するフェイルオーバー経路では、これは使用できないその他のレプリカと同様に扱われます。つまりクエリは残りのレプリカを試行し、そのすべてを試し終えて初めて ALL_CONNECTION_TRIES_FAILED で失敗します。したがって、この設定でクエリ全体の時間が制限されるわけではありません。N 個のレプリカがあり、それぞれ T 回試行する場合、合計の待機時間は connection_pool_max_wait_ms × N × T に達する可能性があります。ここで T は connections_with_failover_max_tries ですが、レプリカは除外される前に必ず一度は試行されるため、1 を下回ることはありません。クエリ自体を制限するには max_execution_time を使用してください。 skip_unavailable_shards によってこれが抑制されることはありません。イニシエーターに空き接続 slot がなかったレプリカにはそもそも接続が行われていないため、その分片は使用不可とは扱われません。設定可能な値:

正の整数。
0 — 無制限のタイムアウト。この場合でも待機は KILL QUERY によって中断され、また timeout_overflow_mode が既定値の throw であれば max_execution_time によっても中断されます。 break の場合は時間制限によってクエリがキャンセルされないため、接続が解放されるまで待機が続きます。KILL QUERY による中断は引き続き有効です。

connections_with_failover_max_tries

Distributed テーブルエンジンで、各レプリカに対して行う接続試行の最大回数。

convert_query_to_cnf

true に設定すると、SELECT クエリは連言標準形 (CNF) に変換されます。クエリを CNF に書き換えることで、実行が高速になる場合があります (詳しくはこの Github issue を参照してください) 。たとえば、次の SELECT クエリは変更されません (デフォルトの動作) :

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = false;

結果は次のとおりです：

┌─explain────────────────────────────────────────────────────────┐
│ SELECT x                                                       │
│ FROM                                                           │
│ (                                                              │
│     SELECT number AS x                                         │
│     FROM numbers(20)                                           │
│     WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │
│ ) AS a                                                         │
│ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))     │
│ SETTINGS convert_query_to_cnf = 0                              │
└────────────────────────────────────────────────────────────────┘

convert_query_to_cnf を true に設定して、何が変わるか見てみましょう。

EXPLAIN SYNTAX
SELECT *
FROM
(
    SELECT number AS x
    FROM numbers(20)
) AS a
WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
SETTINGS convert_query_to_cnf = true;

WHERE句は CNF に書き換えられていますが、結果セットはまったく同じで、ブール値の論理は変わっていません：

┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ SELECT x                                                                                                              │
│ FROM                                                                                                                  │
│ (                                                                                                                     │
│     SELECT number AS x                                                                                                │
│     FROM numbers(20)                                                                                                  │
│     WHERE ((x <= 15) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x >= 10) OR (x >= 1)) │
│ ) AS a                                                                                                                │
│ WHERE ((x >= 10) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x <= 15) OR (x <= 5))     │
│ SETTINGS convert_query_to_cnf = 1                                                                                     │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

設定可能な値: true, false

count_matches_stop_at_empty_match

countMatches 関数では、パターンが長さ 0 に一致した時点でカウントを停止します。

cross_to_inner_join_rewrite

WHERE 句に結合条件となる式がある場合、comma/cross join の代わりに inner join を使用します。値: 0 - 書き換えなし、1 - 可能な場合は comma/cross に適用、2 - すべての comma join を強制的に書き換え、cross は可能な場合に書き換え

data_type_default_nullable

カラム定義で明示的な修飾子 NULL or NOT NULL を指定しないデータ型を、Nullable として扱うかどうかを指定します。設定可能な値:

1 — カラム定義のデータ型は、デフォルトで Nullable に設定されます。
0 — カラム定義のデータ型は、デフォルトで Nullable に設定されません。

decimal_check_overflow

Decimal の算術/比較演算でオーバーフローをチェックします

deduplicate_blocks_in_dependent_materialized_views

Replicated* テーブルからデータを受け取る materialized view に対する重複排除チェックを有効または無効にします。設定可能な値:

0 — 無効。
1 — 有効。

有効にすると、ClickHouse は Replicated* テーブルに依存する materialized view 内のブロックに対して重複排除を実行します。この設定は、障害によって挿入処理が再試行される場合に、materialized view に重複データが含まれないようにするのに役立ちます。 関連項目

IN 演算子における NULL の処理

defer_partition_pruning_after_final

有効な場合 (デフォルト) 、パーティションキーカラムがソートキーに含まれていないテーブルに対する FINAL クエリでは、パーティションプルーニングはスキップされます。これは 26.3 で導入された、正しさを優先した動作です。FINAL では、同じ主キーを共有しながら異なるパーティションに存在する行を重複排除する必要が生じる場合があり、パーティションプルーニングを行うと、そのような行が重複排除の対象から気づかれないまま除外される可能性があります。無効な場合は、FINAL を使用していてもパーティションプルーニングが適用され、26.3 より前の動作に戻ります。これは、パーティションカラムに対する WHERE 条件を含むクエリでは大幅に高速になる可能性がありますが、同じ主キーを持つ行が異なるパーティションに存在しない場合にのみ正しい動作となります。たとえば、パーティションカラムが insert 時に設定され、その後は変更されないイベントログテーブルなどです。この設定が影響するのは、パーティションキーカラムがソートキーに含まれていないパーティションテーブルだけです。その他のテーブルでは、パーティションプルーニングは常に適用されます。設定可能な値:

0 — FINAL の前にパーティションプルーニングを適用します (26.3 より前の動作。高速ですが、一般的には安全ではありません) 。
1 — FINAL の後までパーティションプルーニングを遅らせます (デフォルト。正しさを優先) 。

describe_compact_output

true の場合、DESCRIBE クエリの結果にはカラム名と型のみが含まれます

dialect

クエリの解析に使用するdialect。サポートされる値:

clickhouse (デフォルト) — 標準のClickHouse SQL。
kusto — Kusto Query Language。実験的設定のallow_experimental_kusto_dialectが必要です。
prql — PRQL。実験的設定のallow_experimental_prql_dialectが必要です。
polyglot — 他のdialect (MySQL、PostgreSQLなど) のSQLをClickHouse SQLにトランスパイルします。実験的設定のallow_experimental_polyglot_dialectが必要です。
promql — promql_database、promql_table、promql_evaluation_time設定で構成されたTimeSeriesテーブルに対して評価されるPromQL (Prometheus Query Language) 。
clickhouse_json — SQLテキストの代わりに、クエリをJSON AST (parseQueryToJSONの出力) として解釈します。dialectを元に戻せるよう、SETクエリは引き続き通常の形式で認識されます。実験的設定のenable_json_ast_dialectが必要です。
trino — Trino SQL: Trinoの構文 (ARRAY[...]、TRY_CAST、UNNESTなど) を変換し、Trinoの関数名をClickHouseの同等のものにマッピングします。実験的設定のenable_trino_dialectが必要です。

discard_query_data

有効にすると、サーバーはクエリ結果の行をクライアントに送信しなくなります。クエリ自体は引き続き実行され、サーバー上で完全に記録されます。また、クライアントはそれ以外のパケットを引き続き受信します。シャドートラフィック、ベンチマーク、ファジングで使用します。セカンダリクエリには影響しません。ネイティブ TCP プロトコルにのみ適用されます。

distinct_overflow_mode

データ量がいずれかの上限を超えたときの動作を設定します。設定可能な値:

throw: 例外をスローします (デフォルト) 。
break: クエリの実行を停止し、データソースが尽きたかのように部分的な結果を返します。

do_not_merge_across_partitions_select_final

異なるパーティション間でのマージを避けることで、FINAL クエリを最適化します。有効にすると、SELECT FINAL クエリの実行時に、異なるパーティションのパーツがまとめてマージされることはありません。代わりに、マージは各パーティション内でのみ個別に行われます。これにより、パーティション化されたテーブルを扱う際のクエリパフォーマンスを大幅に向上させることができます。

dynamic_throw_on_type_mismatch

デフォルト実装を使用して Dynamic カラムに関数を適用する際、実際の型がその関数に適合しない行に対してどのように動作するかを制御します。

true (デフォルト) — 例外をスローします。
false — 代わりに、それらの行では NULL を返します。

enforce_strict_identifier_format

有効にすると、英数字とアンダースコアのみを含む識別子だけが許可されます。

engine_url_skip_empty_files

URL エンジンのテーブルで空のファイルをスキップするかどうかを有効または無効にします。設定可能な値:

0 — 空のファイルが要求されたフォーマットと互換性がない場合、SELECT は例外をスローします。
1 — 空のファイルに対して、SELECT は空の結果を返します。

exact_rows_before_limit

有効にすると、ClickHouse は rows_before_limit_at_least 統計の正確な値を返しますが、その代わり、limit より前のデータを最後まで完全に読み取る必要があります

except_default_mode

EXCEPTクエリのデフォルトモードを設定します。設定可能な値: 空文字列、‘ALL’、‘DISTINCT’。空文字列の場合、モードを指定しないクエリは例外を返します。

exclude_materialize_skip_indexes_on_insert

指定したスキップ索引を、INSERT 時の構築および保存の対象から除外します。除外されたスキップ索引は、マージ中または明示的な MATERIALIZE INDEXクエリによって引き続き構築および保存されます。 materialize_skip_indexes_on_insert が false の場合、この設定は効果を持ちません。例:

CREATE TABLE tab
(
    a UInt64,
    b UInt64,
    INDEX idx_a a TYPE minmax,
    INDEX idx_b b TYPE set(3)
)
ENGINE = MergeTree ORDER BY tuple();

SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a will be not be updated upon insert
--SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- neither index would be updated on insert

INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- only idx_b is updated

-- since it is a session setting it can be set on a per-query level
INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b';

ALTER TABLE tab MATERIALIZE INDEX idx_a; -- this query can be used to explicitly materialize the index

SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default

execute_exists_as_scalar_subquery

相関しない EXISTS サブクエリをスカラーサブクエリとして実行します。スカラーサブクエリと同様に cache が使用され、結果には定数畳み込みが適用されます。 Cloud でのデフォルト値: 0.

explain_query_plan_default

EXPLAIN PLAN で使用されるデフォルトのフォーマットです。設定可能な値:

pretty (26.7 以降のデフォルト) — actions、compact、pretty はデフォルトで true となり、コンパクトで見やすく、actions の注釈が付いたプランを生成します。
legacy — 26.7 より前の出力。

EXPLAIN ステートメントで actions、compact、または pretty オプションを明示的に指定した場合 (たとえば EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) 、常にこの設定よりも明示指定の方が優先されます。 json = 1 または distributed = 1 を指定した EXPLAIN PLAN では、actions、compact、または pretty が明示的に設定されていない限り、この設定に関係なく従来の (26.7 より前の) デフォルトが使われます。pretty 出力では JSON の結果や分片ごとの分散実行プランを表現できないため、これらのモードは legacy 形式でのみ正しくレンダリングされます。

explain_syntax_single_record

EXPLAIN SYNTAX の出力を、行ごとに 1 レコードではなく 1 つのレコード (埋め込み改行を含む) として返します。これにより、結果は復元可能な単一の行になります (たとえば、SELECT count() FROM (EXPLAIN SYNTAX ...) は 1 を返します) 。 EXPLAIN SYNTAX ステートメントで single_record オプションを明示的に指定した場合 (たとえば、EXPLAIN SYNTAX single_record = 0 SELECT ...) 、この設定より常に優先されます。 26.8 より前の行ごとに 1 レコードを返す出力に戻すには、false に設定するか、compatibility を 26.8 より前の任意のバージョンに設定します。

extract_key_value_pairs_max_pairs_per_row

別名: extract_kvp_max_pairs_per_row extractKeyValuePairs 関数で生成可能なペアの最大数。メモリを過剰に消費しないようにするための保護策として使用されます。

extremes

極値 (クエリ結果の各カラムにおける最小値と最大値) を計算するかどうかを指定します。0 または 1 を指定できます。デフォルトは 0 (無効) です。詳細については、「Extreme values」セクションを参照してください。

fallback_to_stale_replicas_for_distributed_queries

更新済みのデータを利用できない場合、古いレプリカに対してクエリを強制的に実行します。Replicationを参照してください。 ClickHouse は、テーブルの古いレプリカの中から最も適切なものを選択します。レプリケートテーブルを参照する分散テーブルに対して SELECT を実行する際に使用されます。デフォルト値は 1 (有効) です。

file_like_engine_default_partition_strategy

ファイル系テーブルエンジンのデフォルトのパーティション方式。glob または {_partition_id} プレースホルダーを含まないパスを持つ CREATE クエリにのみ適用されます。{_partition_id} を含むパスでは常に wildcard が使用されます。別の glob を含むパスではパーティション方式は使用されず、PARTITION BY は無視されます。この設定が wildcard であってもパスに {_partition_id} がない場合は、パーティション方式は使用されません。この決定をエンジン引数に永続化できないテーブルエンジン (例: HDFS) は、このような CREATE を拒否します。

filesystem_prefetches_limit

prefetch の最大数です。0 は無制限を意味します。prefetch の数を制限したい場合は、設定 filesystem_prefetches_max_memory_usage を使用することを推奨します

filter

クエリをラップするサブクエリとして WHERE 句を追加します。複数のフィルターは AND で結合されます。HTTP インターフェイスでは複数の filter URL パラメータを指定でき、それらは指定順に AND で結合され、この設定の値とも AND で結合されます。これは、解析済みクエリにエンジンが適用するクエリ構築設定です (派生テーブルとしてラップします) 。そのため既存のクエリと組み合わせて使用でき、すべてのプロトコルで機能します。HTTP URL パラメータ、クエリ内の SETTINGS clause、またはユーザープロファイルで指定できます。結果を返す SELECT / UNION クエリの形を変更します。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソース SELECT 自身の SETTINGS clauseに指定されている場合にのみ有効です。プロファイルまたはセッションから継承された値、あるいは INSERT / CREATE ステートメント自体に設定された値は、ソース SELECT には伝播しません。これは、他のすべての設定にも適用される非伝播ルールと同じです。

filter はアクセス制御の仕組みではなく、行レベルセキュリティポリシーや additional_table_filters 設定の代替として使用してはなりません。ラップするサブクエリに WHERE を追加するだけであるため、フィルターが適用される前に基盤となるデータが読み取られ、処理されます。クエリは処理中にフィルターで除外された行を観測できます (たとえば、throwIf を使用してエラーパス経由で情報を漏えいさせることができます) 。ユーザーがアクセスできる行を制限することが目的の場合は、行レベルセキュリティまたは additional_table_filters を使用してください。

final

クエリ内のすべてのテーブルのうち、FINAL を適用できるものに対して、FINAL 修飾子を自動的に適用します。これには、結合されたテーブル、サブクエリ内のテーブル、および分散テーブルが含まれます。設定可能な値:

0 - 無効
1 - 有効

例:

CREATE TABLE test
(
    key Int64,
    some String
)
ENGINE = ReplacingMergeTree
ORDER BY key;

INSERT INTO test FORMAT Values (1, 'first');
INSERT INTO test FORMAT Values (1, 'second');

SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘
┌─key─┬─some──┐
│   1 │ first │
└─────┴───────┘

SELECT * FROM test SETTINGS final = 1;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

SET final = 1;
SELECT * FROM test;
┌─key─┬─some───┐
│   1 │ second │
└─────┴────────┘

finalize_projection_parts_synchronously

有効にすると、INSERT 中にプロジェクションパーツが同期的にファイナライズされ、S3 アップロードの並列度は下がるものの、ピークメモリ使用量を削減できます。デフォルトでは、各プロジェクションの出力ストリームは、パーツ全体 (すべてのプロジェクションを含む) のファイナライズが完了するまで維持されます。これにより S3 アップロードを並行して実行できますが、ピークメモリはプロジェクション数に比例して増加します。この設定が影響するのは INSERT パスのみで、merge と mutation ではすでにプロジェクションが同期的にファイナライズされます。

flatten_nested

nestedカラムのデータフォーマットを指定します。設定可能な値:

1 — Nested カラムは個別の配列にフラット化されます。
0 — Nested カラムは単一のタプル配列のまま保持されます。

使用法 この設定を 0 にすると、任意のレベルのネストを使用できます。例クエリ:

SET flatten_nested = 1;
CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

結果:

┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n.a` Array(UInt32),
    `n.b` Array(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

クエリ:

SET flatten_nested = 0;

CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();

SHOW CREATE TABLE t_nest;

結果:

┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n` Nested(a UInt32, b UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

format

クエリの入力と出力の両方の FORMAT をオーバーライドします。クエリまたはファイル拡張子で指定されたフォーマットよりも優先されます。より具体的な input_format および output_format 設定は、それぞれ入力と出力について、この汎用的な format 設定より優先されます。

framing_output_format

クエリ応答のさまざまな部分を単一ストリームに多重化できます。データの chunk、totals と extremes、progress パケット、profile events (メトリクス) 、サーバーログなど、ネイティブプロトコルがサポートするすべてが対象です。フレーミングフォーマットは出力フォーマットとは独立しています。任意の出力フォーマットで生成されたバイトを、そのバイト列の chunk を分離し、必要に応じてエンコードすることでカプセル化します。すべての data、totals、extremes パケットのペイロードを連結したものは、フレーミングなしで出力フォーマットが生成する内容と完全に一致します。補助パケット (progress、ログ、profile events、exceptions) は JSON で表現されます。意図的な例外が 1 つあります。totals と extremes を表現できないため通常の出力では省略する出力フォーマット (JSONCompactEachRow ファミリー) は、フレーミング使用時には totals および extremes パケットにそれらを出力します。このようなフォーマットでは、data パケットのみを連結したものがフレーミングなしの出力と完全に一致し、totals および extremes パケットにはフレーミングなしの出力には含まれない追加の行が格納されます。サーバーログは send_logs_level 設定が指定されている場合に含まれ、profile events は send_profile_events 設定が有効な場合に含まれます (これらは interactive_delay マイクロ秒ごとに最大 1 回送信され、progress パケットも interactive_delay によりスロットリングされます) 。成功したストリームは、ネイティブプロトコルの最終 progress パケットと同様に、クエリ終了時のロギングで出力される末尾の log および profile_events パケットの後に書き込まれる、最終カウンター (result_rows、result_bytes、memory_usage) を含む最終 progress パケットで終了します。失敗時には、exception パケットが最後のパケットになります。ただし、パケットストリームの一部がすでに応答として出力され、破棄できなくなった後に失敗が発生した場合は例外です (パケット書き込みが途中で失敗した場合、exception パケット自体の配信に失敗した場合、またはフラッシュやクローズ中に応答ストリームが失敗した場合) 。この場合、フレーミングはフェイルクローズとなります。つまり、ストリームは終端 exception パケットなしで終了し、クライアントには解析可能な終端パケットではなく、切り詰められた応答と中断された HTTP 接続が示されます。部分的なパケットストリームの後に何かが追加されることはないため、通常の HTTP エラー本文がそこに混在することはありません。クエリが自身の SETTINGS clause によってのみ有効化するもの (フレーミングフォーマット、send_logs_level、send_profile_events) は、クエリがパースされるまで判明しません。そのため、対応するログおよび profile events はクエリ実行以降でのみキャプチャされます。パース、プラン、分析フェーズのログおよび profile events は、設定がセッションまたは URL で指定されている場合にのみキャプチャされます。たとえば、分析中に失敗するクエリ (未知のテーブルへの参照など) で、SETTINGS clause 内でのみ send_logs_level を有効にした場合、分析フェーズのログではなく exception パケットのみが配信されます。これらをキャプチャするには、セッションまたは URL で send_logs_level を設定してください。同じ検出タイミングに関する注意点は send_logs_source_regexp にも適用されます。ログキューは各エントリがキャプチャされた時点でソースに基づいてエントリをフィルタリングするため、クエリ自身の SETTINGS clause でのみ設定された正規表現は、クエリ実行以降でのみ有効になります。パース、プラン、分析フェーズの log パケットは設定のセッションまたは URL の値でフィルタリングされます (そこで設定されていない場合はフィルタリングされません) 。そのため、クエリレベルの正規表現に一致しないソースが含まれる場合があります。反対に、より限定的なセッションまたは URL の正規表現によって除外されたエントリは、より広範なクエリレベルの正規表現によって復元されません。クエリのライフサイクル全体をフィルタリングするには、セッションまたは URL で send_logs_source_regexp を設定してください。この設定は現在 HTTP プロトコルに適用され、その他のインターフェイスでは無視されます。設定可能な値:

None - 該当するもの (data、totals、extremes、progress) をすべて出力フォーマットにそのまま渡し、該当しないもの (メトリクス、ログ) はすべて無視します。そのため、デフォルトでは従来どおり動作します。
EventStream - パケットを HTTP のサーバー送信イベント (text/event-stream) としてフレーミングします。各パケットは、対応する名前 (data、totals、extremes、progress、log、profile_events、exception) を持つイベントとして送信されます。progress およびその他の補助パケットは JSON として送信されます。サーバー送信イベントは、改行 (キャリッジリターン \r を含む) を区切り文字として扱うテキストプロトコルであるため、整形済みデータのブロックはイベントの単一の data フィールドに base64 エンコードされます。デコードすると、すべての改行を含む完全に整形されたペイロードになります。これを示すため、Content-Type には payload=base64 パラメータが含まれます。この方法では、テキスト形式・バイナリ形式を問わず、任意の出力フォーマットをバイト単位で正確に転送できます。
JSONEachPacketBase64 - 各パケットは1行ごとの JSON オブジェクトであり、整形済みデータは base64 エンコードされます。例: {"packet":"data","data":"eyJ4IjoxfQo="}。バイナリ出力フォーマットに適しています。
JSONEachPacketString - 各パケットは1行ごとの JSON オブジェクトであり、整形済みデータは文字列に格納されます。例: {"packet":"data","data":"{\"x\":1}\n"}。

JSONEachPacketString は、ペイロードのバイトを検証または再エンコードせずに JSON 文字列に格納します。String および FixedString カラムには任意のバイトを格納できるため、テキスト出力フォーマット (JSONEachRow、TSV、CSV など) は、このような値に対して無効な UTF-8 を出力する場合があります。これは、デフォルトの output_format_json_validate_utf8 = 0 を使用した場合の ClickHouse 自身の JSONEachRow と同様です。そのため、生成される NDJSON ストリームが有効な UTF-8 であることは保証されません。任意のバイトをバイト単位で正確に転送するには、JSONEachPacketBase64 を使用してください。例:

curl "http://localhost:8123/?framing_output_format=JSONEachPacketString" -d "SELECT number FROM numbers(3) FORMAT JSONEachRow"

結果：

{"packet":"data","data":"{\"number\":\"0\"}\n{\"number\":\"1\"}\n{\"number\":\"2\"}\n"}
{"packet":"profile_events","profile_events":[{"host_name":"localhost","current_time":"2026-07-11 00:00:00","thread_id":"0","type":"increment","name":"SelectedRows","value":"3"}]}
{"packet":"progress","progress":{"read_rows":"3","read_bytes":"24","total_rows_to_read":"3","result_rows":"3","result_bytes":"24","elapsed_ns":"1265958"}}

fsync_metadata

.sql ファイルの書き込み時に fsync を有効または無効にします。デフォルトでは有効です。 server に、作成と削除が絶えず行われる非常に小さな table が数百万ある場合は、これを無効にするのが適切です。

functions_h3_default_if_invalid

false の場合、h3 関数 (例: h3CellAreaM2) は入力が無効であれば例外を発生させます。true の場合は、0 またはデフォルト値を返します。

geo_distance_returns_float64_on_float64_arguments

geoDistance、greatCircleDistance、greatCircleAngle 関数の4つの引数がすべて Float64 の場合、戻り値は Float64 となり、内部計算には倍精度が使用されます。以前の ClickHouse バージョンでは、これらの関数は常に Float32 を返していました。

geotoh3_argument_order

Function ‘geoToH3’ は、‘lon_lat’ に設定すると (lon, lat) を、‘lat_lon’ に設定すると (lat, lon) を受け入れます。

glob_expansion_max_elements

許可されるアドレス数の上限 (external storage、table function など) 。

h3togeo_lon_lat_result_order

関数 ‘h3ToGeo’ は、true の場合は (lon, lat)、それ以外の場合は (lat, lon) を返します。

handshake_timeout_ms

ハンドシェイク中にレプリカから Hello パケットを受信するまでのタイムアウト (ミリ秒) 。

hedged_connection_timeout_ms

ヘッジドリクエストでレプリカとの接続を確立する際の接続タイムアウト

highlight_max_matches_per_row

highlight 関数で、1行あたりのハイライト一致数の最大値を設定します。大きなテキスト内で繰り返しの多いパターンをハイライトする際に、過剰なメモリ使用量を防ぐために使用します。設定可能な値:

正の整数。

hnsw_candidate_list_size_for_search

ベクトル類似度索引の検索時に使用される動的な候補リストのサイズです。ef_search とも呼ばれます。

hsts_max_age

HSTS の有効期限です。0 は HSTS を無効にします。

idle_connection_timeout

アイドル状態の TCP 接続を、指定した秒数経過後に切断するまでのタイムアウトです。設定可能な値:

正の整数 (0 の場合は 0 秒後、つまり即座に切断されます) 。

inject_random_order_for_select_without_order_by

有効にすると、ORDER BY clause を持たない SELECT クエリに ‘ORDER BY rand()’ を挿入します。適用されるのはサブクエリの深さが 0 の場合のみです。サブクエリおよび INSERT INTO … SELECT は対象外です。最上位の構造が UNION の場合、‘ORDER BY rand()’ はすべての child に個別に挿入されます。 ORDER BY がないとクエリ結果が非決定論的になるため、主にテストや開発でのみ有用です。

input_format

クエリの入力フォーマットをオーバーライドします。クエリで指定されたフォーマットよりも優先されます。

interactive_delay

リクエストの実行がキャンセルされたかどうかを確認し、Progressを送信する間隔をマイクロ秒単位で指定します。

intersect_default_mode

INTERSECTクエリのデフォルトモードを設定します。設定可能な値: 空文字列、‘ALL’、‘DISTINCT’。空の場合、モードを指定しないクエリでは例外がスローされます。

least_greatest_legacy_null_behavior

有効にすると、関数 ‘least’ と ‘greatest’ は、いずれかの引数が NULL の場合に NULL を返します。

legacy_column_name_of_tuple_literal

ハッシュではなく、大きなタプルリテラルの要素名をすべてカラム名として列挙します。この設定は互換性のためにのみ存在します。バージョン 21.7 未満から 21.7 以上へクラスターをローリングアップデートする際は、‘true’ に設定するのが適切です。

legacy_join_size_limits_trigger_spilling

スピルのしきい値がトリガーになる以前の max_rows_in_join および max_bytes_in_join の動作を、結合のうちディスク上で実行される部分について復元します。すなわち、いずれかに達した時点でクエリを停止するのではなく、結合がさらにスピルするようになります。この場合、join_algorithm = 'grace_hash' はこの 2 つだけを基準にスピルし、max_bytes_before_external_join は 0 を含めて完全に無視します。hash / parallel_hash は引き続きスピルのしきい値でディスクへ移行し、その後はいずれか一方に達した時点でスピルします。これらのインメモリフェーズでは、従来どおりこの 2 つを厳格な上限として扱います。これら 2 つの設定の以前の意味を前提に書かれたクエリ向けの設定で、compatibility によって自動的に有効になります。この設定が導入される前のバージョンのサーバーは旧来の意味を適用し、それを変更することはできません。そのため serialize_query_plan = 1 の場合、スピル動作が新しい意味に依存する結合は、そのようなサーバーへは一切送信されません。異なる取り決めのまま暗黙のうちに実行されるのではなく、クエリが失敗します。この設定を有効にすると、両側で旧来の意味が適用され、これらのクエリが 2 つのバージョン間で動作するようになります。

limit

クエリ結果から取得する最大行数を設定します。LIMIT句で設定された値を調整します。この値はLIMITにそのまま渡されるため、負の値 (結果の末尾から数える) や(0, 1)の小数 (結果に対する割合として解釈される) を含め、LIMITで受け付けられるすべての値を指定できます。設定可能な値:

0 — 行数は制限されません。
正の整数 — 指定した行数。
負の整数 — 末尾からN行を返します。
開区間(0, 1)内の実数 — 結果のその割合を返します。

この設定は、結果を返すSELECT / UNIONクエリに適用されます。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソースのSELECTが自身のSETTINGS clauseでこの設定を指定している場合にのみ有効です。プロファイルまたはセッションから継承された値、あるいはINSERT / CREATEステートメント自体に設定された値は、ソースのSELECTには伝播されません。これは、他のすべての設定にも適用される非伝播ルールと同じです。

load_marks_asynchronously

MergeTree の marks をバックグラウンドの thread pool (server setting load_marks_threadpool_pool_size を参照) で非同期に読み込み、すべてのストリームの marks を並列に読み込みます。無効な場合は、marks はストリームごとに順番に同期的に読み込まれるため、JSON のように多数の substreams を持つカラムではリモートディスク上で処理が遅くなります。

lock_acquire_timeout

ロックのリクエストが失敗するまでに待機する秒数を定義します。このロックタイムアウトは、table に対する読み取り/書き込み操作の実行中にデッドロックを防ぐために使用されます。タイムアウトに達してロックのリクエストが失敗すると、ClickHouse server は例外 "Locking attempt timed out! Possible deadlock avoided. Client should retry." をスローし、エラーコード DEADLOCK_AVOIDED を返します。設定可能な値:

正の整数 (秒単位) 。
0 — ロックタイムアウトなし。

low_priority_query_wait_time_ms

クエリの優先度付けの仕組みが使用されている場合 (設定 priority を参照) 、低優先度のクエリは高優先度のクエリが完了するまで待機します。この設定では、その待機時間を指定します。

make_distributed_plan

分散クエリプランを生成します。有効にすると、分散クエリプランでまだサポートされていない機能を制御する設定が自動的に調整されます。

enable_parallel_replicas = 0 および automatic_parallel_replicas_mode = 0 — 分散プランが処理を独自に分散します。
correlated_subqueries_use_in_memory_buffer = 0;
compile_expressions = 0;
query_plan_direct_read_from_text_index = 0.

merge_table_max_tables_to_look_for_schema_inference

明示的なスキーマを指定せずに Merge テーブルを作成する場合、または merge テーブル関数を使用する場合、スキーマは指定した数以下の一致するテーブルのスキーマのユニオンとして推論されます。テーブル数がそれを超える場合は、先頭から指定した数のテーブルに基づいてスキーマが推論されます。

mongodb_throw_on_unsupported_query

有効な場合、MongoDBクエリを構築できないとき、MongoDBテーブルはエラーを返します。無効な場合、ClickHouse はテーブル全体を読み込み、ローカルで処理します。

multiple_joins_try_to_keep_original_names

複数の JOIN の書き換え時に、最上位の式リストへ別名を追加しない

normalize_function_names

関数名を標準名に正規化します

offset

クエリ結果の行を返し始める前にスキップする行数を設定します。OFFSET 句で設定したオフセットを調整します。この値は OFFSET にそのまま渡され、負の値や (0, 1) の範囲の小数を含め、OFFSET で受け付けられるすべての値を指定できます。設定可能な値:

0 — 行をスキップしません。
正の整数。
負の整数。
開区間 (0, 1) の実数 — 結果のその割合をスキップします。

例入力テーブル:

CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
INSERT INTO test SELECT number FROM numbers(500);

クエリ：

SET limit = 5;
SET offset = 7;
SELECT * FROM test LIMIT 10 OFFSET 100;

結果：

┌───i─┐
│ 107 │
│ 108 │
│ 109 │
└─────┘

この設定は、結果を返す SELECT / UNION クエリに影響します。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソースの SELECT 自身の SETTINGS 句でこの設定が指定されている場合にのみ有効です。プロファイルまたはセッションから継承された値や、INSERT / CREATE ステートメント自体に設定された値は、ソースの SELECT には伝播しません。これは、他のすべての設定にも適用される非伝播ルールと同じです。

order

クエリをラップするサブクエリとして、ORDER BY 句を追加します。任意の式のリストを指定できます。これは、パース済みクエリに対してエンジンが適用するクエリ構築用の設定です (クエリを派生テーブルとしてラップします) 。既存のクエリと組み合わせて使用でき、すべてのプロトコルで機能します。HTTP URL パラメータ、クエリ内の SETTINGS 句、またはユーザープロファイルで指定できます。結果を返す SELECT / UNION クエリの形を変更します。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソースの SELECT 自身の SETTINGS 句で指定した場合にのみ有効です。プロファイルまたはセッションから継承した値、あるいは INSERT / CREATE ステートメント自体に設定した値は、ソースの SELECT には伝播しません。これは、他のすべての設定にも適用される非伝播ルールと同じです。

output_format

クエリの出力フォーマットを上書きします。クエリ、ファイル拡張子、または default_format で指定されたフォーマットよりも優先されます。

ページ

ページネーションされた結果のページ番号を設定します。offset = limit * (page - 1) と同等です。limit が設定されており、offset が設定されていない場合にのみ指定できます。ページ番号は 1 から始まります。limit および offset と同様に、負の値と小数値をサポートします。これは、解析済みクエリに対してエンジンが適用するクエリ構築用の設定です (クエリを派生テーブルとしてラップします) 。そのため、既存のクエリと組み合わせて使用でき、すべてのプロトコルで機能します。HTTP URL パラメータ、クエリ内の SETTINGS 句、またはユーザープロファイルで指定できます。結果を返す SELECT / UNION クエリの形を決定します。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソース SELECT 自体の SETTINGS 句にこの設定が指定されている場合にのみ有効です。プロファイルまたはセッションから継承された値、あるいは INSERT / CREATE ステートメント自体に設定された値は、ソース SELECT には伝播しません。これは、ほかのすべての設定にも適用される非伝播ルールと同じです。

paimon_target_snapshot_id

Paimon のインクリメンタルモードにおける、クエリレベルで特定のスナップショットを対象にした読み取りです。>0 の場合、リーダーはコミット済みのウォーターマークを進めずに、指定した snapshot_id の差分のみを取得します。デフォルト: -1 (無効)

parallelize_output_from_storages

ストレージからの読み取りステップの出力を並列化します。これにより、可能な場合はストレージからの読み取り直後にクエリ処理を並列化できます。

partial_result_on_first_cancel

キャンセル後でも、クエリが部分的な結果を返せるようにします。

per_part_index_stats

各パートの索引統計をログに記録します

poll_interval

サーバー側のクエリ待機ループを、指定した秒数だけブロックします。

polyglot_dialect

polyglotトランスパイラの変換元SQL方言 (例: ‘sqlite’, ‘mysql’, ‘postgresql’, ‘snowflake’, ‘duckdb’) 。

postgresql_fault_injection_probability

内部 (レプリケーション用) の PostgreSQL クエリが失敗するおおよその確率です。有効な値の範囲は [0.0f, 1.0f] です

predicate_statistics_sample_rate

述語の選択性統計を system.predicate_statistics_log に収集します。N > 0 に設定すると、クエリ ID に基づいて、クエリのおよそ 1/N がサンプリングされます。0 は無効を意味します。

prefetch_buffer_size

filesystem から読み込むための prefetch バッファの最大サイズです。読み取りバッファをそれ以上大きくする必要はないため、256 MiB を超える値は 256 MiB に制限されます。

print_pretty_type_names

DESCRIBE クエリおよび toTypeName() 関数で、深くネストされた型名をインデント付きで見やすく表示できるようにします。例:

CREATE TABLE test (a Tuple(b String, c Tuple(d Nullable(UInt64), e Array(UInt32), f Array(Tuple(g String, h Map(String, Array(Tuple(i String, j UInt64))))), k Date), l Nullable(String))) ENGINE=Memory;
DESCRIBE TABLE test FORMAT TSVRaw SETTINGS print_pretty_type_names=1;

a   Tuple(
    b String,
    c Tuple(
        d Nullable(UInt64),
        e Array(UInt32),
        f Array(Tuple(
            g String,
            h Map(
                String,
                Array(Tuple(
                    i String,
                    j UInt64
                ))
            )
        )),
        k Date
    ),
    l Nullable(String)
)

priority

クエリの優先度。1 が最も高く、値が大きいほど優先度は低くなります。0 は優先度を使用しません。

push_external_roles_in_interserver_queries

クエリ実行時に、ユーザーロールをクエリの発行元から他のノードへプッシュすることを有効にします。

query_metric_log_interval

個々のクエリに対する query_metric_log の収集間隔 (ミリ秒単位) です。負の値を指定すると、query_metric_log setting の collect_interval_milliseconds の値が使用され、存在しない場合はデフォルトで 1000 になります。単一のクエリの収集を無効にするには、query_metric_log_interval を 0 に設定します。デフォルト値: -1

queue_max_wait_ms

同時実行リクエスト数が最大値を超えた場合に、リクエストキュー内で待機する時間です。

rabbitmq_max_wait_ms

再試行前にRabbitMQから読み取る際の待機時間。

readonly

0 - 読み取り専用に関する制限はありません。1 - 閲覧リクエストのみ許可され、明示的に許可された設定の変更も可能です。2 - 閲覧リクエストのみ許可され、‘readonly’ 設定を除く設定の変更も可能です。

recursive_cte_max_steps_in_type_inference

recursive CTE のカラム型を推論する際の最大反復回数です。カラム型は、収束するまで、UNION ALL の非再帰側と再帰側に対して getLeastSupertype を繰り返し適用することで決定されます。0 に設定すると型の拡張が無効になり、非再帰部分の型のみが使用されます。

regexp_max_matches_per_row

1行あたり、単一の正規表現に対する最大一致数を設定します。extractAllGroupsHorizontal 関数で貪欲な正規表現を使用する際のメモリ過負荷を防ぐために使用します。設定可能な値:

正の整数。

reject_expensive_hyperscan_regexps

hyperscan での評価コストが高くなる可能性が高いパターンを拒否します (NFA の状態爆発が原因)

remerge_sort_lowered_memory_bytes_ratio

remerge 後のメモリ使用量がこの比率まで減少しない場合、remerge は無効になります。

remote_read_min_bytes_for_seek

ignore を伴う読み取りではなく seek を行うために、リモート読み取り (url、S3) で必要な最小バイト数。

rename_files_after_processing

型: String
デフォルト値: 空文字列

この設定では、file テーブル関数で処理したファイルのリネームパターンを指定できます。このオプションを設定すると、file テーブル関数で読み取られたすべてのファイルは、処理が正常に完了した場合に限り、プレースホルダーを含む指定のパターンに従ってリネームされます。リネームはソースへの書き込みであるため、このオプションを設定してファイルを読み取るクエリには、READ ON FILE に加えて WRITE ON FILE 権限が必要です。DESCRIBE はリネームを行うデータ読み取りパイプラインを構築しないため、READ ON FILE のみが必要です。

プレースホルダー

%a — 元の完全なファイル名 (例: “sample.csv”) 。
%f — 拡張子を除いた元のファイル名 (例: “sample”) 。
%e — ドット付きの元のファイル拡張子 (例: “.csv”) 。
%t — タイムスタンプ (マイクロ秒単位) 。
%% — パーセント記号 (”%”) 。

例

オプション: --rename_files_after_processing="processed_%f_%t%e"
クエリ: SELECT * FROM file('sample.csv')

sample.csv の読み取りに成功すると、ファイル名は processed_sample_1683473210851438.csv に変更されます

replication_wait_for_inactive_replica_timeout

非アクティブなレプリカが ALTER、OPTIMIZE、または TRUNCATE クエリを実行するまでの待機時間 (秒) を指定します。設定可能な値:

0 — 待機しません。
負の整数 — 無制限に待機します。
正の整数 — 待機する秒数。

reserve_memory

ワークロードスケジューリングで使用されます。単一のサーバーでクエリを実行するために予約される RAM の最小量です。予約は、workload クエリ設定の値を使用して、WORKLOAD 階層を通じて行われます。ワークロードで使用可能なメモリが不足している場合、クエリは開始されず、予約を確保できるまで保留状態で待機します。 0 は予約を行わないことを意味します。この設定は、MEMORY RESERVATION リソースが作成されている場合にのみ有効です。

restore_replicated_merge_tree_to_shared_merge_tree

RESTORE 時に、テーブルエンジンを ReplicatedMergeTree から SharedMergeTree に置き換えます。 Cloud でのデフォルト値: 1。

result_overflow_mode

結果量がいずれかの制限を超えた場合の動作を設定します。設定可能な値:

throw: 例外をスローします (デフォルト) 。
break: クエリの実行を停止し、ソースデータが尽きたかのように部分的な結果を返します。

‘break’ を使う動作は LIMIT の使用に似ています。break は block レベルでのみ実行を中断します。つまり、返される行数は max_result_rows を上回り、max_block_size の倍数になり、max_threads に依存します。例

Query

SET max_threads = 3, max_block_size = 3333;
SET max_result_rows = 3334, result_overflow_mode = 'break';

SELECT *
FROM numbers_mt(100000)
FORMAT Null;

Result

6666 rows in set. ...

resumable_backup_from_snapshot

再開可能な BACKUP FROM SNAPSHOT を有効にします。失敗した場合でも、すでに完了したバッチのエントリを再コピーせずに再実行できます。ディレクトリ形式の S3 および AzureBlobStorage 宛先では、ClickHouse Cloud でのみ利用できます。 BACKUP FROM SNAPSHOT 自体を利用できない ClickHouse オープンソースビルドでこれを有効にすると、BACKUP は WRONG_BACKUP_SETTINGS で失敗します。

rows_before_aggregation

有効にすると、ClickHouse は rows_before_aggregation 統計値の正確な値を返します。これは、集約前に読み取られた行数を表します

run_query_in_background

有効にすると、サーバーはクエリをバックグラウンドでスケジュールし、ただちに空の成功結果を返します。接続の状態にかかわらず、クエリは完了まで実行されます。バックグラウンドクエリはサーバーの再起動後には存続しません。シャットダウン時にはフォアグラウンドクエリと同じサーバー設定が適用されます。shutdown_wait_unfinished_queries は、クエリをキャンセルするか完了を待つかを選択します (キュー内のエントリは、いずれの場合も system.query_log にエントリを記録せず破棄されます) 。shutdown_wait_unfinished はサーバーの待機時間を制限します。クエリは query_id で追跡できます。実行中は system.processes、完了してクエリログのエントリがフラッシュされた後は system.query_log で確認できます。ネイティブ TCP および HTTP プロトコル経由で受信したクエリに適用されます。HTTP では、設定を URL パラメータとして渡します。SET では変更できません。クエリごと、またはユーザーやプロファイルのレベルで有効にしてください。主なユースケースは、クライアント接続が切断されても失われてはならない、長時間実行される INSERT ... SELECT です。

secondary_indices_enable_bulk_filtering

インデックスでの一括フィルタリングアルゴリズムを有効にします。通常はこちらのほうが常に優れていると想定されていますが、互換性の確保と制御のためにこの設定を用意しています。

select

明示的な SELECT 式リストを用いて、クエリをサブクエリとしてラップします。空でない場合、結果を返すクエリは SELECT <expr_list> FROM (<query>) でラップされます。これは、パース済みクエリに対してエンジンが適用するクエリ構築設定です (派生テーブルとしてラップします) 。既存のクエリと組み合わせて使用でき、すべてのプロトコルで機能します。HTTP URL パラメータ、クエリ内の SETTINGS 句、またはユーザープロファイルで指定できます。結果を返す SELECT / UNION クエリの形状を決定します。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソース SELECT 自身の SETTINGS 句で指定されている場合にのみ有効です。プロファイルまたはセッションから継承された値や、INSERT / CREATE ステートメント自体に設定された値は、ソース SELECT には伝播されません。これは、他のすべての設定にも適用される非伝播ルールと同じです。

select_sequential_consistency

この設定は、SharedMergeTree と ReplicatedMergeTree で動作が異なります。SharedMergeTree における select_sequential_consistency の動作の詳細については、SharedMergeTree consistency を参照してください。

SELECT クエリで逐次整合性を有効または無効にします。insert_quorum_parallel を無効にする必要があります (デフォルトでは有効) 。設定可能な値:

0 — 無効。
1 — 有効。

使用方法逐次整合性が有効な場合、ClickHouse は、insert_quorum を指定してそれまでに実行されたすべての INSERT クエリのデータを含むレプリカに対してのみ、クライアントが SELECT クエリを実行できるようにします。クライアントが不完全なレプリカを参照した場合、ClickHouse は例外を生成します。SELECT クエリには、まだレプリカのクォーラムに書き込まれていないデータは含まれません。 insert_quorum_parallel が有効な場合 (デフォルト) 、select_sequential_consistency は機能しません。これは、並列の INSERT クエリが異なるクォーラムレプリカのセットに書き込まれる可能性があるため、単一のレプリカがすべての書き込みを受け取っている保証がないためです。関連項目:

session_query_ids_history_size

system.session_query_ids システムテーブルを通じて公開される、セッションローカルな履歴に保持されるクエリIDの最大数です。セッション内で実行された内部クエリ以外のすべてのクエリのクエリIDが、クエリ開始時にそこへ記録されます。履歴がこのサイズを超えると、最も古いエントリから順に追い出されます。この値はクエリ開始時、クエリがパースされる前に読み取られます。そのため、クエリ自身の SETTINGS 句では、そのクエリを記録するかどうかを制御できません。代わりに SET、HTTP URLパラメータ、または設定プロファイルを使用してください。設定可能な値:

正の整数。
0 — 記録は無効です。それ以前に記録されたエントリはテーブルに残ります。

session_timezone

現在のセッションまたはクエリの暗黙的なタイムゾーンを設定します。暗黙的なタイムゾーンとは、明示的にタイムゾーンが指定されていない DateTime/DateTime64 型の値に適用されるタイムゾーンのことです。この設定は、グローバルに設定された (サーバーレベルの) 暗黙的なタイムゾーンよりも優先されます。値 '' (空文字列) は、現在のセッションまたはクエリの暗黙的なタイムゾーンが server time zone と同じであることを意味します。関数 timeZone() と serverTimeZone() を使用すると、セッションのタイムゾーンとサーバーのタイムゾーンを取得できます。設定可能な値:

system.time_zones に含まれる任意のタイムゾーン名 (例: Europe/Berlin、UTC、Zulu)

例:

SELECT timeZone(), serverTimeZone() FORMAT CSV

"Europe/Berlin","Europe/Berlin"

SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV

"Asia/Novosibirsk","Europe/Berlin"

明示的にタイムゾーンが指定されていない内側のDateTimeに、セッションのタイムゾーン ‘America/Denver’ を割り当てます:

SELECT toDateTime64(toDateTime64('1999-12-12 23:23:23.123', 3), 3, 'Europe/Zurich') SETTINGS session_timezone = 'America/Denver' FORMAT TSV

1999-12-13 07:23:23.123

DateTime/DateTime64 を解析する関数のすべてが session_timezone に従うわけではありません。これにより、気づきにくいエラーが生じる可能性があります。次の例と説明を参照してください。

CREATE TABLE test_tz (`d` DateTime('UTC')) ENGINE = Memory AS SELECT toDateTime('2000-01-01 00:00:00', 'UTC');

SELECT *, timeZone() FROM test_tz WHERE d = toDateTime('2000-01-01 00:00:00') SETTINGS session_timezone = 'Asia/Novosibirsk'
0 rows in set.

SELECT *, timeZone() FROM test_tz WHERE d = '2000-01-01 00:00:00' SETTINGS session_timezone = 'Asia/Novosibirsk'
┌───────────────────d─┬─timeZone()───────┐
│ 2000-01-01 00:00:00 │ Asia/Novosibirsk │
└─────────────────────┴──────────────────┘

これは、パース処理のパイプラインが異なるために発生します。

最初の SELECT クエリで、タイムゾーンを明示的に指定せずに使用された toDateTime() は、設定 session_timezone とグローバルタイムゾーンに従います。
2 つ目のクエリでは、DateTime は String からパースされ、既存のカラムdの型とタイムゾーンを継承します。そのため、設定 session_timezone とグローバルタイムゾーンには従いません。

関連項目

timezone

set_overflow_mode

データ量がいずれかの制限値を超えた場合の動作を設定します。設定可能な値:

throw: 例外を発生させます (デフォルト) 。
break: クエリの実行を停止し、入力データが尽きたかのように部分的な結果を返します。

single_join_prefer_left_table

単一の JOIN で識別子が曖昧な場合は、左テーブルを優先します

skip_redundant_aliases_in_udf

ユーザー定義関数を簡単に利用できるように、冗長な別名は UDF 内では使用されず、置換されます。設定可能な値:

1 — UDF では別名がスキップされます (置換されます) 。
0 — UDF では別名はスキップされません (置換されます) 。

例有効時と無効時の違い: クエリ:

SET skip_redundant_aliases_in_udf = 0;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

結果:

SELECT ((4 + 2) + 1 AS y, y + 2)

クエリ:

SET skip_redundant_aliases_in_udf = 1;
CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));

EXPLAIN SYNTAX SELECT test_03274(4 + 2);

結果:

SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)

sleep_after_receiving_query_ms

TCPHandler でクエリを受信した後のスリープ時間

snappy_mode

file や url などの汎用 file I/O パスで、snappy 圧縮に使用するワイヤ形式を制御します。HTTP Content-Encoding: snappy は常に framing フォーマットを使用し、この設定は無視されます。単一の snappy::Compress 呼び出しで生成される生の snappy ブロックフォーマット (たとえば SnappyBasicReadBuffer が処理する Prometheus リモートプロトコルのペイロード) は、これとは別のプロトコル固有のワイヤ形式であり、この設定の制御対象ではない点に注意してください。設定可能な値:

basic — Hadoop snappy ブロックフォーマット。Hadoop が読み書きするファイルと互換性があります。読み取りと書き込みの両方をサポートします。
framed — Snappy framing フォーマット。Google が定義した標準的なストリーミングフォーマットです。読み取りと書き込みの両方をサポートします。

ソート

クエリを派生テーブルとしてラップするサブクエリに、単純な ORDER BY 句を追加します。任意の + (ASC) または - (DESC) プレフィックスを付けた、識別子または位置カラム参照 (正の整数) のカンマ区切りリストを指定できます。例: sort=a,-b は a を昇順、b を降順でソートします。sort=1,-2 は 1 番目のカラムを昇順、2 番目のカラムを降順でソートします。order とは併用できません。これは、エンジンがパース済みクエリに適用するクエリ構築設定です (派生テーブルとしてラップされます) 。既存のクエリと組み合わせて使用でき、すべてのプロトコルで機能します。HTTP URL パラメータ、クエリ内の SETTINGS 句、またはユーザープロファイルで指定できます。結果を返す SELECT / UNION クエリに適用されます。書き込みクエリ (INSERT … SELECT、CREATE … AS SELECT) では、ソース SELECT 自身の SETTINGS 句で指定された場合にのみ有効です。プロファイルまたはセッションから継承された値や、INSERT / CREATE ステートメント自体に設定された値は、ソース SELECT には伝播しません。これは、他のすべての設定にも適用される非伝播ルールと同じです。

sort_overflow_mode

ソート前に受信した行数がいずれかの制限を超えた場合の動作を設定します。設定可能な値:

throw: 例外をスローします。
break: クエリの実行を停止し、部分的な結果を返します。

splitby_max_substrings_includes_remaining_string

引数 max_substrings > 0 が指定された関数 splitBy*() で、結果配列の最後の要素に残りの文字列を含めるかどうかを制御します。設定可能な値:

0 - 残りの文字列は、結果配列の最後の要素に含まれません。
1 - 残りの文字列は、結果配列の最後の要素に含まれます。これは、Spark の split() 関数および Python の string.split() メソッドと同じ動作です。

statistics_max_set_size_for_exact_selectivity_estimation

選択性推定器が集合でカバーされる正確な範囲を導出する対象となる、IN 演算子の右辺の集合の最大サイズ。これらの範囲の導出には、要素ごとに Field 1 つ、ソート、および統計プローブ 1 回が必要となるため、大きな集合ではクエリプランニングの大半を占めます。この制限を超えると、推定器は代わりに集合のサイズとその境界範囲から選択性を導出します。これはソートや要素ごとの統計プローブを必要とせず、集合を 1 回線形走査するだけで済みます。0 は制限なしを意味します。

stop_refreshable_materialized_views_on_startup

サーバーの起動時に、SYSTEM STOP VIEWS を実行した場合と同様に、リフレッシャブルmaterialized view がスケジュールされないようにします。その後、SYSTEM START VIEWS または SYSTEM START VIEW <name> を使用して手動で開始できます。新しく作成されたビューにも適用されます。リフレッシャブルでない materialized view には影響しません。

tcp_keep_alive_timeout

TCP が keepalive プローブの送信を開始するまでに、接続がアイドル状態のままである時間 (秒)

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

ファイルシステムキャッシュ内の一時データで領域を予約する際に、cache を lock するまでの待機時間

throw_if_no_data_to_insert

空の INSERT を許可または禁止します。デフォルトで有効になっており、空の INSERT ではエラーが発生します。clickhouse-client を使用する INSERT、または gRPC インターフェイスを使用する INSERT にのみ適用されます。

time_series_prefer_recent_samples_table

要求された時間範囲全体が最近の Samples テーブルの有効期限 (TTL) ウィンドウ内に収まる場合、メインの Samples テーブルではなく、TimeSeries テーブルの最近の Samples テーブルから読み取ります (TimeSeries テーブルエンジンの recent_samples_ttl_seconds 設定を参照) 。

timeout_before_checking_execution_speed

指定した秒数の経過後、実行速度が遅すぎないこと (min_execution_speed を下回らないこと) を確認します。

transfer_overflow_mode

データ量がいずれかの制限値を超えたときの動作を設定します。設定可能な値:

throw: 例外をスローします (デフォルト) 。
break: クエリの実行を停止し、ソースデータが尽きた場合と同様に、部分的な結果を返します。

transform_null_in

IN 演算子において、NULL 値同士を等価として扱うようにします。デフォルトでは、NULL は未定義の値を意味するため、NULL 値同士は比較できません。したがって、比較 expr = NULL は常に false を返します。この設定を有効にすると、IN 演算子では NULL = NULL が true を返します。設定可能な値:

0 — IN 演算子での NULL 値の比較は false を返します。
1 — IN 演算子での NULL 値の比較は true を返します。

例 null_in テーブルを考えます。

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
│    3 │     3 │
└──────┴───────┘

クエリ:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;

結果:

┌──idx─┬────i─┐
│    1 │    1 │
└──────┴──────┘

クエリ:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;

結果:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
└──────┴───────┘

関連項目

IN 演算子での NULL 処理

traverse_shadow_remote_data_paths

system.remote_data_paths をクエリする際、実際のテーブルデータに加えて凍結データ (shadow ディレクトリ) も走査します

union_default_mode

SELECT クエリ結果を結合するモードを設定します。この設定は、UNION ALL または UNION DISTINCT を明示的に指定せずに UNION を使用した場合にのみ適用されます。設定可能な値:

'DISTINCT' — ClickHouse は、重複する行を除去したうえで、クエリを結合した結果の行を出力します。
'ALL' — ClickHouse は、重複する行を含めて、クエリを結合した結果のすべての行を出力します。
'' — UNION とともに使用すると、ClickHouse は例外を生成します。

例は UNION を参照してください。

unknown_packet_in_send_data

N 番目のデータパケットでは、データの代わりに不明なパケットを送信します

variant_throw_on_type_mismatch

デフォルト実装で Variant カラムに関数を適用する際、実際の型がその関数に対応していない行をどのように扱うかを制御します。

true (デフォルト) — 例外をスローします。
false — 代わりにそれらの行には NULL を返します。

wait_changes_become_visible_after_commit_mode

コミット済みの変更が最新のスナップショットで実際に見えるようになるまで待機します

workload

リソースへのアクセスに使用するワークロード名

workload_admission_timeout_ms

クエリがワークロード scheduling によって受け入れられるまで待機する最大時間で、これを超えるとクエリは開始されずに失敗します。この設定は、query slot (CREATE RESOURCE ... (QUERY) リソースから取得され、ワークロードの max_concurrent_queries によって制限されます) と memory reservation (CREATE RESOURCE ... (MEMORY RESERVATION) リソースおよび reserve_memory 設定によるもの) の待機時間の合計を制限します。いずれもクエリの実行開始前に取得されるため、この実行前の待機時間を制限できるのはこの設定だけです。クエリがまだ開始されていないため、max_execution_time はこの段階では適用されません。 timeout に達すると、待機していたリソースに応じて、クエリは 2 種類の error のいずれかで失敗します。query slot の場合は QUERY_SLOT_ACQUISITION_TIMEOUT、memory reservation の場合は MEMORY_RESERVATION_ACQUISITION_TIMEOUT です。設定可能な値:

正の整数 — timeout (ミリ秒単位) 。
0 — infinite timeout: クエリは受け入れられるまで無期限に待機します (デフォルト) 。ただし、ワークロードの max_waiting_queries の上限に達している場合は、即座に拒否されることがあります。

write_full_path_in_iceberg_metadata

Icebergメタデータファイルに完全なパス (s3:// を含む) を書き込みます。

zstd_window_log_max

ZSTD の最大ウィンドウログを設定します (MergeTree family では使用されません) 。

最終更新日 2026年9月26日

​adaptive_aggregator_freeze_threshold

​adaptive_aggregator_freeze_threshold_bytes

​add_http_cors_header

​analyze_index_with_space_filling_curves

​analyzer_inline_views

​any_join_distinct_right_table_keys

​archive_adaptive_buffer_max_size_bytes

​arrow_flight_request_descriptor_type

​backup_slow_all_threads_after_retryable_s3_error

​cache_warmer_threads

​calculate_text_stack_trace

​cancel_http_readonly_queries_on_client_close

​cascades_aggregation_pushdown

​checksum_on_read

​圧縮

​connection_pool_max_wait_ms

​connections_with_failover_max_tries

​convert_query_to_cnf

​count_matches_stop_at_empty_match

​cross_to_inner_join_rewrite

​data_type_default_nullable

​decimal_check_overflow

​deduplicate_blocks_in_dependent_materialized_views

​defer_partition_pruning_after_final

​describe_compact_output

​dialect

​discard_query_data

​distinct_overflow_mode

​do_not_merge_across_partitions_select_final

​dynamic_throw_on_type_mismatch

​enforce_strict_identifier_format

​engine_url_skip_empty_files

​exact_rows_before_limit

​except_default_mode

​exclude_materialize_skip_indexes_on_insert

​execute_exists_as_scalar_subquery

​explain_query_plan_default

​explain_syntax_single_record

​extract_key_value_pairs_max_pairs_per_row

​extremes

​fallback_to_stale_replicas_for_distributed_queries

​file_like_engine_default_partition_strategy

​filesystem_prefetches_limit

​filter

​final

​finalize_projection_parts_synchronously

​flatten_nested

​format

​framing_output_format

​fsync_metadata

​functions_h3_default_if_invalid

​geo_distance_returns_float64_on_float64_arguments

​geotoh3_argument_order

​glob_expansion_max_elements

​h3togeo_lon_lat_result_order

​handshake_timeout_ms

​hedged_connection_timeout_ms

​highlight_max_matches_per_row

​hnsw_candidate_list_size_for_search

​hsts_max_age

​idle_connection_timeout

​inject_random_order_for_select_without_order_by

​input_format

​interactive_delay

​intersect_default_mode

​least_greatest_legacy_null_behavior

​legacy_column_name_of_tuple_literal

​legacy_join_size_limits_trigger_spilling

​limit

​load_marks_asynchronously

​lock_acquire_timeout

​low_priority_query_wait_time_ms

​make_distributed_plan

​merge_table_max_tables_to_look_for_schema_inference

​mongodb_throw_on_unsupported_query

​multiple_joins_try_to_keep_original_names

​normalize_function_names

​offset

​order

​output_format

adaptive_aggregator_freeze_threshold

adaptive_aggregator_freeze_threshold_bytes

add_http_cors_header

analyze_index_with_space_filling_curves

analyzer_inline_views

any_join_distinct_right_table_keys

archive_adaptive_buffer_max_size_bytes

arrow_flight_request_descriptor_type

backup_slow_all_threads_after_retryable_s3_error

cache_warmer_threads

calculate_text_stack_trace

cancel_http_readonly_queries_on_client_close

cascades_aggregation_pushdown

checksum_on_read

圧縮

connection_pool_max_wait_ms

connections_with_failover_max_tries

convert_query_to_cnf

count_matches_stop_at_empty_match

cross_to_inner_join_rewrite

data_type_default_nullable

decimal_check_overflow

deduplicate_blocks_in_dependent_materialized_views

defer_partition_pruning_after_final

describe_compact_output

dialect

discard_query_data

distinct_overflow_mode

do_not_merge_across_partitions_select_final

dynamic_throw_on_type_mismatch

enforce_strict_identifier_format

engine_url_skip_empty_files

exact_rows_before_limit

except_default_mode

exclude_materialize_skip_indexes_on_insert

execute_exists_as_scalar_subquery

explain_query_plan_default

explain_syntax_single_record

extract_key_value_pairs_max_pairs_per_row

extremes

fallback_to_stale_replicas_for_distributed_queries

file_like_engine_default_partition_strategy

filesystem_prefetches_limit

filter

final

finalize_projection_parts_synchronously

flatten_nested

format

framing_output_format

fsync_metadata

functions_h3_default_if_invalid

geo_distance_returns_float64_on_float64_arguments

geotoh3_argument_order

glob_expansion_max_elements

h3togeo_lon_lat_result_order

handshake_timeout_ms

hedged_connection_timeout_ms

highlight_max_matches_per_row

hnsw_candidate_list_size_for_search

hsts_max_age

idle_connection_timeout

inject_random_order_for_select_without_order_by

input_format

interactive_delay

intersect_default_mode

least_greatest_legacy_null_behavior

legacy_column_name_of_tuple_literal

legacy_join_size_limits_trigger_spilling

limit

load_marks_asynchronously

lock_acquire_timeout

low_priority_query_wait_time_ms

make_distributed_plan

merge_table_max_tables_to_look_for_schema_inference

mongodb_throw_on_unsupported_query

multiple_joins_try_to_keep_original_names

normalize_function_names

offset

order

output_format