> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> `system.merge_tree_settings` 中的 MergeTree 相关设置
# MergeTree 表设置
export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
const cells = [["Type", {type}], ["Default value", {default_value}]];
if (changeable_without_restart) {
const isYes = String(changeable_without_restart).trim().toLowerCase() === "yes";
const badge = isYes ? Yes : No;
cells.push(["Changeable without restart", badge]);
}
return
{cells.map(([h]) => | {h} | )}
{cells.map(([h, v]) => | {v} | )}
;
};
export const galaxyOnClick = eventName => () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
if (link) {
return
Beta
;
}
return ;
};
export const ExperimentalBadge = () => {
return ;
};
系统表 `system.merge_tree_settings` 显示全局设置的 MergeTree 设置。
MergeTree 设置可以在服务器配置文件的 `merge_tree` 部分中进行设置，也可以针对每个 `MergeTree` 表，在 `CREATE TABLE` 语句的 `SETTINGS` 子句中单独指定。
自定义设置 `max_suspicious_broken_parts` 的示例：
在服务器配置文件中为所有 `MergeTree` 表配置默认值：
```text theme={null}
5
```
针对特定表的设置：
```sql theme={null}
CREATE TABLE tab
(
`A` Int64
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS max_suspicious_broken_parts = 500;
```
使用 `ALTER TABLE ... MODIFY SETTING` 更改特定表的 Settings：
```sql theme={null}
ALTER TABLE tab MODIFY SETTING max_suspicious_broken_parts = 100;
-- 重置为全局默认值（取自 system.merge_tree_settings）
ALTER TABLE tab RESET SETTING max_suspicious_broken_parts;
```
## MergeTree 设置
## adaptive\_write\_buffer\_initial\_size
自适应写缓冲区的初始大小
## add\_implicit\_sign\_column\_constraint\_for\_collapsing\_engine
如果为 true，则会为 CollapsingMergeTree
或 VersionedCollapsingMergeTree 表中的 `sign` 列添加隐式约束，
只允许使用有效值 (`1` 和 `-1`) 。
## add\_minmax\_index\_for\_block\_number\_column
启用后，会为持久化虚拟列 `_block_number` 添加一个隐式 min-max (跳过) 索引。
需要设置 `enable_block_number_column = 1` 才能生效。该索引仅在合并期间构建，
不会在插入期间构建：在写入时，块编号还是临时的，因此只会为一个常量建立索引。
## add\_minmax\_index\_for\_block\_offset\_column
启用后，会为持久化虚拟列 `_block_offset` 添加隐式的最小-最大 (跳过) 索引。
需要将 `enable_block_offset_column = 1` 才会生效。该索引仅在合并期间构建，
不会在插入期间构建。
## add\_minmax\_index\_for\_numeric\_columns
启用后，会为表中的所有数值列添加 min-max (数据跳过) 索引。
## add\_minmax\_index\_for\_string\_columns
启用后，将为表中的所有字符串列添加 min-max (跳过) 索引。
## add\_minmax\_index\_for\_temporal\_columns
启用后，会为表中所有 Date、Date32、Time、Time64、DateTime 和 DateTime64 列添加 min-max (跳过) 索引
## allow\_coalescing\_columns\_in\_partition\_or\_order\_key
启用后，允许在 CoalescingMergeTree 表中将合并列用于
分区键或排序键。
## allow\_commit\_order\_projection
启用按提交顺序的投影，用于存储 `_block_number` 和 `_block_offset` 虚拟列，并在 merges 过程中保留原始插入顺序。
要求同时启用 `enable_block_number_column` 和 `enable_block_offset_column`。
## allow\_experimental\_replacing\_merge\_with\_cleanup
允许对带有 `is_deleted`
列的 ReplacingMergeTree 使用实验性的 CLEANUP 合并。启用后，可使用 `OPTIMIZE ... FINAL CLEANUP` 手动将一个分区中的所有 parts
合并为单个 part，并删除所有
已删除的行。
还允许通过设置 `min_age_to_force_merge_seconds`、
`min_age_to_force_merge_on_partition_only` 和
`enable_replacing_merge_with_cleanup_for_min_age_to_force_merge`，
使此类合并在后台自动执行。
## allow\_experimental\_reverse\_key
启用对 MergeTree 排序键中降序排列的支持。此设置对于时间序列分析和 Top-N 查询尤其有用，可按时间逆序存储数据，从而优化查询性能。
启用 `allow_experimental_reverse_key` 后，您可以在 MergeTree 表的 `ORDER BY` 子句中定义降序排序。这使得降序查询可以使用效率更高的 `ReadInOrder` 优化，而不是 `ReadInReverseOrder`。
**示例**
```sql theme={null}
CREATE TABLE example
(
time DateTime,
key Int32,
value String
) ENGINE = MergeTree
ORDER BY (time DESC, key) -- 'time' 字段降序排列
SETTINGS allow_experimental_reverse_key = 1;
SELECT * FROM example WHERE key = 'xxx' ORDER BY time DESC LIMIT 10;
```
在查询中使用 `ORDER BY time DESC` 时，会启用 `ReadInOrder`。
**默认值：** false
## allow\_floating\_point\_partition\_key
启用后可允许将浮点数作为分区键。
可能的值：
* `0` — 不允许使用浮点分区键。
* `1` — 允许使用浮点分区键。
## allow\_nullable\_key
允许将 Nullable 类型作为主键。
## allow\_part\_offset\_column\_in\_projections
允许在投影的 SELECT 查询中使用 '\_part\_offset' 列。
## allow\_reduce\_blocking\_parts\_task
用于减少 shared merge tree 表中阻塞 parts 的后台任务。
仅适用于 ClickHouse Cloud
## allow\_remote\_fs\_zero\_copy\_replication
请勿在生产环境中使用此设置，因为它尚未成熟。
## allow\_summing\_columns\_in\_partition\_or\_order\_key
启用后，允许在 SummingMergeTree 表中将求和列用于
分区键或排序键。
## allow\_suspicious\_indices
拒绝表达式相同的主索引/二级索引和排序键
## allow\_vertical\_merges\_from\_compact\_to\_wide\_parts
允许将 compact parts 垂直合并为 wide parts。此设置在所有副本上
必须具有相同的值。
## alter\_column\_secondary\_index\_mode
配置是否允许对受次级索引覆盖的列执行修改操作的 `ALTER` 命令，以及在允许时应采取的处理方式。默认情况下，此类 `ALTER` 命令是允许的，并且会重建这些索引。
可能的值：
* `rebuild` (默认) ：重建 `ALTER` 命令中受该列影响的所有次级索引。
* `throw`：通过抛出异常，阻止对受**显式**次级索引覆盖的列执行任何 `ALTER`。隐式索引不受此限制影响，仍会被重建。
* `drop`：删除依赖的次级索引。新的 parts 将不再包含这些索引，因此需要使用 `MATERIALIZE INDEX` 重新创建。
* `compatibility`：与原始行为保持一致：对 `ALTER ... MODIFY COLUMN` 使用 `throw`，对 `ALTER ... UPDATE/DELETE` 使用 `rebuild`。
* `ignore`：仅供高级用户使用。它会使索引保持不一致状态，可能导致错误的查询结果。
## always\_fetch\_merged\_part
如果为 true，此副本将永远不会合并 parts，而会始终从其他副本下载已合并的 parts。
可能的值：
* true, false
## always\_use\_copy\_instead\_of\_hardlinks
在执行变更、replace、detach 等操作时，始终复制数据，而不是创建硬链接。
## apply\_patches\_on\_merge
如果为 true，则在合并时应用补丁分区片段
## assign\_part\_uuids
启用后，会为每个新的 part 分配一个唯一的 part 标识符。
启用前，请检查所有副本都支持 UUID v4。
## async\_block\_ids\_cache\_update\_wait\_ms
每次 insert 迭代等待 async\_block\_ids\_cache 更新的时间
## async\_insert
如果为 true，来自 INSERT 查询的数据会存储在队列中，随后在后台刷新到
表。
## auto\_statistics\_types
以逗号分隔的统计信息类型列表，会在所有适用列上自动计算。
支持的统计信息类型：tdigest、countmin、minmax、nullcount、uniq。
## background\_task\_preferred\_step\_execution\_time\_ms
执行一次 merge 或 mutation 中单个 step 的目标耗时。如果单个 step 耗时更长，
则可能会超过该时间
## cache\_populated\_by\_fetch
此设置仅适用于 ClickHouse Cloud。
当 `cache_populated_by_fetch` 被禁用时 (默认设置) ，新的数据 parts
只有在运行查询且该查询需要这些 parts 时，才会加载到文件系统缓存中。
如果启用，`cache_populated_by_fetch` 则会使所有节点将新的数据 parts
从存储加载到各自的文件系统缓存中，而无需由查询
来触发此操作。
**另请参阅**
* [ignore\_cold\_parts\_seconds](/zh/reference/settings/session-settings#ignore_cold_parts_seconds)
* [prefer\_warmed\_unmerged\_parts\_seconds](/zh/reference/settings/session-settings#prefer_warmed_unmerged_parts_seconds)
* [cache\_warmer\_threads](/zh/reference/settings/session-settings#cache_warmer_threads)
## cache\_populated\_by\_fetch\_filename\_regexp
此设置仅适用于 ClickHouse Cloud。
如果该值非空，则仅在拉取后将与此正则表达式匹配的文件预热到缓存中 (前提是已启用 `cache_populated_by_fetch`) 。
## check\_delay\_period
已废弃，没有任何作用。
## check\_sample\_column\_is\_correct
启用在创建表时检查用于采样的列或采样表达式的数据类型是否正确。该数据类型必须是以下无符号
[整数类型](/zh/reference/data-types/int-uint)之一：`UInt8`、`UInt16`、
`UInt32`、`UInt64`。
可能的值：
* `true` — 启用该检查。
* `false` — 在创建表时禁用该检查。
默认值：`true`。
默认情况下，ClickHouse server 会在创建表时检查用于采样的列或采样表达式的数据类型。如果你已经有使用了错误采样表达式的表，并且不希望服务器在启动期间引发异常，请将 `check_sample_column_is_correct` 设置为 `false`。
## clean\_deleted\_rows
已废弃，不起任何作用。
## cleanup\_delay\_period
清理旧队列日志、块哈希和 parts 的最短周期。
## cleanup\_delay\_period\_random\_add
向 cleanup\_delay\_period 额外添加一个从 0 到 x 秒均匀分布的值，
以避免在表数量非常庞大时出现惊群效应，并进而导致 ZooKeeper 遭受 DoS。
## cleanup\_thread\_preferred\_points\_per\_iteration
后台清理的建议批次大小 (点为抽象单位，但 1 个点
大致相当于 1 个已插入块) 。
## cleanup\_threads
已废弃，不起任何作用。
## clone\_replica\_zookeeper\_create\_get\_part\_batch\_size
克隆副本时，ZooKeeper multi-create get-part 请求的批次大小。
## columns\_and\_secondary\_indices\_sizes\_lazy\_calculation
在首次请求时才延迟计算列和次级索引的大小，
而不是在表初始化时计算。
## columns\_to\_prewarm\_mark\_cache
要预热标记缓存的列列表 (启用时) 。留空表示所有列
## compact\_parts\_max\_bytes\_to\_buffer
仅在 ClickHouse Cloud 中可用。compact parts 中单个
stripe 可写入的最大字节数
## compact\_parts\_max\_granules\_to\_buffer
仅在 ClickHouse Cloud 中可用。compact parts 中单个 stripe 内可写入的最大粒度数
## compact\_parts\_merge\_max\_bytes\_to\_prefetch\_part
仅在 ClickHouse Cloud 中可用。合并时可整体读入内存的 compact part 的最大大小。
## compatibility\_allow\_sampling\_expression\_not\_in\_primary\_key
允许创建 采样表达式 不在 主键 中的表。此设置仅用于在向后兼容场景下，临时允许运行包含错误表的 server。
## compress\_marks
标记支持压缩，这样既可减小标记文件大小，也能加快网络传输。
## compress\_per\_column\_in\_compact\_parts
控制 Compact parts 的物理布局。如果为 true (默认值) ，粒度中的每一列
都会从一个新的压缩块开始，这样 ClickHouse 就可以跳过从磁盘读取不必要的列。
如果为 false，则一个粒度内的所有列都会打包到同一个压缩块中，
从而提高压缩率，但读取时需要解压更多数据。
这对于始终读取所有列的工作负载 (例如投影) 很有帮助。
## compress\_primary\_key
支持对主键进行压缩，以减小主键文件大小并加快网络传输。
## concurrent\_part\_removal\_threshold
仅当非活动数据 parts 的数量至少达到该值时，
才会启用并发移除 parts (参见 `max_part_removal_threads`) 。
## concurrent\_part\_removal\_threshold\_for\_remote\_disk
与 `concurrent_part_removal_threshold` 相同，但用于至少有一个
被移除的 part 存储在远程磁盘上的情况。默认值之所以更低，
是因为在远程存储上移除每个 part 通常都需要一次网络
往返 (例如，在对象存储上，每个 part 都需要一次 HTTP `DELETE`) ，因此
即使串行移除 100 个 part，也可能让 `DROP TABLE` 卡住数十秒。
## deduplicate\_merge\_projection\_mode
是否允许为使用非经典 MergeTree (即不属于 (Replicated, Shared) MergeTree) 的表创建投影。
`ignore` 选项纯粹是出于兼容性考虑，可能会导致结果不正确。否则，如果允许，
则该设置决定在合并投影时执行的操作，即 `drop` 或 `rebuild`。因此，经典
MergeTree 会忽略此设置。它也控制 `OPTIMIZE DEDUPLICATE`，
但对所有 MergeTree 家族成员都生效。与
选项 `lightweight_mutation_projection_mode` 类似，它也是 part 级别的。
可能的值：
* `ignore`
* `throw`
* `drop`
* `rebuild`
## default\_compression\_codec
指定当表声明中未为特定列定义压缩编解码器时，所使用的默认压缩编解码器。
列的压缩编解码器选择顺序如下：
1. 在表声明中为该列定义的压缩编解码器
2. 在 `default_compression_codec` 中定义的压缩编解码器 (此设置)
3. 在 `compression` 设置中定义的默认压缩编解码器
默认值：空字符串 (未定义) 。
## detach\_not\_byte\_identical\_parts
启用或禁用以下行为：在执行合并或变更后，如果某个副本上的数据 parts 与其他副本上的数据 parts 在字节级别上不完全一致，则将其分离。如果禁用，则会移除该数据 parts。如果你希望稍后分析此类 parts，请启用此设置。
此设置适用于已启用
[数据复制](/zh/reference/engines/table-engines/mergetree-family/replacingmergetree)
的 `MergeTree` 表。
可能的值：
* `0` — 数据 parts 会被移除。
* `1` — 数据 parts 会被分离。
## detach\_old\_local\_parts\_when\_cloning\_replica
修复丢失的副本时，不要移除旧的本地 parts。
可能的值：
* `true`
* `false`
## disable\_detach\_partition\_for\_zero\_copy\_replication
禁用零拷贝复制中的 DETACH PARTITION 查询。
## disable\_fetch\_partition\_for\_zero\_copy\_replication
禁用零拷贝复制的 FETCH PARTITION 查询。
## disable\_freeze\_partition\_for\_zero\_copy\_replication
禁用零拷贝复制中的 FREEZE PARTITION 查询。
## disk
存储磁盘的名称。也可以指定此项来代替存储策略。
## distributed\_index\_analysis\_min\_indexes\_bytes\_to\_activate
激活分布式索引分析所需的最小索引大小 (磁盘上、按未压缩数据计；包括数据跳过索引和主键)
## distributed\_index\_analysis\_min\_parts\_to\_activate
激活分布式索引分析所需的最少 parts 数量
## dynamic\_serialization\_version
Dynamic 数据类型的序列化版本。用于兼容性。
可选值：
* `v1`
* `v2`
* `v3`
## enable\_block\_number\_column
启用为每一行持久保存 \_block\_number 列。
## enable\_block\_offset\_column
在合并过程中持久化虚拟列 `_block_offset`。
## enable\_index\_granularity\_compression
如果可以，则压缩内存中的索引粒度值
## enable\_max\_bytes\_limit\_for\_min\_age\_to\_force\_merge
控制设置 `min_age_to_force_merge_seconds` 和
`min_age_to_force_merge_on_partition_only` 是否遵循设置
`max_bytes_to_merge_at_max_space_in_pool`。
可能的值：
* `true`
* `false`
## enable\_mixed\_granularity\_parts
启用或禁用切换为通过 `index_granularity_bytes` 设置控制粒度大小。
在 19.11 版本之前，只有 `index_granularity` 设置可用于限制粒度大小。
`index_granularity_bytes` 设置可在从包含大行 (数十到数百 MB) 的表中选择数据时提升 ClickHouse 性能。
如果您的表包含大行，可以为这些表启用此设置，以提高 `SELECT` 查询的效率。
## enable\_replacing\_merge\_with\_cleanup\_for\_min\_age\_to\_force\_merge
在将分区合并为单个 part 时，是否对 ReplacingMergeTree 使用 CLEANUP 合并。
要求启用 `allow_experimental_replacing_merge_with_cleanup`、
`min_age_to_force_merge_seconds` 和 `min_age_to_force_merge_on_partition_only`。
可能的值：
* `true`
* `false`
## enable\_the\_endpoint\_id\_with\_zookeeper\_name\_prefix
为 Replicated MergeTree 表启用带 ZooKeeper 名称前缀的端点 ID。
## enable\_vertical\_merge\_algorithm
启用垂直合并算法。
## enforce\_index\_structure\_match\_on\_partition\_manipulation
如果为分区操作查询 (`ATTACH/MOVE/REPLACE PARTITION`) 的目标表启用此设置，则源表与目标表的索引和投影必须完全一致。否则，目标表可以包含源表索引和投影的超集。
## escape\_index\_filenames
在 26.1 之前，我们不会对为次级索引创建的文件名中的特殊符号进行转义，这可能导致某些
索引名称中的字符生成损坏的 parts。添加此项纯粹是出于兼容性考虑。除非你
正在读取名称中包含非 ASCII 字符索引的旧 parts，否则不应更改它。
## escape\_variant\_subcolumn\_filenames
对 MergeTree 表的 Wide parts 中为 Variant 数据类型子列创建的文件名中的特殊符号进行转义。此设置用于兼容性。
## exclude\_deleted\_rows\_for\_part\_size\_in\_merge
如果启用，在选择要合并的 parts 时，将按数据 parts 的预估实际大小 (即不包括通过 `DELETE FROM` 删除的那些行) 进行判断。请注意，此行为只会对在启用此设置后执行 `DELETE FROM` 所影响的数据 parts 生效。
可能的值：
* `true`
* `false`
**另请参见**
* [load\_existing\_rows\_count\_for\_old\_parts](#load_existing_rows_count_for_old_parts)
设置
## exclude\_materialize\_skip\_indexes\_on\_merge
将提供的以逗号分隔的跳过索引列表排除在合并期间的构建和存储之外。如果
[materialize\_skip\_indexes\_on\_merge](#materialize_skip_indexes_on_merge) 为 false，则此设置不起作用。
被排除的跳过索引仍会通过显式
[MATERIALIZE INDEX](/zh/reference/statements/alter/skipping-index#materialize-index) 查询构建并存储，或者根据
[materialize\_skip\_indexes\_on\_insert](/zh/reference/settings/session-settings#materialize_skip_indexes_on_insert)
会话设置，在 INSERT 期间构建并存储。
示例：
```sql theme={null}
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() SETTINGS exclude_materialize_skip_indexes_on_merge = 'idx_a';
INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- 该设置对 INSERT 操作无效
-- idx_a 将在后台合并或通过 OPTIMIZE TABLE FINAL 显式合并时被排除在更新之外
-- 可通过提供列表来排除多个索引
ALTER TABLE tab MODIFY SETTING exclude_materialize_skip_indexes_on_merge = 'idx_a, idx_b';
-- 默认设置，合并期间不排除任何索引的更新
ALTER TABLE tab MODIFY SETTING exclude_materialize_skip_indexes_on_merge = '';
```
## execute\_merges\_on\_single\_replica\_time\_threshold
当此设置的值大于 0 时，只有一个副本会立即开始合并，其他副本则最多等待这么长时间以下载合并结果，而不是在本地执行合并。如果所选副本未能在这段时间内完成合并，则会回退到标准行为。
可能的值：
* 任意正整数。
## fault\_probability\_after\_part\_commit
仅用于测试。请勿更改。
## 提交 part 前的故障概率
用于测试。请勿更改。
## finished\_mutations\_to\_keep
要保留多少条已完成的变更记录。如果为零，则保留
所有记录。
## force\_read\_through\_cache\_for\_merges
强制在合并过程中通过文件系统缓存读取
## fsync\_after\_insert
对每个已插入的 part 执行 fsync。会显著降低
insert 的性能，不建议与 wide parts 一起使用。
## fsync\_part\_directory
在所有 part 操作 (写入、重命名等) 完成后，对 part 目录执行 fsync。
## in\_memory\_parts\_enable\_wal
已废弃，无任何作用。
## in\_memory\_parts\_insert\_sync
已废弃，不起任何作用。
## inactive\_parts\_to\_delay\_insert
如果表中单个分区里的非活动 parts 数量超过
`inactive_parts_to_delay_insert` 的值，则会人为降低
`INSERT` 的速度。
当 server 无法足够快地清理 parts 时，此设置很有用。
可能的值：
* 任意正整数。
## inactive\_parts\_to\_throw\_insert
如果单个分区中的非活跃 parts 数量超过
`inactive_parts_to_throw_insert` 的值，`INSERT` 将被中断，并抛出
以下错误：
> "非活跃 parts 过多 (N) 。parts 清理速度明显
> 慢于插入操作" 异常。"
可能的值：
* 任意正整数。
## index\_granularity
索引标记之间的最大数据行数。也就是说，一个主键值对应多少行数据。
## index\_granularity\_bytes
数据粒度的最大字节大小。
如果仅想按行数限制粒度大小，请将其设置为 `0` (不推荐) 。
## initialization\_retry\_period
表初始化的重试周期 (以秒为单位) 。
## kill\_delay\_period
已废弃设置，无实际作用。
## kill\_delay\_period\_random\_add
已废弃设置，不起任何作用。
## kill\_threads
已废弃设置，不起任何作用。
## lightweight\_mutation\_projection\_mode
默认情况下，轻量级删除 `DELETE` 不适用于带有
projection 的表。这是因为 projection 中的行可能会受到
`DELETE` 操作的影响。因此，默认值为 `throw`。不过，这个
选项可以改变这种行为。当取值为 `drop` 或 `rebuild` 时，
删除操作将可与 projection 一起使用。`drop` 会删除 projection，因此在当前查询中
可能会更快，因为 projection 会被删除；但在后续查询中可能会变慢，
因为不再附加 projection。`rebuild` 会重建
projection，这可能会影响当前查询的性能，但
可能会加快后续查询。好的一点是，这些选项
只会在 part 级别生效，这意味着未被触及的分片中的 projection
将保持不变，而不会触发诸如
drop 或 rebuild 之类的任何操作。
可能的值：
* `throw`
* `drop`
* `rebuild`
## load\_existing\_rows\_count\_for\_old\_parts
如果与 [exclude\_deleted\_rows\_for\_part\_size\_in\_merge](#exclude_deleted_rows_for_part_size_in_merge) 一同启用，
系统会在表启动时计算现有数据 parts 中已删除的行数。
请注意，这可能会减慢表启动时的加载速度。
可能的值：
* `true`
* `false`
**另请参见**
* [exclude\_deleted\_rows\_for\_part\_size\_in\_merge](#exclude_deleted_rows_for_part_size_in_merge) 设置
## lock\_acquire\_timeout\_for\_background\_operations
对于合并、变更等后台操作，在获取表锁失败之前会等待多少秒。
## map\_buckets\_coefficient
在 `sqrt` 和 `linear` [map\_buckets\_strategy](#map_buckets_strategy) 中，用于根据平均 map 大小计算桶数量的系数。
对于 `sqrt` 策略：`round(map_buckets_coefficient * sqrt(avg_map_size))`。
对于 `linear` 策略：`round(map_buckets_coefficient * avg_map_size)`。
当 `map_buckets_strategy` 为 `constant` 时，此设置会被忽略。
## map\_buckets\_min\_avg\_size
应用 `with_buckets` 序列化所需的最小平均 Map 大小 (每行的键数) 。
如果平均 Map 大小小于该值，则无论其他桶设置如何，都只使用单个桶。
值为 `0` 时将禁用该阈值，并始终应用分桶策略。
此设置可用于避免对较小的 Map 使用分桶序列化所带来的额外开销，因为这种情况下收益微乎其微。
## map\_buckets\_strategy
控制在 `with_buckets` `Map` 序列化中，基于平均 map 大小选择桶数量的策略。
可能的值：
* constant — 始终使用 [max\_buckets\_in\_map](#max_buckets_in_map) 作为桶数量，而不考虑平均 map 大小。
* sqrt — 使用 `round(map_buckets_coefficient * sqrt(avg_map_size))` 作为桶数量，并将其限制在 `[1, max_buckets_in_map]` 范围内。
* linear — 使用 `round(map_buckets_coefficient * avg_map_size)` 作为桶数量，并将其限制在 `[1, max_buckets_in_map]` 范围内。
## map\_serialization\_version
控制 `Map` 列使用的序列化方法。
可能的值：
* basic — 对 `Map` 使用标准序列化。
* with\_buckets — 在序列化时将键拆分到多个桶中。使用桶可提升从 Map 中读取单个键的效率。
`with_buckets` serialization 中的桶数量由 [max\_buckets\_in\_map](#max_buckets_in_map) 和 [map\_buckets\_strategy](#map_buckets_strategy) 决定。
## map\_serialization\_version\_for\_zero\_level\_parts
此设置允许为插入时创建的零级 parts 中的
`Map` 列指定不同的序列化版本。
在零级 parts 中保留 `basic` 序列化有助于避免
插入期间性能下降，同时对合并后的 parts 使用 `with_buckets`。
## marks\_compress\_block\_size
标记压缩块大小，即压缩时块的实际大小。
## marks\_compression\_codec
标记 使用的压缩编码。标记 体积很小且会被缓存，因此
默认使用 ZSTD(3) 压缩。
## materialize\_skip\_indexes\_on\_merge
启用时，合并操作会为新的 parts 构建并存储数据跳过索引。
否则，它们可以通过显式执行 [MATERIALIZE INDEX](/zh/reference/statements/alter/skipping-index#materialize-index)
或 [在 INSERT 时](/zh/reference/settings/session-settings#materialize_skip_indexes_on_insert) 创建/存储。
另请参见 [exclude\_materialize\_skip\_indexes\_on\_merge](#exclude_materialize_skip_indexes_on_merge)，以进行更细粒度的控制。
## materialize\_statistics\_on\_merge
启用后，merge 会为新的 parts 构建并存储统计信息。
否则，可通过显式执行 [MATERIALIZE STATISTICS](/zh/reference/statements/alter/statistics)
或[在 INSERT 时](/zh/reference/settings/session-settings#materialize_statistics_on_insert)创建/存储这些统计信息
## materialize\_ttl\_recalculate\_only
仅在执行 MATERIALIZE 生存时间 (TTL) 时重新计算 生存时间 (TTL) 信息
## max\_avg\_part\_size\_for\_too\_many\_parts
根据 'parts\_to\_delay\_insert' 和
'parts\_to\_throw\_insert' 进行的“parts 过多”检查，
仅会在平均 part 大小 (在相关
分区中) 不大于指定阈值时生效。如果它
大于指定阈值，则 INSERT 既不会被延迟，也不会
被拒绝。这样一来，如果 parts 能成功合并为更大的 parts，就可以在
单台 server 上的单个表中存储数百 TB 的数据。这
不会影响非活跃 parts 或总 parts 数量的阈值。
## max\_buckets\_in\_map
`Map` 序列化的最大桶数。与 `with_buckets` `Map` 序列化配合使用。
实际桶数由 [map\_buckets\_strategy](#map_buckets_strategy) 决定。
允许的最大值为 256。
## max\_bytes\_to\_merge\_at\_max\_space\_in\_pool
在有足够可用资源的情况下，可合并为一个 part 的源 parts 总大小上限 (以字节为单位) 。它大致对应自动后台合并所能生成的最大 part 大小。 (0 表示禁用 merges)
可能的值：
* 任意非负整数。
合并调度器会定期分析各个分区中 parts 的大小和数量；如果池中有足够的空闲资源，就会启动后台合并。合并会持续进行，直到源 parts 的总大小超过 `max_bytes_to_merge_at_max_space_in_pool`。
由 [OPTIMIZE FINAL](/zh/reference/statements/optimize) 发起的合并会忽略 `max_bytes_to_merge_at_max_space_in_pool` (只考虑可用磁盘空间) 。
## max\_bytes\_to\_merge\_at\_min\_space\_in\_pool
在后台池可用资源最少时，可合并为一个 part 的最大总大小 (以字节为单位) 。
可选值：
* 任意正整数。
`max_bytes_to_merge_at_min_space_in_pool` 定义了即使在可用磁盘空间不足 (在池中) 的情况下，仍可进行合并的
parts 的最大总大小。这对于减少小 part 的数量以及降低出现
`Too many parts` 错误的概率是必要的。
合并会按被合并 parts 总大小的两倍预留磁盘空间。
因此，当磁盘剩余空间较少时，可能会出现这样的情况：虽然仍有空闲空间，但这些空间已经被正在进行的大型合并预留，
导致其他合并无法启动，而小 part 的数量会随着每次 insert 持续增长。
## max\_cleanup\_delay\_period
清理旧队列日志、块哈希值和 parts 的最长周期。
## max\_compress\_block\_size
写入表之前，对未压缩数据块进行压缩前的最大大小。你也可以在全局设置中指定此设置 (参见 [max\_compress\_block\_size](/zh/reference/settings/merge-tree-settings#max_compress_block_size) 设置) 。创建表时指定的值会覆盖此设置的全局值。
## max\_concurrent\_queries
与 MergeTree 表相关、可同时执行的查询的最大数量。
查询仍会受到其他 `max_concurrent_queries` 设置的限制。
可能的值：
* 正整数。
* `0` — 不限制。
默认值：`0` (不限制) 。
**示例**
```xml theme={null}
50
```
## max\_delay\_to\_insert
该值以秒为单位：如果单个分区中的活动 parts 数量超过
[parts\_to\_delay\_insert](#parts_to_delay_insert) 的值，
则用它来计算 `INSERT` 延迟。
可能的值：
* 任意正整数。
`INSERT` 延迟 (以毫秒为单位) 按以下公式计算：
```code theme={null}
max_k = parts_to_throw_insert - parts_to_delay_insert
k = 1 + parts_count_in_partition - parts_to_delay_insert
delay_milliseconds = pow(max_delay_to_insert * 1000, k / max_k)
```
例如，如果某个分区有 299 个活动 parts，且 parts\_to\_throw\_insert
\= 300，parts\_to\_delay\_insert = 150，max\_delay\_to\_insert = 1，则 `INSERT`
会延迟 `pow( 1 * 1000, (1 + 299 - 150) / (300 - 150) ) = 1000`
毫秒。
从 23.1 版本开始，公式改为：
```code theme={null}
allowed_parts_over_threshold = parts_to_throw_insert - parts_to_delay_insert
parts_over_threshold = parts_count_in_partition - parts_to_delay_insert + 1
delay_milliseconds = max(min_delay_to_insert_ms, (max_delay_to_insert * 1000)
* parts_over_threshold / allowed_parts_over_threshold)
```
例如，如果某个分区有 224 个活跃 parts，且 parts\_to\_throw\_insert
\= 300、parts\_to\_delay\_insert = 150、max\_delay\_to\_insert = 1，
min\_delay\_to\_insert\_ms = 10，则 `INSERT` 会延迟 `max( 10, 1 * 1000 *
(224 - 150 + 1) / (300 - 150) ) = 500` 毫秒。
## max\_delay\_to\_mutate\_ms
当存在大量未完成变更时，MergeTree 表执行变更的最大延迟时间 (以毫秒为单位)
## max\_digestion\_size\_per\_segment
已废弃，不起作用。
## max\_file\_name\_length
文件名在不进行哈希处理时可保持原样的最大长度。
仅在启用设置 `replace_long_file_name_to_hash` 时生效。
此设置的值不包含文件扩展名的长度。因此，
建议将其设置为略低于文件系统允许的最大文件名长度 (通常为 255
字节) ，并预留一定余量，以避免文件系统错误。
## max\_files\_to\_modify\_in\_alter\_columns
如果需要修改 (删除、新增) 的文件数量
大于此设置值，则不执行 ALTER。
可能的值：
* 任意正整数。
默认值：75
## max\_files\_to\_remove\_in\_alter\_columns
如果待删除的文件数量超过此设置值，则不执行 ALTER。
可能的值：
* 任意正整数。
## max\_merge\_delayed\_streams\_for\_parallel\_write
可并行刷新的流 (列) 的最大数量
(对于 merge，相当于 max\_insert\_delayed\_streams\_for\_parallel\_write) 。仅
对垂直合并生效。
## max\_merge\_selecting\_sleep\_ms
在未选中任何可供 merge 的 parts 后，再次尝试选择 parts 进行 merge 前的最长等待时间。将此设置调低，会更频繁地在
background\_schedule\_pool 中触发选择 task，这会在大规模 cluster 中产生大量对
ZooKeeper 的请求
## max\_number\_of\_merges\_with\_ttl\_in\_pool
当池中带有生存时间 (TTL) 条目的 merge 数量超过指定值时，不再分配新的带有生存时间 (TTL) 的 merge。这是为了给常规 merge 留出空闲线程，并避免出现 "parts 过多"
## max\_number\_of\_mutations\_for\_replica
将每个副本的 part mutation 数量限制为指定值。
零表示每个副本的变更数量不受限制 (执行
仍可能受到其他设置的约束) 。
## max\_part\_loading\_threads
已废弃设置，无任何作用。
## max\_part\_removal\_threads
已废弃设置，无任何作用。
## max\_partitions\_to\_read
限制单次查询可访问的最大分区数。
创建表时指定的设置值可通过
查询级设置覆盖。
可能的值：
* 任意正整数。
你也可以在查询 / 会话 / profile 级别指定查询复杂度设置 [max\_partitions\_to\_read](/zh/reference/settings/session-settings#max_partitions_to_read)。
## max\_parts\_in\_total
如果一个表所有分区中的活动 parts 总数超过
`max_parts_in_total` 的值，`INSERT` 将被中断，并抛出 `parts 过多
(N)` 异常。
可能的值：
* 任意正整数。
表中的 parts 数量过多会降低 ClickHouse 查询性能，
并增加 ClickHouse 启动时间。大多数情况下，这是设计不当造成的后果 (例如选择分区策略时出错——分区过小) 。
## max\_parts\_to\_merge\_at\_once
一次最多可合并的 parts 数量 (0 表示禁用) 。不影响
OPTIMIZE FINAL 查询。
## max\_postpone\_time\_for\_failed\_mutations\_ms
失败的变更操作允许延迟的最长时间。
## max\_postpone\_time\_for\_failed\_replicated\_fetches\_ms
失败的复制拉取任务的最大推迟时间。
## max\_postpone\_time\_for\_failed\_replicated\_merges\_ms
失败的复制合并任务的最大延后时间。
## max\_postpone\_time\_for\_failed\_replicated\_tasks\_ms
失败的复制任务可延后的最长时间。若任务不是拉取、合并或变更操作，则使用该值。
## max\_projections
MergeTree 投影的最大数量。
## max\_replicated\_fetches\_network\_bandwidth
限制[复制](/zh/reference/engines/table-engines/mergetree-family/replication)
拉取操作通过网络进行数据交换的最大速度，单位为每秒字节数。与应用于
服务器的
[`max_replicated_fetches_network_bandwidth_for_server`](/zh/reference/settings/merge-tree-settings#max_replicated_fetches_network_bandwidth)
设置不同，此设置适用于特定表。
你可以同时限制服务器网络和特定表的网络，但在这种情况下，
表级设置的值应小于服务器级设置的值。否则，服务器只会采用
`max_replicated_fetches_network_bandwidth_for_server` 设置。
该设置无法做到绝对精确。
可能的值：
* 正整数。
* `0` — 不限。
默认值：`0`。
**用法**
可用于在复制数据以新增或替换节点时限制速度。
## max\_replicated\_logs\_to\_keep
如果存在不活跃的副本，ClickHouse Keeper 日志中最多可包含多少条记录。超过此数量时，不活跃的副本将被视为丢失。
Possible values:
* 任意正整数。
## max\_replicated\_merges\_in\_queue
ReplicatedMergeTree 队列中允许同时进行的 parts 合并和变异任务数量。
## max\_replicated\_merges\_with\_ttl\_in\_queue
在 ReplicatedMergeTree 队列中，允许同时执行多少个带有生存时间 (TTL) 的 parts 合并任务。
## max\_replicated\_mutations\_in\_queue
ReplicatedMergeTree 队列中允许同时处理的 mutating parts 任务数。
## max\_replicated\_sends\_network\_bandwidth
限制 [replicated](/zh/reference/engines/table-engines/mergetree-family/replacingmergetree)
发送操作的最大网络数据交换速率，单位为每秒字节数。与应用于
服务器的
[`max_replicated_sends_network_bandwidth_for_server`](/zh/reference/settings/merge-tree-settings#max_replicated_sends_network_bandwidth)
设置不同，此设置作用于特定表。
你可以同时限制服务器网络和特定表的网络，但在这种情况下，
表级设置的值应小于服务器级设置的值。否则，服务器只会采用
`max_replicated_sends_network_bandwidth_for_server` 设置。
该设置无法做到完全精确。
可能的值：
* 正整数。
* `0` — 不限。
**用法**
可用于在复制数据以添加新节点或替换现有节点时进行限速。
## max\_suspicious\_broken\_parts
如果单个分区中的损坏 parts 数量超过
`max_suspicious_broken_parts` 的值，则不允许自动删除。
可能值：
* 任意正整数。
## max\_suspicious\_broken\_parts\_bytes
所有损坏 parts 的总大小上限，超过该值将禁止自动删除。
可能的值：
* 任意正整数。
## max\_uncompressed\_bytes\_in\_patches
所有补丁 parts 中数据的最大未压缩大小，单位为字节。
如果所有补丁 parts 中的数据量超过此值，将拒绝轻量级更新。
0 - 无限制。
## merge\_max\_block\_size
从已合并的 parts 读入内存的行数。
可能的值：
* 任意正整数。
合并操作会以每块 `merge_max_block_size` 行的块从 parts 中读取行，然后
进行合并，并将结果写入新的 part。读取的块会放入 RAM 中，
因此 `merge_max_block_size` 会影响合并所需的 RAM 大小。
因此，对于行非常宽的表，merges 可能会消耗大量 RAM
(如果平均每行大小为 100kb，那么在合并 10 个 parts 时，
(100kb \* 10 \* 8192) = \~ 8GB RAM) 。通过减小 `merge_max_block_size`，
你可以减少一次合并所需的 RAM 量，但会降低合并速度。
## merge\_max\_block\_size\_bytes
合并操作中生成的块应包含的字节数。默认情况下，
其值与 `index_granularity_bytes` 相同。
## merge\_max\_bytes\_to\_prewarm\_cache
仅在 ClickHouse Cloud 中可用。表示在 merge 期间用于预热缓存的 part (compact 或 packed) 的最大大小。
## merge\_max\_dynamic\_subcolumns\_in\_compact\_part
合并后，每一列在 Compact 数据 part 中可创建的动态子列最大数量。
该设置可用于控制 Compact 数据 part 中的动态子列数量，而不受数据类型中指定的动态参数影响。
例如，如果表中有一列的类型为 JSON(max\_dynamic\_paths=1024)，并且设置 merge\_max\_dynamic\_subcolumns\_in\_compact\_part 为 128，
那么在合并为 Compact 数据 part 后，该 part 中的动态路径数量将减少到 128，并且只有 128 条路径会作为动态子列写入。
## merge\_max\_dynamic\_subcolumns\_in\_wide\_part
合并后，每个列在 Wide 数据 part 中可创建的动态子列最大数量。
无论数据类型中指定了怎样的动态参数，它都可以减少 Wide 数据 part 中生成的文件数量。
例如，如果表中有一列的类型为 JSON(max\_dynamic\_paths=1024)，并且 merge\_max\_dynamic\_subcolumns\_in\_wide\_part 设置为 128，
那么合并到 Wide 数据 part 后，该 part 中的动态路径数量将减少到 128，并且只有 128 条路径会作为动态子列写入。
## merge\_selecting\_sleep\_ms
在未选中任何用于合并的 parts 后，再次尝试选择待合并 parts 之前的最短等待时间。较低的设置会更频繁地在
background\_schedule\_pool 中触发选择任务，从而在大规模集群中导致大量发往
ZooKeeper 的请求
## merge\_selecting\_sleep\_slowdown\_factor
当没有可合并的内容时，合并选择任务的休眠时间会乘以该因子；
当已分配合并任务时，则会除以该因子
## merge\_selector\_algorithm
用于选择分配给合并操作的 parts 的算法
## merge\_selector\_base
影响已指定合并任务的写入放大 (专家级设置；如果不了解其作用，请勿更改) 。
适用于 Simple 和 StochasticSimple 合并选择器
## merge\_selector\_blurry\_base\_scale\_factor
控制该逻辑根据分区中 parts 的数量在何时触发。因子越大，触发反应越滞后。
## merge\_selector\_enable\_heuristic\_to\_lower\_max\_parts\_to\_merge\_at\_once
为简单合并选择器启用一种启发式策略，以降低单次可选合并的最大数量上限。
这样会增加并发合并的数量，有助于缓解 TOO\_MANY\_PARTS
错误，但同时也会提高写入放大。
## merge\_selector\_enable\_heuristic\_to\_remove\_small\_parts\_at\_right
启用用于选择合并 parts 的启发式策略：如果范围右侧的分片大小小于 `sum_size` 的指定比例 (0.01) ，则将其移除。
适用于 Simple 和 StochasticSimple 合并选择器
## merge\_selector\_heuristic\_to\_lower\_max\_parts\_to\_merge\_at\_once\_exponent
控制用于构建下降曲线公式的指数值。降低该指数会
减小合并宽度，从而增加写放大。反过来也成立。
## merge\_selector\_window\_size
一次要检查多少个 parts。
## merge\_total\_max\_bytes\_to\_prewarm\_cache
仅在 ClickHouse Cloud 中可用。合并期间用于预热缓存的 parts 总大小上限。
## merge\_tree\_clear\_old\_broken\_detached\_parts\_ttl\_timeout\_seconds
已废弃，无实际作用。
## merge\_tree\_clear\_old\_parts\_interval\_seconds
设置 ClickHouse 执行旧
parts、WAL 和变更清理操作的间隔秒数。
可能的值：
* 任意正整数。
## merge\_tree\_clear\_old\_temporary\_directories\_interval\_seconds
设置 ClickHouse 清理旧临时目录的执行间隔，单位为秒。
可能的值：
* 任意正整数。
## merge\_tree\_enable\_clear\_old\_broken\_detached
已废弃设置，无任何作用。
## merge\_with\_recompression\_ttl\_timeout
再次执行带有重新压缩生存时间 (TTL) 的合并前的最小延迟 (秒) 。
## merge\_with\_ttl\_timeout
重复执行带有删除 生存时间 (TTL) 的合并操作前的最小延迟 (秒) 。
## merge\_workload
用于控制资源在合并与其他工作负载之间的使用和共享方式。指定的值将作为该表后台合并的 `workload` 设置值使用。如果未指定 (空字符串) ，则改用服务器设置 `merge_workload`。
**另请参见**
* [工作负载调度](/zh/concepts/features/configuration/server-config/workload-scheduling)
## min\_absolute\_delay\_to\_close
触发关闭、停止处理请求，以及在 status 检查期间不
返回 Ok 的最小绝对延迟。
## min\_age\_to\_force\_merge\_on\_partition\_only
`min_age_to_force_merge_seconds` 是否仅应作用于整个分区，
而不作用于其子集。
默认情况下，会忽略设置 `max_bytes_to_merge_at_max_space_in_pool` (请参见
`enable_max_bytes_limit_for_min_age_to_force_merge`) 。
可能的值：
* true, false
## min\_age\_to\_force\_merge\_seconds
如果范围内的每个 part 的生命周期都超过
`min_age_to_force_merge_seconds`
的值，则合并这些 parts。
默认情况下，会忽略设置 `max_bytes_to_merge_at_max_space_in_pool`
(参见 `enable_max_bytes_limit_for_min_age_to_force_merge`) 。
可能的值：
* 正整数。
## min\_bytes\_for\_compact\_part
已废弃设置，没有任何作用。
## min\_bytes\_for\_full\_part\_storage
仅在 ClickHouse Cloud 中可用。使用 full 类型存储而非 packed 所需的数据 part 最小未压缩字节数。
## min\_bytes\_for\_wide\_part
可按 `Wide`
格式存储的数据分区片段的最小字节数/行数。你可以只设置其中一个，也可以两个都设置，或者都不设置。
## min\_bytes\_to\_prewarm\_caches
用于为新 parts 预热标记缓存和主索引缓存的最小大小 (按未压缩字节数计)
## min\_bytes\_to\_rebalance\_partition\_over\_jbod
设置在将新的大型
parts 分布到卷磁盘 [JBOD](https://en.wikipedia.org/wiki/Non-RAID_drive_architectures) 上时，
启用均衡所需的最小字节数。
可能的值：
* 正整数。
* `0` — 禁用均衡。
**用法**
`min_bytes_to_rebalance_partition_over_jbod` 设置的值
不应小于
[max\_bytes\_to\_merge\_at\_max\_space\_in\_pool](/zh/reference/settings/merge-tree-settings#max_bytes_to_merge_at_max_space_in_pool)
/ 1024 的值。否则，ClickHouse 会抛出异常。
## min\_columns\_to\_activate\_adaptive\_write\_buffer
通过使用自适应写入缓冲区，可降低包含大量列的表的内存占用。
可能的值：
* 0 - 不受限制
* 1 - 始终启用
## min\_compress\_block\_size
写入下一个标记时，未压缩数据块在进行压缩前所需达到的最小大小。您也可以在全局设置中指定此设置
(参见 [min\_compress\_block\_size](/zh/reference/settings/merge-tree-settings#min_compress_block_size)
设置) 。创建表时指定的值会覆盖此设置的全局值。
## min\_compressed\_bytes\_to\_fsync\_after\_fetch
拉取后对分片执行 `fsync` 所需的最小压缩字节数 (0 表示禁用)
## min\_compressed\_bytes\_to\_fsync\_after\_merge
合并后对分片执行 fsync 的最小压缩字节数 (0 表示禁用)
## min\_delay\_to\_insert\_ms
当单个分区中存在大量未合并的 parts 时，将数据插入 MergeTree 表的最小延迟 (以毫秒为单位) 。
## min\_delay\_to\_mutate\_ms
当存在大量未完成的变更时，对 MergeTree 表执行变更的最小延迟 (以毫秒为单位)
## min\_free\_disk\_bytes\_to\_perform\_insert
执行数据插入所需的最小磁盘空闲字节数。如果可用空闲字节数小于
`min_free_disk_bytes_to_perform_insert`，则会抛出异常，并且
不会执行插入。请注意，此设置：
* 会将 `keep_free_space_bytes` 设置考虑在内。
* 不会考虑
`INSERT` 操作即将写入的数据量。
* 仅在指定了正数 (非零) 字节数时才会进行检查
可能的值：
* 任意正整数。
如果同时指定了 `min_free_disk_bytes_to_perform_insert` 和 `min_free_disk_ratio_to_perform_insert`，
ClickHouse 将采用允许在更多磁盘空闲空间下执行
插入的那个值。
## min\_free\_disk\_ratio\_to\_perform\_insert
执行 `INSERT` 所需的最小空闲磁盘空间占总磁盘空间的比例。必须是一个
介于 0 和 1 之间的浮点值。请注意，此设置：
* 会将 `keep_free_space_bytes` 设置考虑在内。
* 不会考虑 `INSERT` 操作将要写入的数据量。
* 仅在指定了正数 (非零) 比例时才会进行检查
可能的值：
* Float，0.0 - 1.0
请注意，如果同时指定了 `min_free_disk_ratio_to_perform_insert` 和
`min_free_disk_bytes_to_perform_insert`，ClickHouse 将采用允许在更多空闲
磁盘空间下执行插入操作的那个值。
## min\_index\_granularity\_bytes
数据粒度允许的最小字节大小。
用于防止因误操作创建 `index_granularity_bytes` 过低的表。
## min\_level\_for\_full\_part\_storage
仅在 ClickHouse Cloud 中可用。数据分区片段使用完整存储类型而非 packed
所需的最小 part 级别
## min\_level\_for\_wide\_part
将数据分区片段创建为 `Wide` 格式而非 `Compact` 格式所需的最小 part 级别。
## min\_marks\_to\_honor\_max\_concurrent\_queries
查询至少读取多少个标记时，才会应用 [max\_concurrent\_queries](#max_concurrent_queries) 设置。
查询仍会受到其他 `max_concurrent_queries` 设置的限制。
可能的值：
* 正整数。
* `0` — 已禁用 (`max_concurrent_queries` 限制不适用于任何查询) 。
**示例**
```xml theme={null}
10
```
## min\_merge\_bytes\_to\_use\_direct\_io
执行 合并 操作时，使用直接
I/O 访问存储磁盘所需的最小数据量。合并数据分区片段时，ClickHouse 会计算
所有待合并数据的总存储量。如果该总量超过
`min_merge_bytes_to_use_direct_io` 字节，ClickHouse 将通过直接 I/O 接口 (`O_DIRECT` 选项)
从存储磁盘读取和写入
数据。如果 `min_merge_bytes_to_use_direct_io = 0`，则禁用直接 I/O。
## min\_parts\_to\_merge\_at\_once
合并选择器一次可选中进行合并的最少数据分区片段数
(专家级设置，如果不了解其作用，请勿更改) 。
0 - 已禁用。适用于 Simple 和 StochasticSimple 合并选择器。
## min\_relative\_delay\_to\_close
与其他副本相比的最小延迟；达到该延迟后，将关闭、停止处理请求，并在 status check 期间不返回 Ok。
## min\_relative\_delay\_to\_measure
仅当绝对延迟不小于此值时，才计算副本的相对延迟。
## min\_relative\_delay\_to\_yield\_leadership
已废弃，无任何作用。
## min\_replicated\_logs\_to\_keep
即使这些记录已过时，也会在 ZooKeeper 日志中保留大约这么多条最新记录。它不会影响表的运行，仅用于在清理前诊断 ZooKeeper 日志。
可能的值：
* 任何正整数。
## min\_rows\_for\_compact\_part
已废弃，无任何作用。
## min\_rows\_for\_full\_part\_storage
仅在 ClickHouse Cloud 中可用。使用完整存储类型而非 packed 来存储数据分区片段时所需的最小行数
## min\_rows\_for\_wide\_part
创建 `Wide` 格式而不是 `Compact` 格式的数据分区片段所需的最少行数。
## min\_rows\_to\_fsync\_after\_merge
合并后对分片执行 fsync 所需的最小行数 (0 表示禁用)
## mutation\_workload
用于调节变更与其他工作负载之间的资源使用和共享方式。指定的值将作为此表后台变更的 `workload` 设置值使用。若未指定 (空字符串) ，则改用服务器设置 `mutation_workload`。
**另请参见**
* [工作负载调度](/zh/concepts/features/configuration/server-config/workload-scheduling)
## non\_replicated\_deduplication\_window
在非复制的
[MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree)表中，
用于存储最近插入的块的哈希值以进行重复检查的数量。
Possible values:
* 任意正整数。
* `0` (禁用去重) 。
这里使用了与复制表类似的去重机制 (请参见
[replicated\_deduplication\_window](#replicated_deduplication_window) 设置) 。
创建出的 parts 的哈希值会写入磁盘上的本地文件。
## notify\_newest\_block\_number
向 SharedJoin 或 SharedSet 通知最新块编号。仅在 ClickHouse Cloud 中可用。
## nullable\_serialization\_version
控制 `Nullable(T)` 列所使用的序列化方法。
可选值：
* basic — 使用 `Nullable(T)` 的标准序列化方式。
* allow\_sparse — 允许 `Nullable(T)` 使用稀疏编码。
## number\_of\_free\_entries\_in\_pool\_to\_execute\_mutation
当池中的空闲条目数少于指定数量时，不执行 part mutations。这样可以为常规合并保留空闲线程，并避免出现“parts 过多”错误。
可选值：
* 任意正整数。
**用法**
`number_of_free_entries_in_pool_to_execute_mutation` 设置的值
应小于 [background\_pool\_size](/zh/reference/settings/server-settings/settings#background_pool_size) 的值
* [background\_merges\_mutations\_concurrency\_ratio](/zh/reference/settings/server-settings/settings#background_merges_mutations_concurrency_ratio)。
否则，ClickHouse 将抛出异常。
## number\_of\_free\_entries\_in\_pool\_to\_execute\_optimize\_entire\_partition
当池中的空闲槽位数少于指定值时，不要
在后台执行针对整个分区的优化操作 (当设置
`min_age_to_force_merge_seconds` 并启用
`min_age_to_force_merge_on_partition_only` 时，会生成
此任务) 。这样可以为常规合并
保留空闲线程，并避免出现“parts 过多”。
可能的值：
* 正整数。
`number_of_free_entries_in_pool_to_execute_optimize_entire_partition`
设置的值应小于
[background\_pool\_size](/zh/reference/settings/server-settings/settings#background_pool_size)
* [background\_merges\_mutations\_concurrency\_ratio](/zh/reference/settings/server-settings/settings#background_merges_mutations_concurrency_ratio) 的值。
否则，ClickHouse 会抛出异常。
## number\_of\_free\_entries\_in\_pool\_to\_lower\_max\_size\_of\_merge
当池中 (或副本队列中) 的空闲条目数少于指定数量时，开始降低可处理的合并的最大大小
(或可放入队列的合并的最大大小) 。
这样可以让小型合并优先得到处理，避免长时间运行的合并
占满整个池。
可能的值：
* 任意正整数。
## number\_of\_mutations\_to\_delay
如果表中至少有
这么多尚未完成的变更，则会人为降低该表变更的执行速度。
设置为 0 时禁用
## number\_of\_mutations\_to\_throw
如果表中至少有这么多未完成的变更，则抛出“Too many mutations”异常。
设置为 0 时禁用
## number\_of\_partitions\_to\_consider\_for\_merge
仅在 ClickHouse Cloud 中可用。最多考虑前 N 个
分区进行合并。分区会按加权随机方式选取，权重
为该分区中可合并的数据分区片段数量。
## object\_serialization\_version
JSON 数据类型的序列化版本。出于兼容性考虑需要设置。
可能的值：
* `v1`
* `v2`
* `v3`
只有 `v3` 版本支持更改共享数据序列化版本。
## object\_shared\_data\_buckets\_for\_compact\_part
compact parts 中 JSON 共享数据 序列化的桶数量。与 `map_with_buckets` 和 `advanced` 共享数据 序列化配合使用。
允许的最大值为 256。
## object\_shared\_data\_buckets\_for\_wide\_part
用于指定 Wide parts 中 JSON 共享数据序列化的桶数量。与 `map_with_buckets` 和 `advanced` 共享数据序列化配合使用。
允许的最大值为 256。
## object\_shared\_data\_serialization\_version
JSON 数据类型中共享数据的序列化版本。
可能的值：
* `map` - 将共享数据存储为 `Map(String, String)`
* `map_with_buckets` - 将共享数据存储为多个独立的 `Map(String, String)` 列。使用桶可以提升从共享数据中读取单个路径的性能。
* `advanced` - 一种专为显著提升从共享数据中读取单个路径性能而设计的特殊共享数据序列化方式。
请注意，这种序列化会增加磁盘上共享数据的存储大小，因为它会存储大量额外信息。
`map_with_buckets` 和 `advanced` 序列化的桶数量由以下设置决定：
[object\_shared\_data\_buckets\_for\_compact\_part](#object_shared_data_buckets_for_compact_part)/[object\_shared\_data\_buckets\_for\_wide\_part](#object_shared_data_buckets_for_wide_part)。
## object\_shared\_data\_serialization\_version\_for\_zero\_level\_parts
此设置允许为插入期间创建的零级 parts 中
JSON 类型内部的共享数据指定不同的序列化版本。
建议不要对零级 parts 使用 `advanced` 共享数据序列化，因为这可能会显著增加
插入时间。
## old\_parts\_lifetime
存储非活动 parts 的时长 (以秒为单位) ，用于防止服务器意外重启时发生数据丢失。
可能的值：
* 任意正整数。
将多个 parts 合并成一个新的 part 后，ClickHouse 会将原始 parts 标记为非活动，并且仅在 `old_parts_lifetime` 秒后才删除它们。若非活动 parts 未被当前查询使用，即 part 的 `refcount` 为 1，则会被移除。
不会对新的 parts 调用 `fsync`，因此在一段时间内，新 parts 仅存在于服务器的 RAM (操作系统缓存) 中。如果服务器意外重启，新 parts 可能会丢失或损坏。为保护数据，非活动 parts 不会被立即删除。
启动期间，ClickHouse 会检查这些 parts 的完整性。如果 merged part 已损坏，ClickHouse 会将非活动 parts 恢复到活动列表中，之后再重新合并。随后，损坏的 part 会被重命名 (添加 `broken_` 前缀) 并移至 `detached` 文件夹中。如果 merged part 未损坏，则原始的非活动 parts 会被重命名 (添加 `ignored_` 前缀) 并移至 `detached` 文件夹中。
默认的 `dirty_expire_centisecs` 值 (Linux 内核设置) 为 30 秒 (写入数据仅保存在 RAM 中的最长时间) ，但在磁盘系统负载较高时，数据写入的时间可能会明显更晚。根据实验，`old_parts_lifetime` 取值为 480 秒，在这段时间内可确保新 part 被写入磁盘。
## optimize\_row\_order
控制是否在插入期间优化行顺序，以提升新插入表 parts 的
压缩效果。
仅对普通的 MergeTree-engine 表生效。对于专用的 MergeTree 引擎表
(例如 CollapsingMergeTree) 则不起作用。
MergeTree 表会 (可选地) 使用[压缩编解码器](/zh/reference/statements/create/table#column_compression_codec)进行压缩。
LZ4 和 ZSTD 等通用压缩编解码器在数据呈现出某种模式时，能够获得最高的压缩率。
相同值的长连续序列通常具有很好的压缩效果。
如果启用此设置，ClickHouse 会尝试以一种行顺序来存储新插入
parts 中的数据，从而尽量减少新表 part 各列中相同值连续段的数量。
换句话说，相同值连续段越少，通常意味着单个连续段越长，
压缩效果也越好。
寻找最优行顺序在计算上是不可行的 (NP-hard) 。
因此，ClickHouse 使用一种启发式方法来快速找到一种行顺序，
即使不是最优，也仍能比原始行顺序获得更好的压缩率。
用于寻找行顺序的启发式方法
通常可以自由打乱表 (或表 part) 中的行，
因为在 SQL 看来，行顺序不同但内容相同的表 (表 part) 是等价的。
当为表定义了主键时，这种自由打乱行的能力会受到限制。
在 ClickHouse 中，主键 `C1, C2, ..., CN` 要求
表中的行按列 `C1`, `C2`, ... `Cn` 排序 ([clustered index](https://en.wikipedia.org/wiki/Database_index#Clustered)) 。
因此，行只能在“等价类”内部进行重排，
也就是主键列值相同的那些行。
直观来看，高基数主键 (例如包含 `DateTime64` 时间戳列的主键)
会产生许多很小的等价类。相应地，低基数主键的表则会产生少量但
较大的等价类。没有主键的表则是一个极端情况，
即只有一个覆盖所有行的等价类。
等价类越少且越大，重新打乱行时的自由度就越高。
用于在每个等价类中寻找最佳行顺序的启发式方法，由 D. Lemire 和 O. Kaser 在
[Reordering columns for smaller indexes](https://doi.org/10.1016/j.ins.2011.02.002)
中提出，其核心是在每个等价类内
按非主键列基数的升序对行进行排序。
它分为三个步骤：
1. 根据主键列中的行值找出所有等价类。
2. 对于每个等价类，计算 (通常是估算)
非主键列的基数。
3. 对于每个等价类，按非主键列基数升序
对行进行排序。
如果启用，插入操作会带来额外的 CPU 开销，用于分析并
优化新数据的行顺序。根据数据特征不同，预计 INSERT 的耗时会增加 30-50%。
LZ4 或 ZSTD 的压缩率平均可提升 20-40%。
此设置最适用于没有主键或主键基数较低的表，
即仅包含少量不同主键值的表。
对于高基数主键，例如包含 `DateTime64` 类型
时间戳列的主键，通常无法从该设置中获益。
## part\_minmax\_index\_columns
选择每个 part 的 min-max 索引覆盖哪些列。每个值都会在前一个值的基础上额外启用一组列。
可选值：
* `partition_key_only` — 仅跟踪分区键列。
* `with_block_number_offset` — 分区键列，以及持久化的 `_block_number` 和 `_block_offset` 虚拟列。支持按这些列进行 part 级裁剪。
## part\_moves\_between\_shards\_delay\_seconds
在分片之间移动 parts 前后等待的时间。
## part\_moves\_between\_shards\_enable
用于在分片之间移动 parts 的 Experimental/未完成功能。不考虑
分片表达式。
## parts\_to\_delay\_insert
如果单个分区中的活动 parts 数量超过
`parts_to_delay_insert` 的值，`INSERT` 将被人为放慢。
可能的值：
* 任意正整数。
ClickHouse 会人为延长 `INSERT` 的执行时间 (添加“sleep”) ，以便
后台 合并 进程能够以快于新增 parts 的速度完成合并。
## parts\_to\_throw\_insert
如果单个分区中的活动 parts 数量超过
`parts_to_throw_insert` 的值，`INSERT` 会被中断，并抛出 `Too many
parts (N). Merges are processing significantly slower than inserts`
异常。
可能的值：
* 任意正整数。
为了获得 `SELECT` 查询的最佳性能，必须尽可能减少需要处理的 parts 数量，参见 [Merge Tree](/zh/resources/develop-contribute/introduction/architecture#merge-tree)。
在 23.6 版本之前，此设置的值为 300。你可以将其设置为更高的值，这会降低出现 `Too many parts`
错误的概率，但与此同时，`SELECT` 性能也可能会下降。另外，如果出现 合并 问题 (例如磁盘空间不足) ，相比使用原始值 300，你会更晚察觉到这个问题。
## prefer\_fetch\_merged\_part\_size\_threshold
如果 parts 的大小总和超过此阈值，并且自复制日志条目创建以来经过的时间大于
`prefer_fetch_merged_part_time_threshold`，则优先从某个副本拉取已合并的分片，
而不是在本地执行合并。这样可以加快耗时很长的合并操作。
可能的值：
* 任意正整数。
## prefer\_fetch\_merged\_part\_time\_threshold
如果自复制日志 (ClickHouse Keeper 或 ZooKeeper) 条目创建以来经过的时间超过此阈值，且 parts 的总大小大于 `prefer_fetch_merged_part_size_threshold`，则优先从副本拉取合并后的分片，而不是在本地执行合并。这样可以加快耗时很长的合并。
Possible values:
* 任意正整数。
## prewarm\_mark\_cache
如果为 true，则会在 insert、合并、拉取期间以及
server 启动时，通过在这些操作中将标记保存到标记缓存来预热标记缓存
## prewarm\_primary\_key\_cache
如果为 true，则会在插入、合并、拉取以及服务器启动时，通过将标记保存到标记缓存中来预热主索引缓存
## primary\_key\_compress\_block\_size
主键压缩块大小，即待压缩数据块的实际大小。
## primary\_key\_compression\_codec
主键使用的压缩编码。由于主键本身足够小且会被缓存，
因此默认使用 ZSTD(3) 压缩。
## primary\_key\_lazy\_load
首次使用时才将主键加载到内存中，
而不是在表初始化时加载。存在大量表时，
这可以节省内存。
## primary\_key\_ratio\_of\_unique\_prefix\_values\_to\_skip\_suffix\_columns
如果parts中主键某一列的值发生变化的次数至少达到这一比例，则跳过将后续列加载到内存中。这样可以避免加载主键中无用的列，从而节省内存使用。
## propagate\_types\_serialization\_versions\_to\_nested\_types
如果为 true，则像 `string_serialization_version` 这样的序列化版本会传递到 Array/Map/Nullable/JSON 等嵌套类型内部。如果禁用，则序列化版本只会对该类型的顶层列和 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：
```sql theme={null}
CREATE TABLE my_regular_table
(
`id` UInt64,
`s` String
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO my_regular_table
SELECT
number AS id,
number % 20 = 0 ? toString(number): '' AS s
FROM
numbers(10000000);
CREATE TABLE my_sparse_table
(
`id` UInt64,
`s` String
)
ENGINE = MergeTree
ORDER BY id
SETTINGS ratio_of_defaults_for_sparse_serialization = 0.95;
INSERT INTO my_sparse_table
SELECT
number,
number % 20 = 0 ? toString(number): ''
FROM
numbers(10000000);
```
请注意，`my_sparse_table` 中的 `s` 列在磁盘上占用的存储空间更小：
```sql theme={null}
SELECT table, name, data_compressed_bytes, data_uncompressed_bytes FROM system.columns
WHERE table LIKE 'my_%_table';
```
```response theme={null}
┌─table────────────┬─name─┬─data_compressed_bytes─┬─data_uncompressed_bytes─┐
│ my_regular_table │ id │ 37790741 │ 75488328 │
│ my_regular_table │ s │ 2451377 │ 12683106 │
│ my_sparse_table │ id │ 37790741 │ 75488328 │
│ my_sparse_table │ s │ 2283454 │ 9855751 │
└──────────────────┴──────┴───────────────────────┴─────────────────────────┘
```
你可以通过查看 `system.parts_columns` 表中的 `serialization_kind` 列，
确认某列是否使用了稀疏编码：
```sql theme={null}
SELECT column, serialization_kind FROM system.parts_columns
WHERE table LIKE 'my_sparse_table';
```
你可以查看 `s` 的哪些部分采用了稀疏序列化存储：
```response theme={null}
┌─column─┬─serialization_kind─┐
│ id │ Default │
│ s │ Default │
│ id │ Default │
│ s │ Default │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
│ id │ Default │
│ s │ Sparse │
└────────┴────────────────────┘
```
## reduce\_blocking\_parts\_sleep\_ms
仅在 ClickHouse Cloud 中可用。在未丢弃/替换任何范围后，再次尝试减少 blocking parts 之前的最短等待时间。较低的设置会更频繁地触发 background\_schedule\_pool 中的任务，从而在大规模集群中向 ZooKeeper 发出大量请求
## refresh\_parts\_interval
如果该值大于零，则会从底层文件系统刷新parts列表，以检查数据是否被底层更新。
只有当该表位于只读磁盘上时才能设置此项 (这意味着这是一个只读副本，而数据由另一个副本写入) 。
## refresh\_statistics\_interval
统计信息缓存的刷新时间间隔 (以秒为单位) 。如果设置为 0，则会禁用刷新。
## remote\_fs\_execute\_merges\_on\_single\_replica\_time\_threshold
当此设置的值大于零时，如果共享存储上存在已合并分片，则只有一个副本会立即开始
合并。
零拷贝复制尚未准备好用于生产环境。
在 ClickHouse 22.8 及更高版本中，零拷贝复制默认处于禁用状态。
不建议在生产环境中使用此功能。
可能的值：
* 任意正整数。
## remote\_fs\_zero\_copy\_path\_compatible\_mode
在转换过程中，以兼容模式运行 零拷贝。
## remote\_fs\_zero\_copy\_zookeeper\_path
用于存放零拷贝表级无关信息的 ZooKeeper 路径。
## remove\_empty\_parts
在通过生存时间 (TTL)、变更或 collapsing
合并算法清理后，删除空的 parts。
## remove\_rolled\_back\_parts\_immediately
这是一个用于尚未完成的 Experimental 功能的设置。
## remove\_unused\_patch\_parts
在后台移除已应用到所有活动 parts 的补丁分区片段。
## replace\_long\_file\_name\_to\_hash
如果列文件名过长 (超过 'max\_file\_name\_length'
字节) ，则将其替换为 SipHash128 哈希值
## replicated\_can\_become\_leader
如果为 true，此节点上的复制表副本将尝试成为
leader。
可能的值：
* `true`
* `false`
## replicated\_deduplication\_window
ClickHouse Keeper 为最近插入的这些块保存哈希和，
以检查重复项；该设置指定这类块的数量。
可能的值：
* 任意正整数。
* 0 (禁用去重)
`Insert` 命令会创建一个或多个块 (parts) 。对于
[插入去重](/zh/reference/engines/table-engines/mergetree-family/replication)，
在向复制表写入时，ClickHouse 会将所创建
parts 的哈希和写入 ClickHouse Keeper。哈希和只会为最近的
`replicated_deduplication_window` 个块保存。最旧的哈希和会
从 ClickHouse Keeper 中移除。
较大的 `replicated_deduplication_window` 值会减慢 `Inserts`
速度，因为需要比较更多条目。哈希和是根据
字段名称与类型的组合，以及已插入
分片 中的数据 (字节流) 计算得出的。
## replicated\_deduplication\_window\_for\_async\_inserts
ClickHouse Keeper 为检查重复项而存储哈希和时，所保留的最近异步插入块数量。
可能的值：
* 任意正整数。
* 0 (禁用 async\_inserts 的去重)
[异步插入](/zh/reference/settings/session-settings#async_insert) 命令会被缓存为一个或多个块 (parts) 。对于[插入去重](/zh/reference/engines/table-engines/mergetree-family/replication)，在写入复制表时，ClickHouse 会将每次插入的哈希和写入 ClickHouse Keeper。哈希和只会为最近的 `replicated_deduplication_window_for_async_inserts` 个块保存，最旧的哈希和会从 ClickHouse Keeper 中移除。
`replicated_deduplication_window_for_async_inserts` 的值越大，`Async Inserts` 就会越慢，因为需要比较更多条目。
哈希和是根据字段名称与类型的组合以及插入的数据 (字节流) 计算得出的。
## replicated\_deduplication\_window\_seconds
插入块的哈希值会在经过多少秒后
从 ClickHouse Keeper 中移除。
可能的值：
* 任意正整数。
与 [replicated\_deduplication\_window](#replicated_deduplication_window)
类似，`replicated_deduplication_window_seconds` 指定用于插入去重的块哈希值
应保留多长时间。早于
`replicated_deduplication_window_seconds` 的哈希值会从 ClickHouse Keeper 中移除，
即使它们的数量少于 ` replicated_deduplication_window`。
这里的时间是相对于最新一条记录的时间，而不是相对于实际时钟
时间。如果这是唯一的一条记录，它将永久保留。
## replicated\_deduplication\_window\_seconds\_for\_async\_inserts
异步插入的哈希和在多少秒后会从
ClickHouse Keeper 中移除。
Possible values:
* 任意正整数。
与 [replicated\_deduplication\_window\_for\_async\_inserts](#replicated_deduplication_window_for_async_inserts) 类似，
`replicated_deduplication_window_seconds_for_async_inserts` 指定用于异步插入去重的块哈希和
应保留多长时间。早于 `replicated_deduplication_window_seconds_for_async_inserts` 的哈希和
会从 ClickHouse Keeper 中移除，即使其数量少于
`replicated_deduplication_window_for_async_inserts`。
这里的时间是相对于最近一条记录的时间，而不是相对于实际时钟
时间。如果这是唯一的一条记录，则会永久保留。
## replicated\_fetches\_http\_connection\_timeout
已废弃，已无作用。
## replicated\_fetches\_http\_receive\_timeout
已废弃，不起任何作用。
## replicated\_fetches\_http\_send\_timeout
已废弃，不起任何作用。
## replicated\_fetches\_min\_part\_level
从其他副本拉取的最低 分片 级别。低于此阈值的 分片s 会被延后处理
(保留在复制队列中，并在每个调度周期重新评估，而不是被永久跳过) 。
将其设为 1 可延后拉取 0 级 (未合并) 的 分片s，从而在高强度摄取期间降低复制开销。
默认值：0 (无论级别如何，都会拉取所有 分片s) 。
## replicated\_fetches\_min\_part\_level\_timeout\_seconds
级别低于 `replicated_fetches_min_part_level` 的 分片 在超过该秒数后仍会被强制拉取。
使用 0 可禁用该超时 (低于最小级别的 分片s 将被无限期延后，直到被合并) 。
默认值：300 (5 分钟后强制拉取) 。
## replicated\_max\_mutations\_in\_one\_entry
可合并并在一个 MUTATE\_PART 条目中执行的变更命令最大数量
(0 表示不受限制)
## replicated\_max\_parallel\_fetches
已废弃，无任何作用。
## replicated\_max\_parallel\_fetches\_for\_host
已废弃，不起任何作用。
## replicated\_max\_parallel\_fetches\_for\_table
已废弃，无任何作用。
## replicated\_max\_parallel\_sends
已废弃，无任何作用。
## replicated\_max\_parallel\_sends\_for\_table
已废弃，没有任何作用。
## replicated\_max\_ratio\_of\_wrong\_parts
如果错误 parts 与 parts 总数的比率低于该值，
则允许启动。
可能的值：
* Float，0.0 - 1.0
## search\_orphaned\_parts\_disks
ClickHouse 会在执行任何 ATTACH 或 CREATE 表操作时扫描所有磁盘上的孤立parts，
以避免遗漏位于未定义 (即未包含在策略中) 磁盘上的parts。
孤立parts可能源于潜在不安全的存储重新配置，例如某个磁盘被从存储策略中排除。
此设置会根据磁盘特征限制搜索的磁盘范围。
可能的值：
* 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 列都会拥有各自独立的 offset 文件，名称中的点不再具有特殊
语义，同时标量列也可以与共享相同前缀的点分 Array 列共存
(例如 `n UInt32` 与 `n.a Array(String)` 可同时存在) 。该设置在表创建后不可更改。
## shared\_merge\_tree\_activate\_coordinated\_merges\_tasks
启用对协调合并任务的重新调度。即使在
shared\_merge\_tree\_enable\_coordinated\_merges=0 时，这也可能很有用，因为它会填充合并协调器的
统计信息，并有助于冷启动。
## shared\_merge\_tree\_create\_per\_replica\_metadata\_nodes
启用在 ZooKeeper 中为每个副本创建 /metadata 和 /columns 节点。
仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_disable\_merges\_and\_mutations\_assignment
停止为 shared merge tree 分配合并和变更任务。仅在 ClickHouse
Cloud 中可用
## shared\_merge\_tree\_empty\_partition\_lifetime
分区在不包含任何 parts 时，会在 Keeper 中保留多少秒。
## shared\_merge\_tree\_enable\_automatic\_empty\_partitions\_cleanup
启用对空分区对应的 Keeper 条目的清理。
## shared\_merge\_tree\_enable\_coordinated\_merges
启用协调合并策略
启用在 Keeper 中向虚拟 parts 写入属性并提交块
## shared\_merge\_tree\_enable\_outdated\_parts\_check
启用过期parts检查。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_idle\_parts\_update\_seconds
shared merge tree 中在未由 ZooKeeper watch 触发的情况下进行 parts 更新的时间间隔 (秒) 。仅在 ClickHouse Cloud
中可用
## shared\_merge\_tree\_initial\_parts\_update\_backoff\_ms
parts 更新的初始退避时间。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_interserver\_http\_connection\_timeout\_ms
服务器间 HTTP 连接的超时时间。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_interserver\_http\_timeout\_ms
用于服务器间 HTTP 通信的超时时间。仅在 ClickHouse
Cloud 中可用
## shared\_merge\_tree\_leader\_update\_period\_random\_add\_seconds
为避免惊群效应，向
shared\_merge\_tree\_leader\_update\_period 额外添加一个从 0 到 x 秒均匀分布的值。仅在 ClickHouse Cloud
中可用
## shared\_merge\_tree\_leader\_update\_period\_seconds
重新检查 parts 更新 leader 状态的最大周期。仅在
ClickHouse Cloud
中可用
## shared\_merge\_tree\_max\_outdated\_parts\_to\_process\_at\_once
leader 在一次 HTTP 请求中尝试确认可删除的过期分区片段的最大数量。仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_max\_parts\_update\_backoff\_ms
parts 更新的最大退避时间。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_max\_parts\_update\_leaders\_in\_total
parts 更新 leader 的最大数量。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_max\_parts\_update\_leaders\_per\_az
parts 更新 leader 的数量上限。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_max\_replicas\_for\_parts\_deletion
参与删除 parts (killer 线程) 的最大副本数。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_max\_replicas\_to\_merge\_parts\_for\_each\_parts\_range
尝试分配可能存在冲突的合并任务的最大副本数 (可
避免在合并任务分配中产生冗余冲突) 。0 表示禁用。仅
在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_max\_suspicious\_broken\_parts
SMT 的损坏 parts 最大数量；若超过该值，则禁止自动 detach。
## shared\_merge\_tree\_max\_suspicious\_broken\_parts\_bytes
SMT 中所有损坏 parts 的最大总大小；若超过该值，将禁止自动 detach。
## shared\_merge\_tree\_memo\_ids\_remove\_timeout\_seconds
为避免在 insert 重试期间执行错误操作，insert memoization ID 会保留多长时间。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_merge\_coordinator\_election\_check\_period\_ms
合并协调器 选举线程的运行间隔时间
## shared\_merge\_tree\_merge\_coordinator\_factor
协调器线程延迟的时间调整系数
## shared\_merge\_tree\_merge\_coordinator\_fetch\_fresh\_metadata\_period\_ms
合并协调器 与 ZooKeeper 同步以获取最新元数据的频率
## shared\_merge\_tree\_merge\_coordinator\_max\_merge\_request\_size
协调器一次可向 MergerMutator 请求的合并数量
## shared\_merge\_tree\_merge\_coordinator\_max\_period\_ms
合并协调器线程两次运行之间的最大时间间隔
## shared\_merge\_tree\_merge\_coordinator\_merges\_prepare\_count
合并协调器应准备并分发给各个工作线程的 merge 条目数量。
设置为 'auto' 时，该值等于单个副本允许的最大 merge 任务数乘以活跃副本数。
## shared\_merge\_tree\_merge\_coordinator\_min\_period\_ms
merge coordinator 线程两次运行的最小间隔时间
## shared\_merge\_tree\_merge\_worker\_fast\_timeout\_ms
合并工作线程在立即操作后如需更新其状态时使用的超时时间
## shared\_merge\_tree\_merge\_worker\_regular\_timeout\_ms
合并工作线程两次运行之间的间隔时间
## shared\_merge\_tree\_outdated\_parts\_group\_size
指定在清理过期 parts 时，同一 rendezvous 哈希组中包含的副本数量。
仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_partitions\_hint\_ratio\_to\_reload\_merge\_pred\_for\_mutations
当 `/` 的比率高于该设置值时，会在 merge/mutate 选择任务中重新加载 merge 谓词。仅在 ClickHouse Cloud
中可用
## shared\_merge\_tree\_parts\_load\_batch\_size
一次调度的拉取 parts 元数据作业数量。仅在
ClickHouse Cloud
中可用
## shared\_merge\_tree\_postpone\_next\_merge\_for\_locally\_merged\_parts\_ms
在不启动包含此 part 的新合并的情况下，保留本地已合并 part 的时间。
这会让其他副本有机会拉取该 part，并开始这次合并。
仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_postpone\_next\_merge\_for\_locally\_merged\_parts\_rows\_threshold
本地合并完成后，若 part 的大小 (按行数计) 达到此最小值，则会推迟为其分配下一次合并。仅在 ClickHouse Cloud 中可用。
## shared\_merge\_tree\_range\_for\_merge\_window\_size
在不启动包含该分片的新 merge 的情况下，本地已合并分片的保留时间。
这让其他副本有机会拉取该分片并启动这次 merge。
仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_read\_virtual\_parts\_from\_leader
在可能的情况下，从 leader 读取 virtual parts。仅在 ClickHouse
Cloud 中可用
## shared\_merge\_tree\_replica\_set\_max\_lifetime\_seconds
副本在后台尝试更新副本集的频率。下一次运行的时间会在 \[0, value] 秒范围内按均匀分布随机抖动。例外情况：value = 0 不遵循这一约定；实现中会强制使用最小 200 毫秒，因此下一次运行的时间会在 \[0, 200] 毫秒范围内随机抖动。
## shared\_merge\_tree\_try\_fetch\_part\_in\_memory\_data\_from\_replicas
如果启用，所有副本都会尝试从其他已存在这些数据的副本拉取 part 的内存数据 (如主键、分区信息等) 。
## shared\_merge\_tree\_update\_replica\_flags\_delay\_ms
副本按后台调度尝试重新加载其标志的频率。
## shared\_merge\_tree\_use\_metadata\_hints\_cache
启用从其他副本的内存缓存中请求 FS 缓存提示。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_use\_outdated\_parts\_compact\_format
对过期parts使用紧凑格式：可降低 Keeper 负载，并改进
过期parts的处理。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_use\_too\_many\_parts\_count\_from\_virtual\_parts
如果启用，parts 过多计数器将基于 Keeper 中的共享数据，而不是
本地副本状态。仅在 ClickHouse Cloud 中可用
## shared\_merge\_tree\_use\_zookeeper\_connection\_pool
如果启用，SharedMergeTree 将使用服务器级连接池中的一个 ZooKeeper 会话。
## shared\_merge\_tree\_virtual\_parts\_discovery\_batch
每个批次应打包多少个分区发现
## simultaneous\_parts\_removal\_limit
如果存在大量过期分区片段，清理线程会在一次迭代中尝试最多删除
`simultaneous_parts_removal_limit` 个 parts。
将 `simultaneous_parts_removal_limit` 设置为 `0` 表示不受限制。
## sleep\_before\_commit\_local\_part\_in\_replicated\_table\_ms
仅用于测试。请勿更改。
## sleep\_before\_loading\_outdated\_parts\_ms
仅用于测试。请勿更改。
## storage\_policy
存储磁盘策略的名称
## string\_serialization\_version
控制顶层 `String` 列的序列化格式。
此设置仅在 `serialization_info_version` 设为 "with\_types" 时生效。
设为 `with_size_stream` 时，顶层 `String` 列会通过单独的
`.size` 子列存储字符串长度，而不是内联存储。这样可以提供真正的 `.size`
子列，并提高压缩效率。
嵌套的 `String` 类型 (例如在 `Nullable`、`LowCardinality`、`Array` 或 `Map` 内部)
不受影响，但出现在 `Tuple` 中时除外。
可选值：
* `single_stream` — 使用内联大小信息的标准序列化格式。
* `with_size_stream` — 对顶层 `String` 列使用单独的大小流。
## table\_disk
这是表级磁盘，path/endpoint 应指向表数据，而不是
数据库数据。只能用于 s3\_plain/s3\_plain\_rewritable/web。
## table\_readonly
如果设置为 true，则该表处于只读模式。任何插入数据或修改表的尝试都会失败。
## temporary\_directories\_lifetime
tmp\_ 目录应保留多少秒。你不应调低该值，
因为如果此设置的值过低，merge 和 mutation 操作可能无法正常进行。
## try\_fetch\_recompressed\_part\_timeout
开始执行重压缩合并前的超时时间 (以秒为单位) 。在这段时间内，
ClickHouse 会尝试从被分配执行此次重压缩合并的副本中拉取
重压缩后的分片。
在大多数情况下，重压缩速度较慢，因此在超时到达之前，我们不会开始
重压缩合并，而是尝试从被分配执行此次重压缩合并的
副本中拉取重压缩后的分片。
可能的值：
* 任意正整数。
## ttl\_only\_drop\_parts
控制在 MergeTree 表中，当某个数据 part 中的所有
行都根据其 `TTL` 设置过期时，是否直接删除整个数据 part。
当 `ttl_only_drop_parts` 被禁用时 (默认) ，只会删除
那些根据其 `TTL` 设置已过期的行。
当 `ttl_only_drop_parts` 被启用时，如果某个数据 part 中的所有
行都根据其 `TTL` 设置过期，则会删除整个数据 part。
## use\_adaptive\_write\_buffer\_for\_dynamic\_subcolumns
允许在写入动态子列时使用自适应写入缓冲区，以降低内存占用
## use\_async\_block\_ids\_cache
如果为 `true`，则会缓存异步插入的哈希和。
可能的值：
* `true`
* `false`
一个包含多个异步插入的块会生成多个哈希和。
当其中部分插入重复时，Keeper 在一次 RPC 中只会返回一个
重复的哈希和，这会导致不必要的 RPC 重试。
此缓存会监听 Keeper 中的哈希和路径。如果在
Keeper 中监听到更新，缓存会尽快更新，以便我们能够在
内存中过滤掉重复的插入。
## use\_compact\_variant\_discriminators\_serialization
为 Variant
数据类型中判别符的二进制序列化启用紧凑模式。
当大多数情况下仅有一种变体，或存在大量 NULL 值时，
此模式可显著减少在 parts 中存储判别符所需的内存。
## use\_const\_adaptive\_granularity
始终对整个分片使用固定粒度。这样可以在内存中压缩索引粒度值。在表较窄的超大规模工作负载中，这会很有帮助。
## use\_metadata\_cache
已废弃设置，不起任何作用。
## use\_minimalistic\_checksums\_in\_zookeeper
在 ZooKeeper 中，对分片校验和使用更小的格式 (数十字节) ，而不是
常规格式 (数十 KB) 。启用前，请先确认所有副本都支持
新格式。
ZooKeeper 中数据分区片段头的存储方式。启用后，ZooKeeper
存储的数据量会更少。详情请参见[此处](/zh/reference/settings/server-settings/settings#use_minimalistic_part_header_in_zookeeper)。
## use\_primary\_key\_cache
使用主索引缓存，
而不是将所有索引都保存在内存中。对非常大的表很有用
## vertical\_merge\_algorithm\_min\_bytes\_to\_activate
在 merging 的 parts 中，用于激活垂直 merge 算法的最小 (近似) 未压缩大小 (以字节为单位) 。
## vertical\_merge\_algorithm\_min\_columns\_to\_activate
启用 Vertical merge 算法所需的非主键列最小数量。
## vertical\_merge\_algorithm\_min\_rows\_to\_activate
用于激活 Vertical merge algorithm 的合并 parts 的最小行数总和 (近似值) 。
## vertical\_merge\_optimize\_lightweight\_delete
如果为 true，则在垂直合并时会对轻量级删除进行优化。
## vertical\_merge\_optimize\_ttl\_delete
如果为 true，则会在垂直合并期间优化基于行的 TTL 删除。无需强制使用水平合并，
而是对 TTL 过滤器进行计算，并将其传递给合并算法，由后者在行源中设置跳过标志。
## vertical\_merge\_remote\_filesystem\_prefetch
如果为 true，则在合并期间会为下一列预拉取远程文件系统中的数据
## wait\_for\_unique\_parts\_send\_before\_shutdown\_ms
关闭前，表会等待指定时间，以便其他副本拉取仅存在于当前副本上的唯一 parts
(0 表示
禁用) 。
## write\_ahead\_log\_bytes\_to\_fsync
已废弃设置，无任何作用。
## write\_ahead\_log\_interval\_ms\_to\_fsync
已废弃，无任何作用。
## write\_ahead\_log\_max\_bytes
已废弃，无任何作用。
## write\_final\_mark
已废弃，不起任何作用。
## write\_marks\_for\_substreams\_in\_compact\_parts
启用后，在 Compact parts 中会按每个子流而不是按每列写入标记。
这样可以高效地从数据分区片段中读取单独的子列。
例如，列 `t Tuple(a String, b UInt32, c Array(Nullable(UInt32)))` 会被序列化为以下子流：
* `t.a`：元组元素 `a` 的 String 数据
* `t.b`：元组元素 `b` 的 UInt32 数据
* `t.c.size0`：元组元素 `c` 的数组大小
* `t.c.null`：元组元素 `c` 中嵌套数组元素的 null map
* `t.c`：元组元素 `c` 中嵌套数组元素的 UInt32 数据
启用此设置后，我们会为这 5 个子流分别写入一个标记。这意味着在需要时，我们可以从粒度中分别读取每个子流的数据。例如，如果要读取子列 `t.c`，则只会读取
子流 `t.c.size0`、`t.c.null` 和 `t.c` 的数据，而不会读取子流 `t.a` 和 `t.b` 的数据。禁用此设置时，
只会为顶层列 `t` 写入一个标记，这意味着即使只需要某些子流的数据，也始终会从粒度中读取整列数据。
## zero\_copy\_concurrent\_part\_removal\_max\_postpone\_ratio
为了获得更小的独立 ranges，可延后删除的顶层 parts 的最大百分比。
建议不要更改。
## zero\_copy\_concurrent\_part\_removal\_max\_split\_times
将相互独立的过期分区片段范围拆分为
更小子范围时的最大递归深度。建议不要修改。
## zero\_copy\_merge\_mutation\_min\_parts\_size\_sleep\_before\_lock
如果启用了零拷贝复制，则在尝试加锁前，会根据用于合并或变更的 parts 大小随机休眠一段时间
## zero\_copy\_merge\_mutation\_min\_parts\_size\_sleep\_no\_scale\_before\_lock
如果启用了 zero copy replication，则在尝试为 merge 或变更操作加锁之前，
会先随机休眠一段时间，最长可达 500ms。
## zookeeper\_session\_expiration\_check\_period
ZooKeeper 会话过期检查周期 (以秒为单位) 。
可能的值：
* 任意正整数。