MergeTree 表设置

system.merge_tree_settings 中的 MergeTree 相关设置

系统表 system.merge_tree_settings 显示全局设置的 MergeTree 设置。

MergeTree 设置可以在服务器配置文件的 merge_tree 部分中进行设置，也可以针对每个 MergeTree 表，在 CREATE TABLE 语句的 SETTINGS 子句中单独指定。

自定义设置 max_suspicious_broken_parts 的示例：

在服务器配置文件中为所有 MergeTree 表配置默认值：

<merge_tree>
    <max_suspicious_broken_parts>5</max_suspicious_broken_parts>
</merge_tree>

针对特定表的设置：

CREATE TABLE tab
(
    `A` Int64
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS max_suspicious_broken_parts = 500;

使用 ALTER TABLE ... MODIFY SETTING 更改特定表的 Settings：

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。

示例

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
• prefer_warmed_unmerged_parts_seconds
• cache_warmer_threads

​

cache_populated_by_fetch_filename_regexp

此设置仅适用于 ClickHouse Cloud。

如果该值非空，则仅在拉取后将与此正则表达式匹配的文件预热到缓存中 (前提是已启用 cache_populated_by_fetch) 。

​

check_delay_period

已废弃，没有任何作用。

​

check_sample_column_is_correct

启用在创建表时检查用于采样的列或采样表达式的数据类型是否正确。该数据类型必须是以下无符号 整数类型之一：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，请启用此设置。

此设置适用于已启用 数据复制 的 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 设置

​

exclude_materialize_skip_indexes_on_merge

将提供的以逗号分隔的跳过索引列表排除在合并期间的构建和存储之外。如果 materialize_skip_indexes_on_merge 为 false，则此设置不起作用。

被排除的跳过索引仍会通过显式 MATERIALIZE INDEX 查询构建并存储，或者根据 materialize_skip_indexes_on_insert 会话设置，在 INSERT 期间构建并存储。

示例：

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 一同启用， 系统会在表启动时计算现有数据 parts 中已删除的行数。 请注意，这可能会减慢表启动时的加载速度。

可能的值：

• true
• false

另请参见

• exclude_deleted_rows_for_part_size_in_merge 设置

​

lock_acquire_timeout_for_background_operations

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

​

map_buckets_coefficient

在 sqrt 和 linear 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 作为桶数量，而不考虑平均 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 和 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 或 在 INSERT 时 创建/存储。

另请参见 exclude_materialize_skip_indexes_on_merge，以进行更细粒度的控制。

​

materialize_statistics_on_merge

启用后，merge 会为新的 parts 构建并存储统计信息。 否则，可通过显式执行 MATERIALIZE STATISTICS 或在 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 决定。 允许的最大值为 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 发起的合并会忽略 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 设置) 。创建表时指定的值会覆盖此设置的全局值。

​

max_concurrent_queries

与 MergeTree 表相关、可同时执行的查询的最大数量。 查询仍会受到其他 max_concurrent_queries 设置的限制。

可能的值：

• 正整数。
• 0 — 不限制。

默认值：0 (不限制) 。

示例

<max_concurrent_queries>50</max_concurrent_queries>

​

max_delay_to_insert

该值以秒为单位：如果单个分区中的活动 parts 数量超过 parts_to_delay_insert 的值， 则用它来计算 INSERT 延迟。

可能的值：

• 任意正整数。

INSERT 延迟 (以毫秒为单位) 按以下公式计算：

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 版本开始，公式改为：

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。

​

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

限制复制 拉取操作通过网络进行数据交换的最大速度，单位为每秒字节数。与应用于 服务器的 max_replicated_fetches_network_bandwidth_for_server 设置不同，此设置适用于特定表。

你可以同时限制服务器网络和特定表的网络，但在这种情况下， 表级设置的值应小于服务器级设置的值。否则，服务器只会采用 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 发送操作的最大网络数据交换速率，单位为每秒字节数。与应用于 服务器的 max_replicated_sends_network_bandwidth_for_server 设置不同，此设置作用于特定表。

你可以同时限制服务器网络和特定表的网络，但在这种情况下， 表级设置的值应小于服务器级设置的值。否则，服务器只会采用 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。

另请参见

• 工作负载调度

​

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 上时， 启用均衡所需的最小字节数。

可能的值：

• 正整数。
• 0 — 禁用均衡。

用法

min_bytes_to_rebalance_partition_over_jbod 设置的值 不应小于 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 设置) 。创建表时指定的值会覆盖此设置的全局值。

​

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 设置的限制。

可能的值：

• 正整数。
• 0 — 已禁用 (max_concurrent_queries 限制不适用于任何查询) 。

示例

<min_marks_to_honor_max_concurrent_queries>10</min_marks_to_honor_max_concurrent_queries>

​

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。

另请参见

• 工作负载调度

​

non_replicated_deduplication_window

在非复制的 MergeTree表中， 用于存储最近插入的块的哈希值以进行重复检查的数量。

Possible values:

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

这里使用了与复制表类似的去重机制 (请参见 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 的值

• 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

• 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_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 表会 (可选地) 使用压缩编解码器进行压缩。 LZ4 和 ZSTD 等通用压缩编解码器在数据呈现出某种模式时，能够获得最高的压缩率。 相同值的长连续序列通常具有很好的压缩效果。

如果启用此设置，ClickHouse 会尝试以一种行顺序来存储新插入 parts 中的数据，从而尽量减少新表 part 各列中相同值连续段的数量。 换句话说，相同值连续段越少，通常意味着单个连续段越长， 压缩效果也越好。

寻找最优行顺序在计算上是不可行的 (NP-hard) 。 因此，ClickHouse 使用一种启发式方法来快速找到一种行顺序， 即使不是最优，也仍能比原始行顺序获得更好的压缩率。

如果启用，插入操作会带来额外的 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。

在 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：

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 中可用。在未丢弃/替换任何范围后，再次尝试减少 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) 。对于 插入去重， 在向复制表写入时，ClickHouse 会将所创建 parts 的哈希和写入 ClickHouse Keeper。哈希和只会为最近的 replicated_deduplication_window 个块保存。最旧的哈希和会 从 ClickHouse Keeper 中移除。

较大的 replicated_deduplication_window 值会减慢 Inserts 速度，因为需要比较更多条目。哈希和是根据 字段名称与类型的组合，以及已插入 分片 中的数据 (字节流) 计算得出的。

​

replicated_deduplication_window_for_async_inserts

ClickHouse Keeper 为检查重复项而存储哈希和时，所保留的最近异步插入块数量。

可能的值：

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

异步插入 命令会被缓存为一个或多个块 (parts) 。对于插入去重，在写入复制表时，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_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_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

启用协调合并策略

​

shared_merge_tree_enable_keeper_parts_extra_data

启用在 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

当 <candidate partitions for mutations only (partitions that cannot be merged)>/<candidate partitions 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) 。启用前，请先确认所有副本都支持 新格式。

​

use_minimalistic_part_header_in_zookeeper

ZooKeeper 中数据分区片段头的存储方式。启用后，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 会话过期检查周期 (以秒为单位) 。

可能的值：

• 任意正整数。