Skip to main content
これらの設定は system.merge_tree_settings で確認でき、ClickHouse のソースコードから自動生成されています。

adaptive_write_buffer_initial_size

アダプティブ書き込みバッファの初期サイズ

add_implicit_sign_column_constraint_for_collapsing_engine

true に設定すると、CollapsingMergeTree または VersionedCollapsingMergeTree テーブルの sign カラムに暗黙的な制約が追加され、 有効な値 (1-1) のみを許可します。

alter_column_secondary_index_mode

セカンダリ索引の対象になっているカラムを変更する ALTER コマンドを許可するかどうか、および 許可する場合にどのような処理を行うかを設定します。デフォルトでは、このような ALTER コマンドは許可され、索引は再構築されます。 設定可能な値:
  • rebuild (default): ALTER コマンド内のカラムの影響を受けるセカンダリ索引を再構築します。
  • throw: 例外を送出し、明示的 なセカンダリ索引の対象になっているカラムに対する ALTER をすべて禁止します。暗黙的な索引はこの制限の対象外であり、再構築されます。
  • drop: 依存するセカンダリ索引を削除します。新しいパーツにはその索引が含まれなくなるため、再作成するには MATERIALIZE INDEX が必要です。
  • compatibility: 元の動作に合わせます。ALTER ... MODIFY COLUMN では throwALTER ... UPDATE/DELETE では rebuild になります。
  • ignore: 熟練者向けです。索引を不整合な状態のままにするため、誤ったクエリ結果を招く可能性があります。

apply_patches_on_merge

true の場合、マージ時にパッチパーツが適用されます

assign_part_uuids

有効にすると、新しく作成される各パーツに一意の識別子が割り当てられます。 有効にする前に、すべてのレプリカが UUID バージョン 4 をサポートしていることを確認してください。

auto_statistics_types

適切なすべてのカラムに対して自動的に計算する統計タイプのカンマ区切りリストです。 サポートされている統計タイプ: basic, tdigest, countmin, uniq, uniq_v2。 minmax 統計タイプは非推奨です。これは basic の部分集合であるため、代わりに basic を使用してください。

background_task_preferred_step_execution_time_ms

マージ または mutation の 1 ステップの実行に要する目標時間です。1 ステップの処理に これより長い時間がかかる場合は、この時間を超えることがあります

clean_deleted_rows

廃止された設定で、効果はありません。

clone_replica_zookeeper_create_get_part_batch_size

レプリカのクローン時に ZooKeeper の multi-create get-part リクエストで使用するバッチサイズ。

compatibility_allow_sampling_expression_not_in_primary_key

主キーに含まれない sampling expression を持つテーブルの作成を許可します。これは、 後方互換性のために、不正なテーブルを含む状態でサーバーを一時的に実行できるようにする場合にのみ 必要です。

compute_exact_num_defaults_for_sparse_columns

insert および マージ 時に、スパース シリアライゼーションを判断するための、より低コストな sampling による推定ではなく、 各カラムのデフォルト値数を正確に計算します。 これは、永続化された num_defaults カウンターを利用する optimize_trivial_count_with_sparsity_filter で必要になります (Nullable カラムでは、 さらに nullable_serialization_version = 'allow_sparse' が必要です) 。 無効のままにしておけば inserts/merges の速度は従来どおり維持されますが、有効にすると スパース化の対象となり得る各カラムごとに O(rows) の追加パスが発生します。

deduplicate_merge_projection_mode

(Replicated, Shared) MergeTree ではない、従来型以外の MergeTree を使用するテーブルで、プロジェクションの作成を許可するかどうかを指定します。 ignore オプションは互換性のためだけのものであり、誤った結果を招く可能性があります。それ以外の値では、許可する場合に プロジェクションのマージ時にどう処理するかを指定します。動作は drop または rebuild のいずれかです。したがって、従来型の MergeTree ではこの設定は無視されます。これは OPTIMIZE DEDUPLICATE も制御しますが、効果は MergeTree family のすべてのメンバーに及びます。lightweight_mutation_projection_mode オプションと同様に、これも part level です。 設定可能な値:
  • ignore
  • throw
  • drop
  • rebuild

deduplication_hashes_cache_update_wait_ms

すでに挿入済みのブロックを再確認する前に、各 insert の反復処理が、メモリ内の deduplication_hashes cache が より新しいバージョンに更新されるのを待つ時間です。この cache は ClickHouse Keeper 内の deduplication_hashes ディレクトリを反映しているため、insert は Keeper との往復変換なしで重複を検出できます。

default_compression_codec

テーブル宣言で特定のカラムに圧縮コーデックが定義されていない場合に使用される、デフォルトの圧縮コーデックを指定します。 カラムの圧縮コーデックの選択順序:
  1. テーブル宣言でそのカラムに定義された圧縮コーデック
  2. default_compression_codec で定義された圧縮コーデック (この設定)
  3. compression 設定で定義されたデフォルトの圧縮コーデック デフォルト値: 空文字列 (未定義) 。

ディスク

ストレージに使用するディスクの名前です。storage policy の代わりに指定できます。

dynamic_serialization_version

Dynamic データ型のシリアル化バージョンです。互換性のために必要です。 設定可能な値:
  • v1
  • v2
  • v3

enforce_index_structure_match_on_partition_manipulation

この設定をパーティション操作 クエリ (ATTACH/MOVE/REPLACE PARTITION) の宛先テーブルに対して有効にすると、 ソーステーブルと宛先テーブルの索引およびプロジェクションは 同一である必要があります。無効な場合は、宛先テーブルが ソーステーブルの索引およびプロジェクションの上位集合を持つことができます。

execute_merges_on_single_replica_time_threshold

この設定の値が 0 より大きい場合、ただ 1 つのレプリカのみが直ちにマージを開始し、他のレプリカはローカルでマージを実行する代わりに、その時間内は結果をダウンロードして待機します。選択されたレプリカがその時間内にマージを完了しなかった場合は、標準の動作にフォールバックします。 設定可能な値:
  • 任意の正の整数。

finished_mutations_to_keep

完了したミューテーションに関するレコードを保持する件数です。ゼロの場合は、 そのすべてを保持します。

force_read_through_cache_for_merges

マージ時の読み取りでファイルシステムキャッシュを強制的に経由させます

initialization_retry_period

テーブル初期化の再試行間隔 (秒) 。

kill_threads

廃止された設定で、何の効果もありません。

lightweight_mutation_projection_mode

デフォルトでは、論理削除 DELETE は プロジェクション を持つテーブルでは機能しません。これは、projection 内の行が DELETE 操作の影響を受ける可能性があるためです。そのため、デフォルト値は throw です。ただし、このオプションで動作を変更できます。値を drop または rebuild のいずれかにすると、プロジェクション に対しても deletes が機能するようになります。drop は projection を削除するため、 現在のクエリでは projection が削除されることで高速になる可能性がありますが、 以降のクエリでは projection がアタッチされなくなるため低速になる可能性があります。rebuild は projection を再構築するため、現在のクエリのパフォーマンスに影響する可能性がありますが、 以降のクエリは高速化される可能性があります。さらに、これらのオプションは パーツ level でのみ機能するため、変更対象にならない パーツ 内の プロジェクション は、 drop や rebuild のようなアクションをトリガーすることなく、そのまま維持されます。 設定可能な値:
  • throw
  • drop
  • rebuild

load_existing_rows_count_for_old_parts

exclude_deleted_rows_for_part_size_in_merge とあわせて有効にすると、 既存のデータパーツの削除済み行数が、テーブルの起動時に 計算されます。なお、これにより起動時のテーブル読み込みが遅くなる可能性があります。 設定可能な値:
  • true
  • false
関連項目

lock_acquire_timeout_for_background_operations

マージやミューテーションなどのバックグラウンド処理で、テーブルロックを取得できない場合に失敗と見なすまでの秒数。

mutation_workload

ミューテーションと他のワークロードの間で、リソースの利用と共有をどのように制御するかを調整するために使用されます。指定した値は、このテーブルのバックグラウンドミューテーションに対する workload 設定の値として使用されます。指定しない場合 (空文字列) は、代わりにサーバー設定 mutation_workload が使用されます。 関連項目

non_replicated_deduplication_window

非レプリケートの MergeTree テーブルで、重複確認のためにハッシュ値を保持する直近の挿入ブロック数です。 設定可能な値:
  • 任意の正の整数。
  • 0 (重複排除を無効化) 。
レプリケートテーブルと同様の重複排除の仕組みが使用されます ( replicated_deduplication_window 設定を参照) 。重複排除用の ハッシュ値は、挿入されたブロック全体を対象に計算されます。ハッシュ値は ClickHouse Keeper ではなく、ディスク上のローカルファイルに書き込まれます。

notify_newest_block_number

最新の ブロック 番号を SharedJoin または SharedSet に通知します。ClickHouse Cloud でのみ使用できます。

nullable_serialization_version

Nullable(T) カラムで使用するシリアライゼーション方式を制御します。 設定可能な値:
  • basic — Nullable(T) に標準のシリアライゼーションを使用します。
  • allow_sparse — Nullable(T) でスパースエンコーディングの使用を許可します。

object_serialization_version

JSON データ型のシリアライゼーションバージョンです。互換性のために必要です。 設定可能な値:
  • v1
  • v2
  • v3
共有データのシリアライゼーションバージョンを変更できるのは、バージョン v3 のみです。

old_parts_lifetime

突発的なサーバー再起動時のデータ損失を防ぐために、 非アクティブなパーツを保持しておく時間 (秒) 。 設定可能な値:
  • 任意の正の整数。
複数のパーツを新しいパーツにマージすると、ClickHouse は元の パーツを非アクティブとしてマークし、old_parts_lifetime 秒が経過した後にのみ削除します。 非アクティブなパーツは、現在のクエリで使用されていない場合、つまり そのパーツの refcount が 1 の場合に削除されます。 新しいパーツに対しては fsync が呼び出されないため、しばらくの間、新しいパーツは server の RAM (OS キャッシュ) 上にしか存在しません。server が突発的に再起動すると、 新しいパーツが失われたり破損したりする可能性があります。データ保護のため、 非アクティブなパーツはすぐには削除されません。 起動時に ClickHouse はパーツの整合性を確認します。マージ済みの パーツが破損している場合、ClickHouse は非アクティブなパーツをアクティブな一覧に戻し、 その後それらを再度マージします。次に、破損したパーツはリネームされ (broken_ プレフィックスが追加され) 、detached フォルダーに移動されます。マージ済みのパーツが 破損していない場合は、元の非アクティブなパーツがリネームされ (ignored_ プレフィックスが追加され) 、detached フォルダーに移動されます。 デフォルトの dirty_expire_centisecs 値 (Linux カーネルの設定) は 30 秒 (書き込まれたデータが RAM にのみ保持される最大時間) ですが、 ディスクシステムに高い負荷がかかっている場合、実際の書き込みはそれよりかなり遅くなることがあります。実験的に、 old_parts_lifetime には 480 秒という値が選ばれており、この間に 新しいパーツが確実にディスクへ書き込まれることが保証されます。

optimize_row_order

新たに挿入されるテーブルパートの圧縮効率を高めるために、挿入時に行順序を最適化するかどうかを制御します。 通常の MergeTree-engine テーブルに対してのみ効果があります。特殊な MergeTree engine テーブル (例: CollapsingMergeTree) には効果がありません。 MergeTree テーブルは、 (必要に応じて) compression codecs を使用して圧縮されます。 LZ4 や ZSTD のような汎用的な圧縮コーデックは、データにパターンがある場合に最大の圧縮率を発揮します。 同じ値が長く連続するデータは、一般に非常によく圧縮されます。 この設定を有効にすると、ClickHouse は、新たに 挿入されるパート内のデータを、新しいテーブルパートの各カラムにおいて同じ値の連続数が最小になるような行順序で格納しようとします。 言い換えると、同じ値の連続数が少ないほど、個々の連続区間は 長くなり、圧縮効率が高くなります。 最適な行順序を見つけることは、計算量の観点から現実的ではありません (NP 困難) 。 そのため、ClickHouse は、元の行順序よりも圧縮率を改善できる行順序を すばやく見つけるためにヒューリスティックを使用します。 有効にすると、新しいデータの行順序を分析して 最適化するために、挿入操作で追加の CPU コストが発生します。INSERT は、データの特性に応じて 30~50% 長くかかることが見込まれます。 LZ4 または ZSTD の圧縮率は、平均で 20~40% 改善します。 この設定は、主キーがないテーブル、または低カーディナリティの 主キーを持つテーブル、すなわち異なる主キー値が少数しかないテーブルで最も効果を発揮します。 高カーディナリティの主キー、たとえば型 DateTime64 の timestamp カラムを含む主キーでは、この設定の恩恵は 期待できません。

packed_skip_index_max_bytes

skip-index サブストリームを個別の skp_idx_<name>.idx2 / .mrk2 ファイルとして書き込む代わりに、パーツごとに単一の skp_idx.packed アーカイブへまとめるしきい値です (シリアライズ後のディスク上バイト数、つまりサブストリームの圧縮と hashing chain の後のサイズ) 。この値より大きいサブストリームは、従来のファイル単位レイアウトのままです。判定は 書き込み時にサブストリームごとに独立して行われるため、1 つのパーツ内で小さい索引 (例: minmax) はパックされ、大きいもの (例: 重い bloom_filter) はファイル単位のままになる場合があります。パッキングを完全に無効化するには 0 を設定します (既定値) 。 各 skip-index サブストリームは実際には data file と marks file で構成されており、spill の判定が行われるまで両方が しきい値までメモリ内に buffer されます。そのため、書き込み中の Peak memory は 2 * packed_skip_index_max_bytes * (number of substreams that stay below the threshold) に比例します。 全文索引はこの設定ではサポートされず、パックされることはありません。 パッキングにより、table に多数の skip 索引が定義されている場合の inode 負荷を軽減できます (たとえば add_minmax_index_for_numeric_columns を使用する場合) 。 ディスク上フォーマットは自己記述的です。reader は skp_idx.packed を検出し、その内部のパック済み サブストリームを透過的に提供します。この設定の変更は新しく書き込まれるパーツにのみ影響し、 既存のパーツは書き込み時のレイアウトを保持します。

part_minmax_index_columns

パートごとの min-max 索引が対象とするカラムを選択します。各値を選ぶと、1つ前の値で有効になるカラム群に加えて、さらに別のカラム群が有効になります。 設定可能な値:
  • partition_key_only — パーティションキーのカラムのみを追跡します。
  • with_block_number_offset — パーティションキーのカラムに加えて、永続化された仮想カラム _block_number_block_offset も追跡します。これにより、これらのカラムによるパートレベルの pruning が有効になります。

propagate_types_serialization_versions_to_nested_types

true の場合、string_serialization_version のようなシリアライゼーションバージョンは、Array/Map/Nullable/JSON/etc. のようなネスト型の内部にも伝播されます。無効にすると、シリアライゼーションバージョンはこの型のトップレベルのカラムと Tuple el にのみ適用されます

ratio_of_defaults_for_sparse_serialization

カラム内の デフォルト 値の数を 値の数で割った比率の最小値です。 この値を設定すると、そのカラムはスパースな シリアライゼーションで保存されます。 カラムがスパースである場合 (ほとんどの値がゼロである場合) 、ClickHouse はそれを スパースなフォーマットでエンコードし、計算を自動的に最適化できます。つまり、クエリ時に データを完全に伸長する必要がありません。このスパース シリアライゼーションを有効にするには、ratio_of_defaults_for_sparse_serialization 設定を 1.0 未満にしてください。値が 1.0 以上の場合、 カラムは常に通常の完全なシリアライゼーションで書き込まれます。 設定可能な値:
  • スパースなシリアライゼーションを有効にするには、0 から 1 の間の Float
  • スパースなシリアライゼーションを使用しない場合は、1.0 (またはそれ以上)
次のテーブルでは、s カラムは 95% の 行で空文字列です。my_regular_table ではスパースなシリアライゼーションを使用せず、 my_sparse_table では ratio_of_defaults_for_sparse_serialization を 0.95 に設定しています:
my_sparse_tables カラムが、ディスク上で使用するストレージ容量が少ないことに注目してください。
カラムでスパースエンコーディングが使用されているかどうかは、 system.parts_columns テーブルの serialization_kind カラムを見ることで確認できます:
s のどの部分がスパースシリアライゼーションで保存されたかを確認できます:

reduce_blocking_parts_sleep_ms

ClickHouse Cloudでのみ利用できます。どの範囲も削除または置換されなかった場合に、blocking parts の削減を再度試みるまでの最小待機時間です。設定値を小さくすると、background_schedule_pool 内のタスクが高頻度でトリガーされるため、大規模なクラスターでは ZooKeeper への大量のリクエストが発生します

replace_long_file_name_to_hash

カラムのファイル名が長すぎる場合 (‘max_file_name_length’ バイトを超える場合) は、SipHash128に置き換えます

replicated_can_become_leader

true の場合、このノード上のレプリケートテーブルのレプリカは リーダーになることを試みます。 設定可能な値:
  • true
  • false

search_orphaned_parts_disks

ClickHouse は、policy に含まれない未定義のディスク上にあるデータパーツの見落としを防ぐため、 ATTACH または CREATE table のたびに、孤立したパーツがないかすべてのディスクを走査します。 孤立したパーツは、たとえばディスクが storage policy から除外された場合のような、 安全でない可能性があるストレージの再構成によって発生します。 この設定では、ディスクの特性に基づいて検索対象とするディスクの範囲を制限します。 設定可能な値:
  • any - 範囲は制限されません。
  • local - 範囲はローカルディスクに制限されます。
  • none - 対象範囲を空にし、検索しません

serialization_info_version

serialization.json の書き込み時に使用するシリアライゼーションバージョンです。 この設定は、クラスターのアップグレード時に互換性を保つために必要です。 設定可能な値:
  • basic - 基本フォーマット。
  • with_types - 追加の types_serialization_versions フィールドを含むフォーマットで、型ごとのシリアライゼーションバージョンを使用できます。 これにより、string_serialization_version のような設定が有効になります。
ローリングアップグレード中は、これを basic に設定し、新しいサーバーが 古いサーバーと互換性のあるデータパーツを生成するようにします。アップグレード完了後は、 型ごとのシリアライゼーションバージョンを有効にするため、WITH_TYPES に切り替えます。

share_nested_offsets

有効時 (デフォルト) には、共通のプレフィックスを持つドット区切りの名前の Array カラム (例: n.a および n.b) は Nested 構造の一部として扱われます。これらはディスク上の単一の offsets ファイル (例: n.size0) を共有し、 INSERT 時には配列サイズが同一であることが検証されます。 無効時には、各 Array カラムがそれぞれ独立した offsets ファイルを持ち、ドット区切りの名前に特別な セマンティクスはなくなります。また、同じプレフィックスを共有するドット区切りの Array カラムと スカラー カラムを共存させることもできます (例: n UInt32n.a Array(String)) 。この設定はテーブル作成後は変更できません。

simultaneous_parts_removal_limit

古いパーツが多数ある場合、クリーンアップスレッドは1回の反復で最大 simultaneous_parts_removal_limit 個のパーツを削除しようとします。 simultaneous_parts_removal_limit0 に設定すると、上限なしを意味します。

storage_policy

ストレージディスクポリシー名

string_serialization_version

トップレベルの String カラムのシリアライゼーション フォーマットを制御します。 この設定は、serialization_info_version が “with_types” に設定されている場合にのみ有効です。 with_size_stream に設定すると、トップレベルの String カラムは、サイズをインラインで格納するのではなく、 文字列長を格納する独立した .size サブカラムを使ってシリアライズされます。これにより実際の .size サブカラムを利用できるようになり、圧縮効率が向上する場合があります。 ネストされた String 型 (たとえば NullableLowCardinalityArrayMap の内部にあるもの) は、Tuple 内に現れる場合を除き、影響を受けません。 設定可能な値:
  • single_stream — サイズをインラインで格納する標準のシリアライゼーション フォーマットを使用します。
  • with_size_stream — トップレベルの String カラムに対して、独立したサイズストリームを使用します。

temporary_directories_lifetime

tmp_ディレクトリを保持する期間 (秒) です。この値は下げないでください。 この設定値が小さいと、マージやミューテーションが正常に動作しない可能性があるためです。

try_fetch_recompressed_part_timeout

再圧縮を伴うマージを開始するまでのタイムアウト時間 (秒) 。この間、 ClickHouse は、この再圧縮を伴うマージが割り当てられたレプリカから、 再圧縮済みのパートを取得しようとします。 再圧縮は多くの場合低速なため、このタイムアウトが経過するまでは 再圧縮を伴うマージを開始せず、この再圧縮を伴うマージが割り当てられた レプリカから再圧縮済みのパートを取得しようとします。 設定可能な値:
  • 任意の正の整数。

ttl_only_drop_parts

TTL 設定に従ってそのパーツ内のすべての行の有効期限が切れた場合に、 MergeTree テーブルでデータパーツ全体を完全に削除するかどうかを制御します。 ttl_only_drop_parts が無効な場合 (デフォルト) 、 TTL 設定に基づいて有効期限が切れた行のみが削除されます。 ttl_only_drop_parts が有効な場合、 TTL 設定に従ってそのパーツ内のすべての行の有効期限が切れていれば、パーツ全体が削除されます。

wait_for_unique_parts_send_before_shutdown_ms

シャットダウン前に、テーブルは一意なパーツ (現在のレプリカにのみ存在するもの) が他のレプリカにフェッチされるまで、必要な時間だけ待機します (0 は 無効を意味します) 。

zookeeper_session_expiration_check_period

ZooKeeper セッションの有効期限切れを確認する間隔 (秒単位) 。 設定可能な値:
  • 任意の正の整数。
最終更新日 2026年7月24日