其他 MergeTree 表设置 - ClickHouse Documentation

这些设置可在 system.merge_tree_settings 中查看，且由 ClickHouse 源代码自动生成。

adaptive_write_buffer_initial_size

自适应写入缓冲区的初始大小

add_implicit_sign_column_constraint_for_collapsing_engine

如果为 true，则会为 CollapsingMergeTree 或 VersionedCollapsingMergeTree 表的 sign 列添加隐式约束，仅允许使用有效值 (1 和 -1) 。

alter_column_secondary_index_mode

配置是否允许执行修改受次级索引覆盖列的 ALTER 命令，以及在允许时应采取的操作。默认情况下，此类 ALTER 命令是允许的，并且会重建相关索引。可能的值：

rebuild (默认) ：重建受 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

指定当表定义中未为某个列指定压缩编解码器时，默认使用的压缩编解码器。列的压缩编解码器选择顺序如下：

在表定义中为该列指定的压缩编解码器
在 default_compression_codec 中定义的压缩编解码器 (此设置)
在 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，系统会在表启动时计算现有数据parts中的已删除行数。请注意，这可能会减慢表启动时的加载速度。可能的值：

true
false

另请参见

exclude_deleted_rows_for_part_size_in_merge 设置

lock_acquire_timeout_for_background_operations

对于合并、变更等后台操作，获取表锁失败前会等待多少秒。

mutation_workload

用于调节资源如何在变更与其他工作负载之间分配和共享。指定的值将作为该表后台变更的 workload 设置值使用。若未指定 (空字符串) ，则改用服务器设置 mutation_workload。 另请参见

Workload Scheduling

non_replicated_deduplication_window

在非复制表 MergeTree 表中，为最近插入的若干个块保存哈希值，以检查重复数据。可能的值：

任意正整数。
0 (禁用去重) 。

这里使用了与复制表类似的去重机制 (请参见 replicated_deduplication_window 设置) ：去重哈希值覆盖整个插入块。这些哈希值会写入磁盘上的本地文件，而不是写入 ClickHouse Keeper。

notify_newest_block_number

向 SharedJoin 或 SharedSet 通知最新的块编号。仅在 ClickHouse Cloud 中可用。

nullable_serialization_version

控制 Nullable(T) 列使用的序列化方法。可能的值：

basic — 对 Nullable(T) 使用标准序列化。
allow_sparse — 允许 Nullable(T) 使用稀疏编码。

object_serialization_version

JSON 数据类型的序列化版本。用于兼容性。可能的值：

v1
v2
v3

只有 v3 版本支持更改共享数据序列化版本。

old_parts_lifetime

存储非活跃分片的时长 (以秒为单位) ，用于防止服务器意外重启期间发生数据丢失。可能的值：

任意正整数。

将多个分片合并成一个新的分片后，ClickHouse 会将原始分片标记为非活跃，并仅在 old_parts_lifetime 秒后才删除它们。如果非活跃分片当前未被查询使用，也就是该分片的 refcount 为 1，则会被移除。新分片不会调用 fsync，因此在一段时间内，新分片只存在于服务器的 RAM (操作系统缓存) 中。如果服务器意外重启，新分片可能会丢失或损坏。为保护数据，非活跃分片不会被立即删除。启动期间，ClickHouse 会检查各个分片的完整性。如果合并后的分片已损坏，ClickHouse 会将非活跃分片恢复到活跃列表中，随后再次对其进行合并。然后，损坏的分片会被重命名 (添加 broken_ 前缀) 并移至 detached 文件夹中。如果合并后的分片没有损坏，则原始的非活跃分片会被重命名 (添加 ignored_ 前缀) 并移至 detached 文件夹中。默认的 dirty_expire_centisecs 值 (一个 Linux 内核设置) 是 30 秒 (已写入数据仅存储在 RAM 中的最长时间) ，但在磁盘系统负载较高时，数据实际写入的时间可能会晚得多。根据实验结果， old_parts_lifetime 选择了 480 秒，这段时间内可以保证新的分片被写入磁盘。

optimize_row_order

控制是否在插入期间优化行顺序，以提高新插入表分片的可压缩性。仅对普通 MergeTree 引擎表生效。对于专用的 MergeTree 引擎表 (例如 CollapsingMergeTree) 则无效。 MergeTree 表会 (可选地) 使用压缩编解码器进行压缩。如果数据呈现出某些模式，LZ4 和 ZSTD 等通用压缩编解码器可以达到更高的压缩率。相同值的长连续段通常具有很好的压缩效果。如果启用此设置，ClickHouse 会尝试以一种行顺序将数据存储到新插入的分片中，从而尽量减少新表分片各列中相同值连续段的数量。换句话说，相同值连续段的数量越少，就意味着单个连续段越长，压缩效果也越好。找到最优行顺序在计算上是不可行的 (NP-hard) 。因此，ClickHouse 使用启发式方法快速找到一种行顺序，虽然不是最优，但仍能比原始行顺序获得更好的压缩率。如果启用，插入操作会带来额外的 CPU 开销，用于分析并优化新数据的行顺序。预计 INSERT 的耗时会增加 30–50%，具体取决于数据特征。 LZ4 或 ZSTD 的压缩率平均可提升 20–40%。此设置最适用于没有主键或主键基数较低的表，也就是仅有少量不同主键值的表。对于高基数主键 (例如包含 DateTime64 类型时间戳列的主键) ，预计无法从此设置中受益。

packed_skip_index_max_bytes

低于该阈值 (即序列化后的磁盘字节数，也就是子流经过压缩和哈希事件链之后的大小) 的 skip-index 子流，不会写入单独的 skp_idx_<name>.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：

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 列占用的磁盘存储空间更少：

SELECT table, name, data_compressed_bytes, data_uncompressed_bytes FROM system.columns
WHERE table LIKE 'my_%_table';

┌─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 列，确认某一列是否使用了稀疏编码：

SELECT column, serialization_kind FROM system.parts_columns
WHERE table LIKE 'my_sparse_table';

你可以查看 s 中哪些部分是通过稀疏序列化存储的：

┌─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 会话过期检查周期，单位为秒。可能的值：

任意正整数。

最后修改于 2026年7月24日

格式设置用于控制输入和输出格式的设置项。

​adaptive_write_buffer_initial_size

​add_implicit_sign_column_constraint_for_collapsing_engine

​alter_column_secondary_index_mode

​apply_patches_on_merge

​assign_part_uuids

​auto_statistics_types

​background_task_preferred_step_execution_time_ms

​clean_deleted_rows

​clone_replica_zookeeper_create_get_part_batch_size

​compatibility_allow_sampling_expression_not_in_primary_key

​compute_exact_num_defaults_for_sparse_columns

​deduplicate_merge_projection_mode

​deduplication_hashes_cache_update_wait_ms

​default_compression_codec

​disk

​dynamic_serialization_version

​enforce_index_structure_match_on_partition_manipulation

​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

​load_existing_rows_count_for_old_parts

​lock_acquire_timeout_for_background_operations

​mutation_workload

​non_replicated_deduplication_window

​notify_newest_block_number

​nullable_serialization_version

​object_serialization_version

​old_parts_lifetime

​optimize_row_order

​packed_skip_index_max_bytes

​part_minmax_index_columns

​propagate_types_serialization_versions_to_nested_types

​ratio_of_defaults_for_sparse_serialization

​reduce_blocking_parts_sleep_ms

​replace_long_file_name_to_hash

​replicated_can_become_leader

​search_orphaned_parts_disks

​serialization_info_version

​share_nested_offsets

​simultaneous_parts_removal_limit

​storage_policy

​string_serialization_version

​temporary_directories_lifetime

​try_fetch_recompressed_part_timeout

​ttl_only_drop_parts

​wait_for_unique_parts_send_before_shutdown_ms

​zookeeper_session_expiration_check_period