> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# merge_tree_* 会话设置

> merge_tree_* 自动生成分组中的 ClickHouse 会话设置。

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>;
};

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>;
};

这些设置可在 [system.settings](/docs/zh/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 中生效。此设置指定 MergeTree 表的 compact part 中单个 stripe 的粒度数达到多少时使用 multibuffer reader；该读取器支持并行读取和预取。从远程文件系统读取时，使用 multibuffer reader 会增加读取请求的数量。当某个分片包含的粒度数既小于此阈值，又小于正在读取的列数时，会使用 single buffer reader 读取该分片，因为在这种情况下，single buffer reader 发出的读取请求少于 multibuffer reader。

<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": "用于限制主键索引上 generic exclusion search 步数的新设置。"}]}]} />

当某个过滤器无法被评估为主键上的单个连续范围时，例如它使用了除第一个键列之外的其他键列，ClickHouse 会在索引标记上运行迭代式的 generic exclusion search algorithm。分析 text index 时也会使用同样的算法。此设置会限制该算法在每个数据分区片段上消耗的步数 (索引检查次数) 。

预算会优先用于当前剩余的最大标记范围。当预算耗尽时，尚未完全分析的范围会被整体接受，因此查询结果仍然正确，但读取的粒度可能会比无限制搜索选出的更多。预算越低，索引分析越快，但代价是需要读取更多数据。该限制是近似限制，而不是分析成本的严格上限：搜索大致可能会多出一轮拆分；并且当该分区片段已经被划分为许多范围时 (例如由 query condition cache 导致) ，无论限制值是多少，每个范围至少都会被检查一次。

搜索在每个数据分区片段上执行的步数会记录在该查询的 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" />

如果 ClickHouse 在一次查询中需要读取超过 `merge_tree_max_bytes_to_use_cache` 字节的数据，则不会使用未压缩块缓存。

未压缩块缓存用于存储为查询提取的数据。ClickHouse 使用此缓存来加快重复的小型查询的响应速度。此设置可防止读取大量数据的查询冲刷缓存。[uncompressed\_cache\_size](/docs/zh/reference/settings/server-settings/settings#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 在一次查询中需要读取的行数超过 `merge_tree_max_rows_to_use_cache`，则不会使用未压缩块缓存。

未压缩块缓存用于存储为查询提取出的数据。ClickHouse 使用此缓存来加快重复执行的小型查询的响应速度。此设置可防止读取大量数据的查询污染缓存。[uncompressed\_cache\_size](/docs/zh/reference/settings/server-settings/settings#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](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎的表中的单个文件读取的字节数超过 `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](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎可并行读取前，单个文件至少需要读取的字节数。我们不建议使用此设置。

可能的值：

* 正整数。

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

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

如果在同一个文件中待读取的两个数据块之间的距离小于 `merge_tree_min_bytes_for_seek` 字节，ClickHouse 就会顺序读取包含这两个块的那段文件范围，从而避免额外的寻道。

可能的值：

* 任意正整数。

<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](/docs/zh/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](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree) 引擎开始并行读取前，单个文件至少需要读取的行数。我们不建议使用此设置。

可能的值：

* 正整数。

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

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

如果在同一文件中，要读取的两个数据块之间的距离小于 `merge_tree_min_rows_for_seek` 行，ClickHouse 就不会在文件中执行寻道，而是顺序读取数据。

可能的值：

* 任意正整数。

<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 中对 Wide parts 进行前缀并行反序列化时是否使用线程池"}]}]} />

启用在线程池中对 MergeTree 的 Wide parts 进行前缀并行读取。该线程池的大小由服务器设置 `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 将对 JSON 和 Dynamic 类型使用 V1 序列化版本，而不是 V2。更改此设置仅在 server 重启后才会生效。