> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# merge_tree_* セッション設定

> merge_tree_* の自動生成グループに属する ClickHouse のセッション設定。

export const CloudOnlyBadge = () => {
  return <div className="cloudBadge">
            <div className="cloudIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path fillRule="evenodd" clipRule="evenodd" d="M5.33395 12.6667H12.3739C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00004 12.3739 8.00004H12.0839V7.33337C12.0839 5.12671 10.2906 3.33337 8.08395 3.33337C6.09928 3.33337 4.45395 4.78537 4.14195 6.68204C2.55728 6.76271 1.29395 8.06204 1.29395 9.66671C1.29395 11.3234 2.63728 12.6667 4.29395 12.6667H5.33395Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'ClickHouse Cloud 専用'}
        </div>;
};

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["バージョン", "デフォルト値", "コメント"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        バージョン履歴
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>型</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>デフォルト値</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          再起動せずに変更可能
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

これらの設定は [system.settings](/ja/reference/system-tables/settings) で確認でき、[ソースコード](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) から自動生成されています。

<div id="merge_tree_coarse_index_granularity">
  ## merge\_tree\_coarse\_index\_granularity
</div>

<SettingsInfoBlock type="UInt64" default_value="8" />

データを検索する際、ClickHouse は索引ファイル内のデータマークを確認します。必要なキーが含まれる範囲が見つかると、ClickHouse はその範囲を `merge_tree_coarse_index_granularity` 個の部分範囲に分割し、その中を再帰的に検索して必要なキーを探します。

設定可能な値:

* 正の偶数整数。

<div id="merge_tree_compact_parts_min_granules_to_multibuffer_read">
  ## merge\_tree\_compact\_parts\_min\_granules\_to\_multibuffer\_read
</div>

<CloudOnlyBadge />

<SettingsInfoBlock type="UInt64" default_value="16" />

ClickHouse Cloud でのみ有効です。並列読み取りと prefetch をサポートするマルチバッファリーダーを使用するために必要な、MergeTree テーブルの compact パーツ内のストライプに含まれるグラニュール数を指定します。リモート fs から読み取る場合、マルチバッファリーダーを使用すると読み取りリクエスト数が増加します。パーツに含まれるグラニュール数がこのしきい値未満であり、かつ読み取るカラム数よりも少ない場合、そのパーツは単一バッファで読み取られます。これは、その場合は単一バッファリーダーのほうがマルチバッファリーダーより少ない読み取りリクエストで済むためです。

<div id="merge_tree_determine_task_size_by_prewhere_columns">
  ## merge\_tree\_determine\_task\_size\_by\_prewhere\_columns
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

読み取りタスクサイズの決定に、prewhereカラムのサイズのみを使用するかどうか。

<div id="merge_tree_generic_exclusion_search_max_steps">
  ## merge\_tree\_generic\_exclusion\_search\_max\_steps
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": "0"},{"label": "主キー索引に対する汎用排除検索のステップ数を制限するための新しい設定。"}]}]} />

フィルタを主キーの単一の連続した範囲として評価できない場合、たとえば先頭以外のキーカラムを使用している場合、ClickHouse は索引マークに対して反復的な汎用排除検索アルゴリズムを実行します。同じアルゴリズムは、テキスト索引の解析にも使用されます。この設定は、アルゴリズムが各データパートに費やすステップ数 (索引のチェック回数) を制限します。

この予算は、残っている中で最も大きいマーク範囲から優先的に消費されます。予算を使い切ると、完全に解析されなかった範囲はひとかたまりとして受け入れられるため、クエリの正しさは保たれますが、無制限の検索で選択される場合よりも多くのグラニュールを読み取ることがあります。予算を小さくすると、読み取るデータ量が増える代わりに索引解析は高速になります。この制限は解析コストの厳密な上限ではなく、検索はおおよそ 1 回の分割ラウンド分だけ超過することがあります。また、パートがすでに多数の範囲に分割されている場合 (たとえば query condition cache による場合) 、制限に関係なく各範囲は少なくとも 1 回チェックされます。

検索が各データパートで実行したステップ数は、クエリの trace レベルのログメッセージに記録されます。また、`IndexGenericExclusionSearchStepLimitReached` および `TextIndexGenericExclusionSearchStepLimitReached` profile events は、予算を使い切った回数をカウントします。

(既定の) 値 0 は、ステップ数が無制限であることを意味します。

設定可能な値:

* ステップ数を無制限にする 0、または任意の正の整数。

<div id="merge_tree_max_bytes_to_use_cache">
  ## merge\_tree\_max\_bytes\_to\_use\_cache
</div>

<SettingsInfoBlock type="UInt64" default_value="2013265920" />

1つのクエリで ClickHouse が `merge_tree_max_bytes_to_use_cache` バイトを超えるデータを読み取る必要がある場合、非圧縮ブロックのキャッシュは使用されません。

非圧縮ブロックのキャッシュには、クエリ用に抽出されたデータが保存されます。ClickHouse はこのキャッシュを使用して、繰り返し実行される小規模なクエリへの応答を高速化します。この設定は、大量のデータを読み取るクエリによってキャッシュが使い尽くされるのを防ぎます。[uncompressed\_cache\_size](/ja/reference/settings/server-settings/settings/uncompressed-cache#uncompressed_cache_size) サーバー設定で、非圧縮ブロックのキャッシュのサイズを定義します。

設定可能な値:

* 任意の正の整数。

<div id="merge_tree_max_rows_to_use_cache">
  ## merge\_tree\_max\_rows\_to\_use\_cache
</div>

<SettingsInfoBlock type="UInt64" default_value="1048576" />

ClickHouse が 1 回のクエリで `merge_tree_max_rows_to_use_cache` 行を超えて読み取る必要がある場合、非圧縮ブロックのキャッシュは使用されません。

非圧縮ブロックのキャッシュには、クエリ用に抽出されたデータが保存されます。ClickHouse はこのキャッシュを使用して、繰り返し実行される小規模なクエリへの応答を高速化します。この設定は、大量のデータを読み取るクエリによってキャッシュが無駄に消費されるのを防ぎます。[uncompressed\_cache\_size](/ja/reference/settings/server-settings/settings/uncompressed-cache#uncompressed_cache_size) サーバー設定で、非圧縮ブロックのキャッシュのサイズを定義します。

設定可能な値:

* 任意の正の整数。

<div id="merge_tree_min_bytes_for_concurrent_read">
  ## merge\_tree\_min\_bytes\_for\_concurrent\_read
</div>

<SettingsInfoBlock type="UInt64" default_value="251658240" />

[MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree)エンジンのテーブルにおいて、1つのファイルから読み取るバイト数が `merge_tree_min_bytes_for_concurrent_read` を超える場合、ClickHouse はこのファイルを複数のスレッドで同時に読み取ろうとします。

設定可能な値:

* 正の整数。

<div id="merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem">
  ## merge\_tree\_min\_bytes\_for\_concurrent\_read\_for\_remote\_filesystem
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "0"},{"label": "設定は非推奨"}]}]} />

リモートファイルシステムから読み取る際に、[MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree)エンジンが並列読み取りを開始するまでに、1つのファイルから読み取る最小バイト数です。この設定の使用は推奨されません。

設定可能な値:

* 正の整数。

<div id="merge_tree_min_bytes_for_seek">
  ## merge\_tree\_min\_bytes\_for\_seek
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

1 つのファイル内で読み取る 2 つのデータブロック間の距離が `merge_tree_min_bytes_for_seek` バイト未満の場合、ClickHouse は追加の シーク を避けるため、両方のブロックを含むファイル範囲を順次読み取ります。

設定可能な値:

* 任意の正の整数。

<div id="merge_tree_min_bytes_per_read_stream">
  ## merge\_tree\_min\_bytes\_per\_read\_stream
</div>

<SettingsInfoBlock type="UInt64" default_value="65536" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "65536"},{"label": "sqrt コストモデルを用いて、通常のローカル非順序 `MergeTree` における狭いカラムのスキャン時のストリーム数に上限を設ける新しい設定。コア数の多いマシンでストリームごとのオーバーヘッドを削減します。previous_value=0（無効）のため、26.8 より前のバージョンとの `compatibility` により、従来のストリーム数が復元されます。"}]}]} />

バイト換算で表したストリームごとのオーバーヘッドコストです。通常のローカル非順序 `MergeTree` スキャンで作成される読み取りストリームの最大数を制御します。順序付き読み取り、`FINAL`、レイヤー化された読み取り、および並列レプリカ読み取りには影響しません。ボリュームベースの上限は `ceil(sqrt(estimated_read_bytes / this_setting))` です。ClickHouse では、少なくとも 16 ストリーム、およびこの上限を適用する前に要求されたストリーム数の少なくとも 4 分の 1 が維持されるため、実効ストリーム数は `min(requested_streams, max(volume_based_cap, 16, floor(requested_streams / 4)))` となります。これらの下限により、コストが `estimated_read_bytes` には反映されない、CPU 負荷の高い式や集計において下流の並列度が維持されます。

`estimated_read_bytes` は、索引およびパーティションプルーニング後に残ったマーク範囲で読み取られるカラムの非圧縮サイズです。ストリームごとのオーバーヘッドは、圧縮率ではなく処理される値の数に比例するストリームごとの作業量とのトレードオフになるため、非圧縮サイズが使用されます。

読み取りボリュームを保守的に見積もれない場合、この上限は適用されません。たとえば、古いパートで新しく追加された `DEFAULT` カラムを評価するために他の物理カラムを読む必要がある場合や、選択された範囲で可変幅カラムの一部のみを読み取る場合です。

デフォルトの 64 KB は、`T(N) = W/N + F + V·N` というコストモデルから導出されています。ここで、`W` は有効な作業量、`F` は固定のパイプラインオーバーヘッド、`V` はストリームごとの可変コストです。最適なストリーム数は `sqrt(W/V)` です。スループットを介して `W` をバイトで表すと、`C = throughput · V ≈ 400 MB/s · 0.17 ms ≈ 64 KB` となります。この値を大きくするとストリーム数は減少し (より保守的になり) 、小さくするとより多くのストリームが許可されます。この最適化を無効にするには 0 に設定します。

設定可能な値:

* 非負の整数。

<div id="merge_tree_min_bytes_per_task_for_remote_reading">
  ## merge\_tree\_min\_bytes\_per\_task\_for\_remote\_reading
</div>

**別名**: `filesystem_prefetch_min_bytes_for_single_read_task`

<SettingsInfoBlock type="UInt64" default_value="2097152" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.8"},{"label": "2097152"},{"label": "値は `filesystem_prefetch_min_bytes_for_single_read_task` に統一されました"}]}]} />

タスクごとに読み取る最小バイト数。

<div id="merge_tree_min_read_task_size">
  ## merge\_tree\_min\_read\_task\_size
</div>

<SettingsInfoBlock type="NonZeroUInt64" default_value="8" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "8"},{"label": "新しい設定"}]}]} />

タスクサイズの厳格な下限値 (グラニュール の数が少なく、利用可能なスレッド数が多い場合でも、これより小さいタスクは割り当てられません

<div id="merge_tree_min_rows_for_concurrent_read">
  ## merge\_tree\_min\_rows\_for\_concurrent\_read
</div>

<SettingsInfoBlock type="UInt64" default_value="163840" />

[MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree) テーブルのファイルから読み取る行数が `merge_tree_min_rows_for_concurrent_read` を超えると、ClickHouse はこのファイルを複数のスレッドで同時に読み取ろうとします。

設定可能な値:

* 正の整数。

<div id="merge_tree_min_rows_for_concurrent_read_for_remote_filesystem">
  ## merge\_tree\_min\_rows\_for\_concurrent\_read\_for\_remote\_filesystem
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.10"},{"label": "0"},{"label": "設定は非推奨"}]}]} />

リモートファイルシステムからの読み取り時に、[MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree)エンジンが読み取りを並列化できるようになるまでに、1つのファイルから読み取る最小行数です。この設定の使用は推奨されません。

設定可能な値:

* 正の整数。

<div id="merge_tree_min_rows_for_seek">
  ## merge\_tree\_min\_rows\_for\_seek
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

1 つのファイル内で読み取る 2 つのデータブロック間の距離が `merge_tree_min_rows_for_seek` 行未満の場合、ClickHouse はファイル内でシークを行わず、データを順次読み取ります。

設定可能な値:

* 任意の正の整数。

<div id="merge_tree_prefetch_json_shared_data_substreams">
  ## merge\_tree\_prefetch\_json\_shared\_data\_substreams
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "1"},{"label": "Wide パーツで索引マークへのシークにより読み取られる JSON 共有データサブストリームのプリフェッチを制御する新しい設定。"}]}]} />

索引マークへのシークにより読み取られる Wide パーツ内の JSON 共有データサブストリームのプリフェッチを有効にします。このようなプリフェッチはグラニュールの先頭から読み取りますが、通常そこはサブストリームの読み取り位置ではないため、無駄になる場合があります。これらのプリフェッチをスキップするには、無効にします。

<div id="merge_tree_read_split_ranges_into_intersecting_and_non_intersecting_injection_probability">
  ## merge\_tree\_read\_split\_ranges\_into\_intersecting\_and\_non\_intersecting\_injection\_probability
</div>

<SettingsInfoBlock type="Float" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.3"},{"label": "0"},{"label": "`PartsSplitter` のテスト用。指定した確率で、MergeTree から読み取るたびに読み取り範囲を交差する範囲と交差しない範囲に分割します。"}]}]} />

`PartsSplitter` のテスト用。指定した確率で、MergeTree から読み取るたびに読み取り範囲を交差する範囲と交差しない範囲に分割します。

<div id="merge_tree_storage_snapshot_sleep_ms">
  ## merge\_tree\_storage\_snapshot\_sleep\_ms
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.6"},{"label": "0"},{"label": "クエリ内のストレージスナップショットの整合性をデバッグするための新しい設定"}]}]} />

MergeTree テーブルのストレージスナップショット作成時に、人為的な遅延 (ミリ秒単位) を挿入します。
テストおよびデバッグ専用です。

設定可能な値:

* 0 - 遅延なし (デフォルト)
* N - ミリ秒単位の遅延

<div id="merge_tree_use_const_size_tasks_for_remote_reading">
  ## merge\_tree\_use\_const\_size\_tasks\_for\_remote\_reading
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

リモートテーブルから読み取る際に、一定サイズのタスクを使用するかどうか。

<div id="merge_tree_use_deserialization_prefixes_cache">
  ## merge\_tree\_use\_deserialization\_prefixes\_cache
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.2"},{"label": "1"},{"label": "MergeTree におけるデシリアライゼーションプレフィックスキャッシュの使用を制御する新しい設定"}]}]} />

MergeTree でリモートディスクから読み取る際に、ファイルのプレフィックス内のカラムメタデータをキャッシュする機能を有効にします。

<div id="merge_tree_use_prefixes_deserialization_thread_pool">
  ## merge\_tree\_use\_prefixes\_deserialization\_thread\_pool
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.2"},{"label": "1"},{"label": "MergeTree におけるプレフィックスの並列デシリアライゼーション用スレッドプールの使用を制御する新しい設定"}]}]} />

MergeTree の wide パーツでプレフィックスを並列に読み取る際に、スレッドプールを使用するようにします。このスレッドプールのサイズは、サーバー設定 `max_prefixes_deserialization_thread_pool_size` で制御されます。

<div id="merge_tree_use_v1_object_and_dynamic_serialization">
  ## merge\_tree\_use\_v1\_object\_and\_dynamic\_serialization
</div>

<SettingsInfoBlock type="Bool" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "24.11"},{"label": "0"},{"label": "JSON および Dynamic 型向けの新しいシリアル化バージョン V2 を追加"}]}]} />

有効にすると、MergeTree では V2 の代わりに JSON 型および Dynamic 型のシリアル化バージョン V1 が使用されます。この設定の変更は、サーバーの再起動後にのみ反映されます。