> ## 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.
# 其他 MergeTree 表设置
> 属于自动生成的“其他”分组的 ClickHouse MergeTree 表设置。
export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
return
类型
{type}
默认值
{default_value}
{changeable_without_restart &&
无需重启即可更改
}
{changeable_without_restart &&
{changeable_without_restart}
}
;
};
export const ExperimentalBadge = () => {
return ;
};
这些设置可在 [system.merge\_tree\_settings](/docs/zh/reference/system-tables/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` (默认) ：重建受 `ALTER` 命令中该列影响的所有次级索引。
* `throw`：通过抛出异常，阻止对受**显式**次级索引覆盖的列执行任何 `ALTER`。隐式索引不受此限制影响，仍会被重建。
* `drop`：删除依赖的次级索引。新的 parts 将不再包含这些索引，需要使用 `MATERIALIZE INDEX` 重新创建。
* `compatibility`：与原始行为一致：对 `ALTER ... MODIFY COLUMN` 使用 `throw`，对 `ALTER ... UPDATE/DELETE` 使用 `rebuild`。
* `ignore`：仅供高级用户使用。它会使索引保持不一致状态，从而可能导致错误的查询结果。
## apply\_patches\_on\_merge
如果为 true，则在合并过程中应用补丁parts
## assign\_part\_uuids
启用后，每个新的数据分片都会被分配一个唯一的分片标识符。
启用前，请检查所有副本都支持 UUID v4。
## auto\_statistics\_types
以逗号分隔的统计类型列表，用于在所有适用列上自动计算。
支持的统计类型：basic、tdigest、countmin、uniq、uniq\_v2。
`minmax` 统计类型已弃用：它是 `basic` 的子集，应改用 `basic`。
## background\_task\_preferred\_step\_execution\_time\_ms
合并或变更中单个步骤的目标执行时间。如果
某个步骤耗时更长，则可能会超过该时间
## clean\_deleted\_rows
已废弃设置，无任何作用。
## clone\_replica\_zookeeper\_create\_get\_part\_batch\_size
用于克隆副本时的 ZooKeeper multi-create get-part 请求批次大小。
## compatibility\_allow\_sampling\_expression\_not\_in\_primary\_key
允许创建抽样表达式不在主键中的表。只有为了向后兼容，在临时允许服务器使用不正确的表运行时，才需要启用此设置。
## compute\_exact\_num\_defaults\_for\_sparse\_columns
在插入和
合并期间，按列精确计算默认值的数量，而不是使用成本更低、用于决定是否采用稀疏
序列化的采样估算。`optimize_trivial_count_with_sparsity_filter`
需要此设置，因为它会使用持久化的 `num_defaults` 计数器 (`Nullable` 列
还需要设置 `nullable_serialization_version = 'allow_sparse'`) 。
保持禁用可使插入/合并速度与之前一样快；启用后，
每个符合稀疏条件的列都会额外增加一次 O(rows) 扫描。
## deduplicate\_merge\_projection\_mode
是否允许为使用非经典 MergeTree 的表创建投影，
也就是不属于 (Replicated、Shared) MergeTree 的表。`ignore` 选项纯粹是为了
兼容性，但可能会导致错误结果。否则，如果允许，
则在合并投影时需要执行什么操作：`drop` 还是 `rebuild`。因此，经典
MergeTree 会忽略此设置。它也会控制 `OPTIMIZE DEDUPLICATE`，
但对 MergeTree 家族的所有成员都生效。与
选项 `lightweight_mutation_projection_mode` 类似，它也是 分片 级别的。
可能的值：
* `ignore`
* `throw`
* `drop`
* `rebuild`
## deduplication\_hashes\_cache\_update\_wait\_ms
每次插入迭代在再次检查内存中的 `deduplication_hashes` 缓存、确认是否存在已插入块之前，会等待其刷新到
更新的版本。该缓存镜像了 ClickHouse Keeper 中的
`deduplication_hashes` 目录，因此插入操作无需与
Keeper 往返通信即可检测重复项。
## default\_compression\_codec
指定当表定义中未为某个列指定压缩编解码器时，默认使用的压缩编解码器。
列的压缩编解码器选择顺序如下：
1. 在表定义中为该列指定的压缩编解码器
2. 在 `default_compression_codec` 中定义的压缩编解码器 (此设置)
3. 在 `compression` 设置中定义的默认压缩编解码器
默认值：空字符串 (未定义) 。
## disk
存储 磁盘 的名称。可以指定 磁盘 来代替 存储策略。
## 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
当此设置的值大于零时，只会有一个副本立即开始合并，其他副本则最多等待这么长时间来下载合并结果，而不是在本地执行合并。如果选定的副本未能在这段时间内完成合并，则会回退为标准行为。
可能的值：
* 任意正整数。
## finished\_mutations\_to\_keep
要保留多少条已完成的变更记录。如果为零，则保留
全部记录。
## force\_read\_through\_cache\_for\_merges
强制合并操作通过文件系统缓存读取
## initialization\_retry\_period
表初始化的重试间隔，单位为秒。
## kill\_threads
已废弃，不起作用。
## lightweight\_mutation\_projection\_mode
默认情况下，轻量级删除 `DELETE` 不适用于带有投影的表。
这是因为投影中的行可能会受到 `DELETE` 操作的影响。
因此，默认值是 `throw`。不过，此选项可以改变这种行为。
当取值为 `drop` 或 `rebuild` 时，删除操作可与投影配合使用。
`drop` 会删除投影，因此当前查询可能会更快，因为投影会被删除；
但后续查询可能会变慢，因为不再有已附加的投影。`rebuild` 会重建
投影，这可能会影响当前查询的性能，但可能会加快后续查询。
这样做的一个好处是，这些选项只会在 分片 级别生效，这意味着未被触及的分片中的投影
会保持不变，而不会触发
drop 或 rebuild 之类的操作。
可选值：
* `throw`
* `drop`
* `rebuild`
## load\_existing\_rows\_count\_for\_old\_parts
如果启用此设置，并同时启用 [exclude\_deleted\_rows\_for\_part\_size\_in\_merge](/docs/zh/reference/settings/merge-tree-settings/exclude#exclude_deleted_rows_for_part_size_in_merge)，
系统会在表启动时计算现有数据parts中的已删除行数。请注意，这可能会减慢表启动时的加载速度。
可能的值：
* `true`
* `false`
**另请参见**
* [exclude\_deleted\_rows\_for\_part\_size\_in\_merge](/docs/zh/reference/settings/merge-tree-settings/exclude#exclude_deleted_rows_for_part_size_in_merge) 设置
## lock\_acquire\_timeout\_for\_background\_operations
对于合并、变更等后台操作，获取表锁失败前会等待多少秒。
## mutation\_workload
用于调节资源如何在变更与其他工作负载之间分配和共享。指定的值将作为该表后台变更的 `workload` 设置值使用。若未指定 (空字符串) ，则改用服务器设置 `mutation_workload`。
**另请参见**
* [Workload Scheduling](/docs/zh/concepts/features/configuration/server-config/workload-scheduling)
## non\_replicated\_deduplication\_window
在非复制表
[MergeTree](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree) 表中，
为最近插入的若干个块保存哈希值，以检查重复数据。
可能的值：
* 任意正整数。
* `0` (禁用去重) 。
这里使用了与复制表类似的去重机制 (请参见
[replicated\_deduplication\_window](/docs/zh/reference/settings/merge-tree-settings/replicated-deduplication-window#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`，因此在一段时间内，新 分片 只存在于
服务器的 RAM (操作系统缓存) 中。如果服务器意外重启，新
分片 可能会丢失或损坏。为保护数据，非活跃 分片 不会被立即删除。
启动期间，ClickHouse 会检查各个 分片 的完整性。如果合并后的
分片 已损坏，ClickHouse 会将非活跃 分片 恢复到活跃列表中，
随后再次对其进行合并。然后，损坏的 分片 会被重命名 (添加 `broken_`
前缀) 并移至 `detached` 文件夹中。如果合并后的 分片
没有损坏，则原始的非活跃 分片 会被重命名 (添加 `ignored_`
前缀) 并移至 `detached` 文件夹中。
默认的 `dirty_expire_centisecs` 值 (一个 Linux 内核设置) 是 30
秒 (已写入数据仅存储在 RAM 中的最长时间) ，但在
磁盘系统负载较高时，数据实际写入的时间可能会晚得多。根据实验结果，
`old_parts_lifetime` 选择了 480 秒，这段时间内可以保证
新的 分片 被写入磁盘。
## optimize\_row\_order
控制是否在插入期间优化行顺序，以提高新插入表分片的
可压缩性。
仅对普通 MergeTree 引擎表生效。对于
专用的 MergeTree 引擎表 (例如 CollapsingMergeTree) 则无效。
MergeTree 表会 (可选地) 使用[压缩编解码器](/docs/zh/reference/statements/create/table#column_compression_codec)进行压缩。
如果数据呈现出某些模式，LZ4 和 ZSTD 等通用压缩编解码器
可以达到更高的压缩率。相同值的长连续段通常
具有很好的压缩效果。
如果启用此设置，ClickHouse 会尝试以一种行顺序将数据存储到新
插入的分片中，从而尽量减少新表分片各列中相同值连续段的数量。
换句话说，相同值连续段的数量越少，就意味着单个连续段
越长，压缩效果也越好。
找到最优行顺序在计算上是不可行的 (NP-hard) 。
因此，ClickHouse 使用启发式方法快速找到一种行顺序，
虽然不是最优，但仍能比原始行顺序获得更好的压缩率。
查找行顺序的启发式方法
通常，可以自由打乱表 (或表分片) 的行顺序，
因为在 SQL 看来，同一张表 (表分片) 即使行顺序不同，
也是等价的。
当为表定义了主键时，这种打乱行顺序的自由会受到限制。
在 ClickHouse 中，主键 `C1, C2, ..., CN` 会强制
表中的行按列 `C1`, `C2`, ... `Cn` 排序 ([聚簇索引](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` 类型时间戳列的主键) ，
预计无法从此设置中受益。
## packed\_skip\_index\_max\_bytes
.idx2 \/ .mrk2 布局。该决定会在写入时按子流分别作出。"}]}]} />
低于该阈值 (即序列化后的磁盘字节数，也就是子流经过压缩和哈希
事件链之后的大小) 的 skip-index 子流，不会写入单独的 `skp_idx_.idx2` / `.mrk2`
文件，而是会打包到每个 分片 的单个 `skp_idx.packed`
归档中。超过该值的子流则保留旧版的逐文件布局。该决定会在写入时按子流独立
作出，因此单个 分片 可以同时包含已打包的小索引
(例如 `minmax`) 以及仍按文件单独存放的大索引 (例如较重的 `bloom_filter`) 。设为 0
可完全禁用打包 (默认值) 。
每个 skip-index 子流实际上都由一个数据文件和一个标记文件组成；在作出是否
落盘的决定之前，这两个文件都会先在内存中缓冲直到达到该阈值。因此，写入时的峰值内存占用
会随 `2 * packed_skip_index_max_bytes * (number of substreams that stay
below the threshold)` 成比例增长。
此设置不支持全文索引，因此全文索引永远不会被打包。
当表上定义了许多 skip 索引时 (例如
使用 `add_minmax_index_for_numeric_columns`) ，打包可以减少 inode 压力。
该磁盘格式是自描述的：读取器会检测 `skp_idx.packed`，并透明地从中读取已打包的
子流。更改此设置只会影响新写入的 分片；
现有 分片 会保留其写入时所使用的布局。
## part\_minmax\_index\_columns
选择每个分片的 min-max 索引覆盖哪些列。每个取值都会在前一个取值的基础上额外启用一组列。
可选值：
* `partition_key_only` — 仅跟踪分区键列。
* `with_block_number_offset` — 分区键列，以及持久化的 `_block_number` 和 `_block_offset` 虚拟列。启用基于这些列的分片级裁剪。
## propagate\_types\_serialization\_versions\_to\_nested\_types
如果为 true，则像 string\_serialization\_version 这样的序列化版本会传播到 Array/Map/Nullable/JSON 等嵌套类型内部。如果禁用，该序列化版本则只会对该类型的顶层列和 Tuple el 生效
## ratio\_of\_defaults\_for\_sparse\_serialization
一列中 *default* 值数量与 *all* 值数量之间的最小比率。
设置此值后，该列将使用稀疏
序列化进行存储。
如果某一列是稀疏的 (大多数值为零) ，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 中可用。在未丢弃/替换任何范围后，再次尝试减少阻塞 parts 之前的最短等待时间。将此设置调低会频繁触发 background\_schedule\_pool 中的任务，从而在大规模集群中向 ZooKeeper 发起大量请求
## replace\_long\_file\_name\_to\_hash
如果列文件名过长 (超过 'max\_file\_name\_length'
字节) ，则替换为 SipHash128
## replicated\_can\_become\_leader
如果为 true，则此节点上的复制表副本会尝试成为
leader。
可能的值：
* `true`
* `false`
## search\_orphaned\_parts\_disks
ClickHouse 在执行任何 ATTACH 或 CREATE 表操作时，都会扫描所有磁盘以查找孤立的 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 结构的一部分：它们在磁盘上共享同一个偏移文件 (例如 n.size0) ，
并且在 INSERT 时会校验它们的数组大小是否相同。
禁用时，每个 Array 列都会拥有各自独立的偏移文件，带点名称不再具有特殊
语义，而且标量列可以与共享相同前缀、名称中带点的 Array 列共存
(例如 n UInt32 与 n.a Array(String) 同时存在) 。此设置在创建表后不可更改。
## simultaneous\_parts\_removal\_limit
如果过期parts较多，清理线程会在一次迭代中尝试最多删除
`simultaneous_parts_removal_limit` 个过期parts。
将 `simultaneous_parts_removal_limit` 设置为 `0` 表示不受限制。
## 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` 列使用单独的大小流。
## temporary\_directories\_lifetime
tmp\_ 目录会保留多少秒。不要调低此值，
因为该设置值过低时，merges 和 变更 可能无法正常工作。
## try\_fetch\_recompressed\_part\_timeout
在开始带重压缩的 merge 之前的超时时间 (以秒为单位) 。在这段时间内，ClickHouse 会尝试从被分配执行此次带重压缩 merge 的副本拉取重压缩后的分片。
在大多数情况下，重压缩速度较慢，因此在超时到期前，我们不会开始带重压缩的 merge，而是会尝试从被分配执行此次带重压缩 merge 的副本拉取重压缩后的分片。
可选值：
* 任意正整数。
## ttl\_only\_drop\_parts
控制在 MergeTree 表中，当某个数据parts内的所有
行都已根据其 `TTL` 设置过期时，是否直接删除整个数据parts。
当 `ttl_only_drop_parts` 被禁用时 (默认) ，只会移除那些
已根据其 `TTL` 设置过期的行。
当 `ttl_only_drop_parts` 被启用时，如果某个数据parts内的所有
行都已根据其 `TTL` 设置过期，则会删除整个数据parts。
## wait\_for\_unique\_parts\_send\_before\_shutdown\_ms
关闭前，表会等待一段所需时间，让唯一的 parts
(仅存在于当前副本上) 被其他副本拉取 (0 表示
禁用) 。
## zookeeper\_session\_expiration\_check\_period
ZooKeeper 会话过期检查周期，单位为秒。
可能的值：
* 任意正整数。