跳到主要内容
跳到主要内容
编辑此页

MergeTree 表设置

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

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

自定义设置 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 更改特定表的设置

ALTER TABLE tab MODIFY SETTING max_suspicious_broken_parts = 100;

-- reset to global default (value from system.merge_tree_settings)
ALTER TABLE tab RESET SETTING max_suspicious_broken_parts;

allow_nullable_key​

允许 Nullable 类型作为主键。

默认值：0。

index_granularity​

索引标记之间最大的数据行数。

默认值：8192。

index_granularity_bytes​

数据粒度的最大大小（以字节为单位）。

默认值：10485760（约 10 MiB）。

要仅按行数限制粒度大小，请设置为 0（不建议）。

min_index_granularity_bytes​

数据粒度的最小允许大小（以字节为单位）。

默认值：1024b。

提供安全保障，防止意外创建具有非常低的 index_granularity_bytes 的表。

enable_mixed_granularity_parts​

启用或禁用转换为使用 index_granularity_bytes 设置控制粒度大小。在 19.11 版本之前，只有 index_granularity 设置用于限制粒度大小。当从具有大数据行（数十和数百兆字节）的表中选择数据时，index_granularity_bytes 设置提高了 ClickHouse 的性能。如果您有具有大数据行的表，您可以为这些表启用此设置，以提高 SELECT 查询的效率。

use_minimalistic_part_header_in_zookeeper​

ZooKeeper 中数据部分标头的存储方法。如果启用，ZooKeeper 将存储更少的数据。有关详细信息，请参阅此处。

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。

默认值：10 * 1024 * 1024 * 1024 字节。

ttl_only_drop_parts​

控制当 MergeTree 表中某个部分的所有行都根据其 TTL 设置过期时，是否完全删除该数据部分。

当 ttl_only_drop_parts 禁用（默认）时，仅删除基于其 TTL 设置过期的行。

当 ttl_only_drop_parts 启用时，如果某个部分中的所有行都根据其 TTL 设置过期，则会删除整个部分。

默认值：0。

merge_with_ttl_timeout​

重复使用删除 TTL 合并之前的最小延迟（秒）。

默认值：14400 秒（4 小时）。

merge_with_recompression_ttl_timeout​

重复使用重新压缩 TTL 合并之前的最小延迟（秒）。

默认值：14400 秒（4 小时）。

write_final_mark​

启用或禁用在数据部分末尾（最后一个字节之后）写入最终索引标记。

默认值：1。

请勿更改，否则会发生不好的事情。

storage_policy​

存储策略。

min_bytes_for_wide_part​

可以以 Wide 格式存储的数据部分的最小字节数/行数。您可以设置其中一个、两个或都不设置。

max_compress_block_size​

压缩并写入表之前，未压缩数据的最大块大小。您也可以在全局设置中指定此设置（请参阅 max_compress_block_size 设置）。创建表时指定的此值将覆盖此设置的全局值。

min_compress_block_size​

写入下一个标记时压缩所需的未压缩数据的最小块大小。您也可以在全局设置中指定此设置（请参阅 min_compress_block_size 设置）。创建表时指定的此值将覆盖此设置的全局值。

max_suspicious_broken_parts​

如果单个分区中损坏的部分数超过 max_suspicious_broken_parts 值，则拒绝自动删除。

可能的值

  • 任何正整数。

默认值：100。

parts_to_throw_insert​

如果单个分区中的活动部分数超过 parts_to_throw_insert 值，则 INSERT 会被 Too many parts (N). Merges are processing significantly slower than inserts 异常中断。

可能的值

  • 任何正整数。

默认值：3000。

为了实现 SELECT 查询的最大性能，有必要最大限度地减少处理的部分数，请参阅 Merge Tree。

在 23.6 之前，此设置设置为 300。您可以设置更高的不同值，这将降低 Too many parts 错误的概率，但同时 SELECT 性能可能会下降。此外，如果出现合并问题（例如，由于磁盘空间不足），您会比使用原始的 300 更晚注意到它。

parts_to_delay_insert​

如果单个分区中的活动部分数超过 parts_to_delay_insert 值，则 INSERT 会人为地减慢速度。

可能的值

  • 任何正整数。

默认值：1000。

ClickHouse 会人为地延长 INSERT 的执行时间（添加“sleep”），以便后台合并进程可以比添加部分更快地合并部分。

inactive_parts_to_throw_insert​

如果单个分区中的非活动部分数超过 inactive_parts_to_throw_insert 值，则 INSERT 会被“Too many inactive parts (N). Parts cleaning are processing significantly slower than inserts”异常中断。

可能的值

  • 任何正整数。

默认值：0（无限制）。

inactive_parts_to_delay_insert​

如果表中单个分区中的非活动部分数至少达到 inactive_parts_to_delay_insert 值，则 INSERT 会人为地减慢速度。当服务器无法足够快地清理部分时，这很有用。

可能的值

  • 任何正整数。

默认值：0（无限制）。

max_delay_to_insert​

以秒为单位的值，用于计算 INSERT 延迟，如果单个分区中的活动部分数超过 parts_to_delay_insert 值。

可能的值

  • 任何正整数。

默认值：1。

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_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_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_parts_in_total​

如果表中所有分区中的活动部分总数超过 max_parts_in_total 值，则 INSERT 会被 Too many parts (N) 异常中断。

可能的值

  • 任何正整数。

默认值：100000。

表中的大量部分会降低 ClickHouse 查询的性能并增加 ClickHouse 的启动时间。最常见的情况是设计不正确（选择分区策略时出错 - 分区太小）导致的。

simultaneous_parts_removal_limit​

如果有大量过时的部分，则清理线程将尝试在一个迭代中删除最多 simultaneous_parts_removal_limit 个部分。simultaneous_parts_removal_limit 设置为 0 表示无限制。

默认值：0。

replicated_deduplication_window​

ClickHouse Keeper 存储最近插入的块的哈希和数，用于检查重复项的块数。

可能的值

  • 任何正整数。
  • 0（禁用重复数据删除）

默认值：1000。

Insert 命令创建一个或多个块（部分）。对于 插入重复数据删除，当写入复制表时，ClickHouse 会将创建部分的哈希和写入 ClickHouse Keeper。哈希和仅存储在最近的 replicated_deduplication_window 块中。最旧的哈希和将从 ClickHouse Keeper 中删除。大量的 replicated_deduplication_window 会减慢 Inserts 的速度，因为它需要比较更多条目。哈希和是根据字段名称和类型以及插入部分的数据（字节流）的组合计算得出的。

non_replicated_deduplication_window​

非复制 MergeTree 表中最近插入的块数，用于存储哈希和以检查重复项。

可能的值

  • 任何正整数。
  • 0（禁用重复数据删除）。

默认值：0。

使用类似于复制表的重复数据删除机制（请参阅 replicated_deduplication_window 设置）。创建部分的哈希和将写入磁盘上的本地文件。

replicated_deduplication_window_seconds​

插入块的哈希和从 ClickHouse Keeper 中删除后的秒数。

可能的值

  • 任何正整数。

默认值：604800（1 周）。

与 replicated_deduplication_window 类似，replicated_deduplication_window_seconds 指定为插入重复数据删除存储块哈希和的时间长度。早于 replicated_deduplication_window_seconds 的哈希和将从 ClickHouse Keeper 中删除，即使它们小于 replicated_deduplication_window。

时间是相对于最近记录的时间，而不是挂钟时间。如果是唯一记录，它将永远存储。

replicated_deduplication_window_for_async_inserts​

ClickHouse Keeper 存储最近异步插入的块的哈希和数，用于检查重复项的块数。

可能的值

  • 任何正整数。
  • 0（禁用 async_inserts 的重复数据删除）

默认值：10000。

Async Insert 命令将缓存在一个或多个块（部分）中。对于 插入重复数据删除，当写入复制表时，ClickHouse 会将每次插入的哈希和写入 ClickHouse Keeper。哈希和仅存储在最近的 replicated_deduplication_window_for_async_inserts 块中。最旧的哈希和将从 ClickHouse Keeper 中删除。大量的 replicated_deduplication_window_for_async_inserts 会减慢 Async Inserts 的速度，因为它需要比较更多条目。哈希和是根据字段名称和类型以及插入的数据（字节流）的组合计算得出的。

replicated_deduplication_window_seconds_for_async_inserts​

异步插入的哈希和从 ClickHouse Keeper 中删除后的秒数。

可能的值

  • 任何正整数。

默认值：604800（1 周）。

与 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。

时间是相对于最近记录的时间，而不是挂钟时间。如果是唯一记录，它将永远存储。

use_async_block_ids_cache​

如果为 true，我们将缓存异步插入的哈希和。

可能的值

  • true, false

默认值：false。

包含多个异步插入的块将生成多个哈希和。当某些插入重复时，keeper 将在一个 RPC 中仅返回一个重复的哈希和，这将导致不必要的 RPC 重试。此缓存将监视 Keeper 中的哈希和路径。如果在 Keeper 中监视更新，则缓存将尽快更新，以便我们能够在内存中过滤重复的插入。

async_block_ids_cache_min_update_interval_ms​

更新 use_async_block_ids_cache 的最小间隔（以毫秒为单位）

可能的值

  • 任何正整数。

默认值：100。

通常，use_async_block_ids_cache 会在监视 keeper 路径中出现更新后立即更新。但是，缓存更新可能过于频繁，并成为沉重的负担。此最小间隔可防止缓存更新过快。请注意，如果我们将此值设置得太长，则包含重复插入的块将具有更长的重试时间。

max_replicated_logs_to_keep​

如果存在非活动副本，则 ClickHouse Keeper 日志中可能有多少条记录。当此数字超过时，非活动副本将丢失。

可能的值

  • 任何正整数。

默认值：1000

min_replicated_logs_to_keep​

在 ZooKeeper 日志中保留大约此数量的最新记录，即使它们已过时。它不影响表的工作：仅用于在清理之前诊断 ZooKeeper 日志。

可能的值

  • 任何正整数。

默认值：10

prefer_fetch_merged_part_time_threshold​

如果自复制日志（ClickHouse Keeper 或 ZooKeeper）条目创建以来经过的时间超过此阈值，并且部分大小之和大于 prefer_fetch_merged_part_size_threshold，则优先从副本中提取合并的部分，而不是在本地进行合并。这是为了加快非常长的合并。

可能的值

  • 任何正整数。

默认值：3600

prefer_fetch_merged_part_size_threshold​

如果部分大小之和超过此阈值，并且自复制日志条目创建以来的时间大于 prefer_fetch_merged_part_time_threshold，则优先从副本中提取合并的部分，而不是在本地进行合并。这是为了加快非常长的合并。

可能的值

  • 任何正整数。

默认值：10,737,418,240

execute_merges_on_single_replica_time_threshold​

当此设置的值大于零时，只有一个副本立即开始合并，其他副本最多等待该时间量以下载结果，而不是在本地进行合并。如果选择的副本在该时间量内未完成合并，则会回退到标准行为。

可能的值

  • 任何正整数。

默认值：0（秒）

remote_fs_execute_merges_on_single_replica_time_threshold​

当此设置的值大于零时，如果共享存储上的合并部分且启用了 allow_remote_fs_zero_copy_replication，则只有一个副本立即开始合并。

零拷贝复制尚未准备好用于生产环境

在 ClickHouse 22.8 及更高版本中，默认情况下禁用零拷贝复制。不建议在生产环境中使用此功能。

可能的值

  • 任何正整数。

默认值：10800

try_fetch_recompressed_part_timeout​

开始重新压缩合并之前的超时时间（秒）。在此期间，ClickHouse 尝试从副本中提取分配了此重新压缩合并的重新压缩部分。

重新压缩在大多数情况下工作缓慢，因此我们不会在此超时之前开始重新压缩合并，并尝试从分配了此重新压缩合并的副本中提取重新压缩部分。

可能的值

  • 任何正整数。

默认值：7200

always_fetch_merged_part​

如果为 true，则此副本永远不会合并部分，并且始终从其他副本下载合并后的部分。

可能的值

  • true, false

默认值：false

max_suspicious_broken_parts​

最大损坏部分数，如果更多 - 拒绝自动删除。

可能的值

  • 任何正整数。

默认值：100

max_suspicious_broken_parts_bytes​

所有损坏部分的最大大小，如果更多 - 拒绝自动删除。

可能的值

  • 任何正整数。

默认值：1,073,741,824

max_files_to_modify_in_alter_columns​

如果修改（删除、添加）的文件数大于此设置，则不应用 ALTER。

可能的值

  • 任何正整数。

默认值：75

max_files_to_remove_in_alter_columns​

如果删除的文件数大于此设置，则不应用 ALTER。

可能的值

  • 任何正整数。

默认值：50

replicated_max_ratio_of_wrong_parts​

如果错误部分与部分总数的比率小于此值 - 允许启动。

可能的值

  • 浮点数，0.0 - 1.0

默认值：0.5

replicated_max_parallel_fetches_for_host​

限制来自端点的并行提取（实际上是池大小）。

可能的值

  • 任何正整数。

默认值：15

replicated_fetches_http_connection_timeout​

用于部分提取请求的 HTTP 连接超时。如果未显式设置，则从默认配置文件 http_connection_timeout 继承。

可能的值

  • 任何正整数。

默认值：如果未显式设置，则从默认配置文件 http_connection_timeout 继承。

replicated_can_become_leader​

如果为 true，则此节点上的复制表副本将尝试获取领导权。

可能的值

  • true, false

默认值：true

zookeeper_session_expiration_check_period​

ZooKeeper 会话过期检查周期，以秒为单位。

可能的值

  • 任何正整数。

默认值：60

detach_old_local_parts_when_cloning_replica​

修复丢失的副本时，不要删除旧的本地 part。

可能的值

  • true, false

默认值：true

replicated_fetches_http_connection_timeout​

用于 part 获取请求的 HTTP 连接超时（以秒为单位）。如果未显式设置，则从默认配置文件 http_connection_timeout 继承。

可能的值

  • 任何正整数。
  • 0 - 使用 http_connection_timeout 的值。

默认值：0。

replicated_fetches_http_send_timeout​

用于 part 获取请求的 HTTP 发送超时（以秒为单位）。如果未显式设置，则从默认配置文件 http_send_timeout 继承。

可能的值

  • 任何正整数。
  • 0 - 使用 http_send_timeout 的值。

默认值：0。

replicated_fetches_http_receive_timeout​

用于获取 part 请求的 HTTP 接收超时（以秒为单位）。如果未显式设置，则从默认配置文件 http_receive_timeout 继承。

可能的值

  • 任何正整数。
  • 0 - 使用 http_receive_timeout 的值。

默认值：0。

max_replicated_fetches_network_bandwidth​

限制 副本 获取时，网络数据交换的最大速度，单位为字节/秒。此设置应用于特定的表，与应用于服务器的 max_replicated_fetches_network_bandwidth_for_server 设置不同。

您可以限制服务器网络和特定表的网络，但为此，表级设置的值应小于服务器级设置的值。否则，服务器仅考虑 max_replicated_fetches_network_bandwidth_for_server 设置。

此设置并非完全精确地执行。

可能的值

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

默认值：0。

用法

可用于在复制数据以添加或替换新节点时限制速度。

max_replicated_sends_network_bandwidth​

限制 副本 发送时，网络数据交换的最大速度，单位为字节/秒。此设置应用于特定的表，与应用于服务器的 max_replicated_sends_network_bandwidth_for_server 设置不同。

您可以限制服务器网络和特定表的网络，但为此，表级设置的值应小于服务器级设置的值。否则，服务器仅考虑 max_replicated_sends_network_bandwidth_for_server 设置。

此设置并非完全精确地执行。

可能的值

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

默认值：0。

用法

可用于在复制数据以添加或替换新节点时限制速度。

old_parts_lifetime​

存储非活动 part 的时间（以秒为单位），以防止在服务器自发重启期间数据丢失。

可能的值

  • 任何正整数。

默认值：480。

将多个 part 合并为一个新 part 后，ClickHouse 将原始 part 标记为非活动状态，并在 old_parts_lifetime 秒后才删除它们。如果非活动 part 未被当前查询使用，即 part 的 refcount 为 1，则会删除它们。

新 part 不会调用 fsync，因此在一段时间内，新 part 仅存在于服务器的 RAM（OS 缓存）中。如果服务器自发重启，则新 part 可能会丢失或损坏。为了保护数据，非活动 part 不会立即删除。

启动期间，ClickHouse 检查 part 的完整性。如果合并后的 part 损坏，ClickHouse 会将非活动 part 返回到活动列表，然后再次合并它们。然后，损坏的 part 将被重命名（添加 broken_ 前缀）并移动到 detached 文件夹。如果合并后的 part 未损坏，则原始非活动 part 将被重命名（添加 ignored_ 前缀）并移动到 detached 文件夹。

默认的 dirty_expire_centisecs 值（Linux 内核设置）为 30 秒（写入的数据仅存储在 RAM 中的最长时间），但在磁盘系统负载较重的情况下，数据可能会稍后写入。经过实验，为 old_parts_lifetime 选择了一个 480 秒的值，在此期间，可以保证新 part 被写入磁盘。

max_bytes_to_merge_at_max_space_in_pool​

如果有足够的资源可用，则要合并为一个 part 的最大 part 总大小（以字节为单位）。大致对应于自动后台合并创建的最大可能 part 大小。

可能的值

  • 任何正整数。

默认值：161061273600 (150 GB)。

合并调度器定期分析分区中 part 的大小和数量，如果 pool 中有足够的空闲资源，它将启动后台合并。合并会一直进行，直到源 part 的总大小大于 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​

在后台 pool 中资源最少的情况下，要合并为一个 part 的最大 part 总大小（以字节为单位）。

可能的值

  • 任何正整数。

默认值：1048576 (1 MB)

max_bytes_to_merge_at_min_space_in_pool 定义了即使缺少可用磁盘空间（在 pool 中）也可以合并的 part 的最大总大小。这对于减少小 part 的数量和 Too many parts 错误的几率是必要的。合并通过将合并 part 的总大小加倍来预留磁盘空间。因此，在可用磁盘空间较小的情况下，可能会发生存在可用空间，但该空间已被正在进行的大型合并预留，因此其他合并无法启动，并且小 part 的数量随着每次插入而增长的情况。

merge_max_block_size​

从合并的 part 中读取到内存中的行数。

可能的值

  • 任何正整数。

默认值：8192

合并以 merge_max_block_size 行的块为单位从 part 中读取行，然后合并并将结果写入新的 part。读取的块放置在 RAM 中，因此 merge_max_block_size 会影响合并所需的 RAM 大小。因此，对于具有非常宽行的表，合并可能会消耗大量 RAM（如果平均行大小为 100kb，则在合并 10 个 part 时，(100kb * 10 * 8192) = ~ 8GB 的 RAM）。通过减小 merge_max_block_size，您可以减少合并所需的 RAM 量，但会减慢合并速度。

number_of_free_entries_in_pool_to_lower_max_size_of_merge​

当 pool（或副本队列）中的空闲条目数少于指定数量时，开始降低要处理（或放入队列）的最大合并大小。这是为了允许小合并进行处理 - 而不是用长时间运行的合并填充 pool。

可能的值

  • 任何正整数。

默认值：8

number_of_free_entries_in_pool_to_execute_mutation​

当 pool 中的空闲条目数少于指定数量时，不要执行 part mutation。这是为了为常规合并留下空闲线程并避免“Too many parts”。

可能的值

  • 任何正整数。

默认值：20

用法

number_of_free_entries_in_pool_to_execute_mutation 设置的值应小于 background_pool_size * background_merges_mutations_concurrency_ratio 的值。否则，ClickHouse 将抛出异常。

max_part_loading_threads​

ClickHouse 启动时读取 part 的最大线程数。

可能的值

  • 任何正整数。

默认值：auto（CPU 核心数）。

启动期间，ClickHouse 读取所有表的所有 part（读取 part 的元数据文件）以构建内存中所有 part 的列表。在某些具有大量 part 的系统中，此过程可能需要很长时间，并且可以通过增加 max_part_loading_threads 来缩短此时间（如果此过程不受 CPU 和磁盘 I/O 限制）。

max_partitions_to_read​

限制一个查询中可以访问的最大分区数。

创建表时指定的设置值可以通过查询级别设置覆盖。

可能的值

  • 任何正整数。

默认值：-1（无限制）。

您还可以在查询/会话/配置文件级别指定查询复杂度设置 max_partitions_to_read。

min_age_to_force_merge_seconds​

如果范围内的每个 part 都比 min_age_to_force_merge_seconds 的值旧，则合并 part。

默认情况下，忽略设置 max_bytes_to_merge_at_max_space_in_pool（请参阅 enable_max_bytes_limit_for_min_age_to_force_merge）。

可能的值

  • 正整数。

默认值：0 — 禁用。

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

默认值：false

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

默认值：false

number_of_free_entries_in_pool_to_execute_optimize_entire_partition​

当 pool 中的空闲条目数少于指定数量时，不要在后台执行优化整个分区（当设置 min_age_to_force_merge_seconds 并启用 min_age_to_force_merge_on_partition_only 时会生成此任务）。这是为了为常规合并留下空闲线程并避免“Too many parts”。

可能的值

  • 正整数。

默认值：25

number_of_free_entries_in_pool_to_execute_optimize_entire_partition 设置的值应小于 background_pool_size * background_merges_mutations_concurrency_ratio 的值。否则，ClickHouse 将抛出异常。

allow_floating_point_partition_key​

启用允许浮点数作为分区键。

可能的值

  • 0 — 不允许浮点分区键。
  • 1 — 允许浮点分区键。

默认值：0。

check_sample_column_is_correct​

在创建表时启用检查，以确保用于采样或采样表达式的列的数据类型是正确的。数据类型必须是无符号整数类型之一：UInt8、UInt16、UInt32、UInt64。

可能的值

  • true — 检查已启用。
  • false — 在创建表时禁用检查。

默认值：true。

默认情况下，ClickHouse 服务器在创建表时检查用于采样或采样表达式的列的数据类型。如果您已经有具有不正确采样表达式的表，并且不希望服务器在启动期间引发异常，请将 check_sample_column_is_correct 设置为 false。

min_bytes_to_rebalance_partition_over_jbod​

设置在通过卷磁盘 JBOD 分发新的大 part 时启用平衡的最小字节数。

可能的值

  • 正整数。
  • 0 — 平衡已禁用。

默认值：0。

用法

min_bytes_to_rebalance_partition_over_jbod 设置的值不应小于 max_bytes_to_merge_at_max_space_in_pool / 1024 的值。否则，ClickHouse 将抛出异常。

detach_not_byte_identical_parts​

如果数据 part 与其他副本上的数据 part 不是字节相同的，则在合并或 mutation 后，启用或禁用在副本上分离数据 part。如果禁用，则删除数据 part。如果您想稍后分析此类 part，请激活此设置。

此设置适用于启用了数据复制的 MergeTree 表。

可能的值

  • 0 — Part 已删除。
  • 1 — Part 已分离。

默认值：0。

merge_tree_clear_old_temporary_directories_interval_seconds​

设置 ClickHouse 执行清理旧临时目录的时间间隔（以秒为单位）。

可能的值

  • 任何正整数。

默认值：60 秒。

merge_tree_clear_old_parts_interval_seconds​

设置 ClickHouse 执行清理旧 part、WAL 和 mutation 的时间间隔（以秒为单位）。

可能的值

  • 任何正整数。

默认值：1 秒。

max_concurrent_queries​

与 MergeTree 表相关的并发执行查询的最大数量。查询仍将受到其他 max_concurrent_queries 设置的限制。

可能的值

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

默认值：0（无限制）。

示例

<max_concurrent_queries>50</max_concurrent_queries>

min_marks_to_honor_max_concurrent_queries​

查询读取的最小 marks 数，用于应用 max_concurrent_queries 设置。请注意，查询仍将受到其他 max_concurrent_queries 设置的限制。

可能的值

  • 正整数。
  • 0 — 禁用（max_concurrent_queries 限制不应用于任何查询）。

默认值：0（永不应用限制）。

示例

<min_marks_to_honor_max_concurrent_queries>10</min_marks_to_honor_max_concurrent_queries>

ratio_of_defaults_for_sparse_serialization​

列中默认值数量与所有值数量的最小比率。设置此值会导致列使用稀疏序列化存储。

如果列是稀疏的（主要包含零），ClickHouse 可以将其编码为稀疏格式并自动优化计算 - 数据在查询期间不需要完全解压缩。要启用此稀疏序列化，请将 ratio_of_defaults_for_sparse_serialization 设置定义为小于 1.0。如果该值大于或等于 1.0，则列将始终使用正常的完全序列化写入。

可能的值

  • 介于 0 和 1 之间的浮点数，用于启用稀疏序列化
  • 如果您不想使用稀疏序列化，则为 1.0（或更大）

默认值：0.9375

示例

注意下表中的 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             │
└────────┴────────────────────┘

replace_long_file_name_to_hash​

如果列的文件名太长（超过 max_file_name_length 字节），则将其替换为 SipHash128。默认值：false。

max_file_name_length​

文件名的最大长度，以保持原样而不进行哈希处理。仅在启用设置 replace_long_file_name_to_hash 时生效。此设置的值不包括文件扩展名的长度。因此，建议将其设置为低于最大文件名长度（通常为 255 字节）的值，并留有一些余量，以避免文件系统错误。默认值：127。

allow_experimental_block_number_column​

在合并时持久化虚拟列 _block_number。

默认值：false。

exclude_deleted_rows_for_part_size_in_merge​

如果启用，则在选择要合并的 part 时，将使用数据 part 的估计实际大小（即，排除通过 DELETE FROM 删除的行）。请注意，此行为仅针对在此设置启用后执行的 DELETE FROM 影响的数据 part 触发。

可能的值

  • true, false

默认值：false

另请参阅

load_existing_rows_count_for_old_parts​

如果与 exclude_deleted_rows_for_part_size_in_merge 一起启用，则将在表启动期间计算现有数据 part 的已删除行数。请注意，这可能会减慢表启动加载速度。

可能的值

  • true, false

默认值：false

另请参阅

use_compact_variant_discriminators_serialization​

启用 Variant 数据类型中鉴别器的二进制序列化的紧凑模式。当主要存在一个变体或大量 NULL 值时，此模式允许使用明显更少的内存来存储 part 中的鉴别器。

默认值：true

merge_workload​

用于调节合并和其他工作负载之间如何利用和共享资源。指定的值用作此表的后台合并的工作负载设置值。如果未指定（空字符串），则改用服务器设置 merge_workload。

默认值：空字符串

另请参阅

mutation_workload​

用于调节 mutation 和其他工作负载之间如何利用和共享资源。指定的值用作此表的后台 mutation 的工作负载设置值。如果未指定（空字符串），则改用服务器设置 mutation_workload。

默认值：空字符串

另请参阅

optimize_row_order​

控制是否应在插入期间优化行顺序，以提高新插入表 part 的可压缩性。

仅对普通 MergeTree 引擎表有效。对专用 MergeTree 引擎表（例如 CollapsingMergeTree）无效。

MergeTree 表（可选）使用 压缩编解码器 进行压缩。如果数据暴露出模式，则 LZ4 和 ZSTD 等通用压缩编解码器可实现最大压缩率。相同值的长运行通常压缩效果非常好。

如果启用此设置，ClickHouse 会尝试以最小化新表 part 列中等值运行次数的行顺序存储新插入 part 中的数据。换句话说，少量的等值运行意味着单个运行时间较长且压缩效果良好。

找到最佳行顺序在计算上是不可行的（NP 难题）。因此，ClickHouse 使用启发式方法快速找到仍然可以提高压缩率的行顺序，优于原始行顺序。

查找行顺序的启发式方法

通常可以自由地打乱表（或表 part）的行，因为 SQL 认为不同行顺序的同一表（表 part）是等效的。

当为表定义主键时，这种打乱行的自由会受到限制。在 ClickHouse 中，主键 C1, C2, ..., CN 强制表行按列 C1, C2, ... Cn 排序（聚集索引）。因此，行只能在行的“等价类”内打乱，即主键列中具有相同值的行。直观的理解是，具有高基数的主键，例如涉及 DateTime64 时间戳列的主键，会导致许多小的等价类。同样，具有低基数主键的表会创建少量且大的等价类。没有主键的表代表跨越所有行的单个等价类的极端情况。

等价类越少且越大，重新打乱行时的自由度就越高。

应用于在每个等价类中查找最佳行顺序的启发式方法由 D. Lemire、O. Kaser 在 Reordering columns for smaller indexes 中提出，并基于按非主键列的升序基数对每个等价类中的行进行排序。它执行三个步骤

  1. 根据主键列中的行值查找所有等价类。
  2. 对于每个等价类，计算（通常估计）非主键列的基数。
  3. 对于每个等价类，按非主键列基数升序对行进行排序。

如果启用，插入操作会产生额外的 CPU 成本来分析和优化新数据的行顺序。根据数据特性，INSERT 预计会花费 30-50% 更长的时间。LZ4 或 ZSTD 的压缩率平均提高 20-40%。

此设置最适用于没有主键或低基数主键的表，即只有少数不同主键值的表。高基数主键，例如涉及 DateTime64 类型的时间戳列的主键，预计不会从此设置中受益。

lightweight_mutation_projection_mode​

默认情况下，轻量级删除 DELETE 不适用于带有投影的表。这是因为投影中的行可能会受到 DELETE 操作的影响。因此，默认值将是 throw。但是，此选项可以更改行为。值为 drop 或 rebuild 时，删除将适用于投影。drop 将删除投影，因此在当前查询中可能会很快，因为投影被删除，但在未来的查询中会很慢，因为没有附加投影。rebuild 将重建投影，这可能会影响当前查询的性能，但可能会加快未来查询的速度。好处是这些选项仅在 part 级别起作用，这意味着未触及的 part 中的投影将保持不变，而不会触发任何操作，例如 drop 或 rebuild。

可能的值

  • 抛出, 删除, 重建

默认值：抛出

deduplicate_merge_projection_mode​

是否允许为非经典 MergeTree（即非（Replicated、Shared）MergeTree）的表创建投影。ignore 选项纯粹是为了兼容性，可能会导致不正确的答案。否则，如果允许，合并投影时的操作是什么，是 drop 还是 rebuild。因此，经典 MergeTree 将忽略此设置。它也控制 OPTIMIZE DEDUPLICATE，但对所有 MergeTree 家族成员都有效。与选项 lightweight_mutation_projection_mode 类似，它也是 part 级别。

可能的值

  • 忽略, 抛出, 删除, 重建

默认值：抛出

min_free_disk_bytes_to_perform_insert​

为了插入数据，磁盘空间中应有的最小可用字节数。如果可用空闲字节数小于 min_free_disk_bytes_to_perform_insert，则会抛出异常，并且不执行插入。请注意，此设置

  • 考虑了 keep_free_space_bytes 设置。
  • 不考虑 INSERT 操作将写入的数据量。
  • 仅当指定正数（非零）字节数时才检查

可能的值

  • 任何正整数。

默认值：0 字节。

请注意，如果同时指定了 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 操作将写入的数据量。
  • 仅当指定正数（非零）比率时才检查

可能的值

  • 浮点数，0.0 - 1.0

默认值：0.0

请注意，如果同时指定了 min_free_disk_ratio_to_perform_insert 和 min_free_disk_bytes_to_perform_insert，ClickHouse 将依赖于允许在更大的可用内存量上执行插入操作的值。

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)  -- Descending order on 'time' field
SETTINGS allow_experimental_reverse_key = 1;

SELECT * FROM example WHERE key = 'xxx' ORDER BY time DESC LIMIT 10;

通过在查询中使用 ORDER BY time DESC，将应用 ReadInOrder。

默认值： false

cache_populated_by_fetch​

注意

此设置仅适用于 ClickHouse Cloud。

当 cache_populated_by_fetch 禁用（默认设置）时，仅当运行需要这些数据部分的查询时，新数据部分才会被加载到缓存中。

如果启用，cache_populated_by_fetch 将导致所有节点从存储加载新的数据部分到其缓存中，而无需查询来触发此类操作。

默认值：false

另请参阅

add_implicit_sign_column_constraint_for_collapsing_engine​

如果为 true，则为 CollapsingMergeTree 或 VersionedCollapsingMergeTree 表的 sign 列添加隐式约束，以仅允许有效值（1 和 -1）。

默认值：false

add_minmax_index_for_numeric_columns​

启用后，将为表的所有数值列添加 min-max（跳过）索引。

默认值：false。

add_minmax_index_for_string_columns​

启用后，将为表的所有字符串列添加 min-max（跳过）索引。

默认值：false。

materialize_skip_indexes_on_merge​

启用后，合并操作会为新数据部分构建和存储跳过索引。

默认值: true

assign_part_uuids​

启用后，将为每个新的数据部分分配唯一的部件标识符。在启用之前，请检查所有副本是否支持 UUID 版本 4。

默认值: 0。