跳到主要内容
跳到主要内容

会话设置

所有以下设置在表 system.settings 中也可用。这些设置是从 source 自动生成的。

add_http_cors_header​

写入添加 http CORS 头。

additional_result_filter​

一个额外的过滤器表达式，应用于 SELECT 查询的结果。 该设置不适用于任何子查询。

示例

additional_table_filters​

一个额外的过滤器表达式，在从指定表读取后应用。

示例

aggregate_functions_null_for_empty​

启用或禁用在查询中重写所有聚合函数，并为其添加 -OrNull 后缀。为兼容 SQL 标准启用它。 它通过查询重写实现（类似于 count_distinct_implementation 设置），以获取分布式查询的一致结果。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

示例

考虑以下带有聚合函数的查询：

在 aggregate_functions_null_for_empty = 0 时，它将产生：

在 aggregate_functions_null_for_empty = 1 时，结果将是：

aggregation_in_order_max_block_bytes​

在主键顺序聚合期间累积的块的最大字节数。较小的块大小允许并行化聚合的最终合并阶段。

aggregation_memory_efficient_merge_threads​

用于合并中间聚合结果的线程数量，以内存高效模式运行。当更大时，消耗的内存更多。0 表示 - 与 'max_threads' 相同。

allow_aggregate_partitions_independently​

当分区键适合分组依据键时，启用在单独线程上独立聚合分区。当分区数量接近核心数量且分区大小大致相同的情况下，这种做法是有益的。

allow_archive_path_syntax​

文件/S3 引擎/表函数将解析路径为 '::' 作为 <archive> :: <file>，如果存档具有正确的扩展名。

allow_asynchronous_read_from_io_pool_for_merge_tree​

使用后台 I/O 池从 MergeTree 表中读取。此设置可能会提高 I/O 密集查询的性能。

allow_changing_replica_until_first_data_packet​

如果启用，在竞态请求中，我们可以在接收到第一个数据包之前开始新的连接，即使我们已经取得了一些进展 （但进展未更新至 receive_data_timeout 超时），否则我们将在第一次取得进展后禁用更改副本。

allow_create_index_without_type​

允许没有类型的 CREATE INDEX 查询。查询将被忽略。为适应 SQL 兼容性测试而设置。

allow_custom_error_code_in_throwif​

启用在函数 throwIf() 中使用自定义错误代码。如果为 true，抛出的异常可能具有意外的错误代码。

allow_ddl​

如果设置为 true，用户将被允许执行 DDL 查询。

allow_deprecated_database_ordinary​

允许创建具有已弃用的普通引擎的数据库。

allow_deprecated_error_prone_window_functions​

允许使用已弃用的高错误概率窗口函数（neighbor, runningAccumulate, runningDifferenceStartingWithFirstValue, runningDifference）。

allow_deprecated_snowflake_conversion_functions​

函数 snowflakeToDateTime, snowflakeToDateTime64, dateTimeToSnowflake 和 dateTime64ToSnowflake 已弃用，默认为禁用。 请使用函数 snowflakeIDToDateTime, snowflakeIDToDateTime64, dateTimeToSnowflakeID 和 dateTime64ToSnowflakeID。

要重新启用已弃用的函数（例如，在过渡期间），请将此设置设置为 true。

allow_deprecated_syntax_for_merge_tree​

允许使用已弃用的引擎定义语法创建 *MergeTree 表。

allow_distributed_ddl​

如果设置为 true，用户将被允许执行分布式 DDL 查询。

allow_drop_detached​

允许执行 ALTER TABLE ... DROP DETACHED PART[ITION] ... 查询。

allow_execute_multiif_columnar​

允许执行 multiIf 函数的列式操作。

allow_experimental_analyzer​

允许新的查询分析器。

allow_experimental_codecs​

Experimental feature. Learn more.

如果设置为 true，允许指定实验性压缩编解码器（但我们还没有这些，且此选项没有任何作用）。

allow_experimental_correlated_subqueries​

Experimental feature. Learn more.

允许执行相关子查询。

allow_experimental_database_glue_catalog​

Experimental feature. Learn more.

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'glue'。

allow_experimental_database_hms_catalog​

Experimental feature. Learn more.

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'hms'。

allow_experimental_database_iceberg​

Experimental feature. Learn more.

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'iceberg'。

allow_experimental_database_materialized_postgresql​

Experimental feature. Learn more.

允许创建数据库 Engine=MaterializedPostgreSQL(...)。

allow_experimental_database_unity_catalog​

Experimental feature. Learn more.

允许实验性数据库引擎 DataLakeCatalog，catalog_type = 'unity'。

allow_experimental_delta_kernel_rs​

Beta feature. Learn more.

允许实验性的 delta-kernel-rs 实现。

allow_experimental_dynamic_type​

允许创建 Dynamic 数据类型。

allow_experimental_full_text_index​

Experimental feature. Learn more.

如果设置为 true，允许使用实验性全文索引。

allow_experimental_funnel_functions​

Experimental feature. Learn more.

启用实验性漏斗分析函数。

allow_experimental_hash_functions​

Experimental feature. Learn more.

启用实验性哈希函数。

allow_experimental_inverted_index​

Experimental feature. Learn more.

如果设置为 true，允许使用实验性倒排索引。

allow_experimental_join_condition​

Experimental feature. Learn more.

支持对同时涉及左右表列的非等条件的连接，例如 t1.y < t2.y。

allow_experimental_join_right_table_sorting​

Experimental feature. Learn more.

如果设置为 true，并且满足 join_to_sort_minimum_perkey_rows 和 join_to_sort_maximum_table_rows 的条件，通过键重新排列右表，以提高左表或内连接的性能。

allow_experimental_json_type​

允许创建 JSON 数据类型。

allow_experimental_kafka_offsets_storage_in_keeper​

Experimental feature. Learn more.

允许实验性功能在 ClickHouse Keeper 中存储 Kafka 相关的偏移量。当启用时，可以将 ClickHouse Keeper 路径和副本名称指定给 Kafka 表引擎。结果是使用一种新型存储引擎来代替常规 Kafka 引擎，主要在 ClickHouse Keeper 中存储已提交的偏移量。

allow_experimental_kusto_dialect​

Experimental feature. Learn more.

启用 Kusto 查询语言（KQL） - SQL 的一种替代品。

allow_experimental_lightweight_update​

Experimental feature. Learn more.

允许使用轻量级更新。

allow_experimental_live_view​

Experimental feature. Learn more.

允许创建已弃用的实时视图。

可能的值：

  • 0 — 禁用实时视图。
  • 1 — 启用实时视图。

allow_experimental_materialized_postgresql_table​

Experimental feature. Learn more.

允许使用 MaterializedPostgreSQL 表引擎。默认禁用，因为此功能是实验性的。

allow_experimental_nlp_functions​

Experimental feature. Learn more.

启用自然语言处理的实验性函数。

allow_experimental_object_type​

Experimental feature. Learn more.

允许过时的对象数据类型。

allow_experimental_parallel_reading_from_replicas​

Beta feature. Learn more.

使用每个分片的 max_parallel_replicas 数量的副本进行 SELECT 查询执行。读取是并行的并动态协调。0 - 禁用，1 - 启用，遇到故障时静默禁用，2 - 启用，遇到故障时抛出异常。

allow_experimental_prql_dialect​

Experimental feature. Learn more.

启用 PRQL - SQL 的一种替代品。

allow_experimental_query_deduplication​

Experimental feature. Learn more.

基于部分 UUID 的 SELECT 查询的实验性数据去重。

allow_experimental_statistics​

Experimental feature. Learn more.

允许使用 statistics 来优化查询，并 操纵统计信息。

allow_experimental_time_series_table​

Experimental feature. Learn more.

允许创建使用 TimeSeries 表引擎的表。可能值：

allow_experimental_ts_to_grid_aggregate_function​

Experimental feature. Learn more.

实验性 tsToGrid 聚合函数，用于类 Prometheus 的时间序列重采样。云专用。

allow_experimental_variant_type​

允许创建 Variant 数据类型。

allow_experimental_vector_similarity_index​

Experimental feature. Learn more.

允许实验性向量相似度索引。

allow_experimental_window_view​

Experimental feature. Learn more.

启用窗口视图。还不够成熟。

allow_general_join_planning​

允许更一般的连接规划算法，可以处理更复杂的条件，但仅适用于哈希连接。如果哈希连接未启用，则使用常规连接规划算法，而不考虑此设置的值。

allow_get_client_http_header​

允许使用函数 getClientHTTPHeader，它允许获取当前 HTTP 请求头的值。出于安全原因，此功能默认未启用，因为某些头，例如 Cookie，可能包含敏感信息。请注意，X-ClickHouse-* 和 Authentication 头始终受到限制，不能通过此功能获取。

allow_hyperscan​

允许使用使用 Hyperscan 库的函数。禁用以避免潜在的长编译时间和过度资源使用。

allow_introspection_functions​

启用或禁用查询分析的 自省函数。

可能的值：

  • 1 — 启用自省函数。
  • 0 — 禁用自省函数。

另见

allow_materialized_view_with_bad_select​

允许 CREATE MATERIALIZED VIEW 使用引用不存在的表或列的 SELECT 查询。它仍然必须在语法上有效。不适用于可刷新的物化视图。如果 MV 模式需要从 SELECT 查询推断（即，如果 CREATE 没有列列表且没有 TO 表），则不适用。可用于在其源表之前创建 MV。

allow_named_collection_override_by_default​

允许默认覆盖命名集合的字段。

allow_non_metadata_alters​

允许执行不仅影响表元数据的更改，还影响磁盘上的数据。

allow_nonconst_timezone_arguments​

允许在某些时间相关函数中使用非常量时区参数，例如 toTimeZone()，fromUnixTimestamp*()，snowflakeToDateTime*()。

allow_nondeterministic_mutations​

用户级设置，允许在复制表上使用非确定性函数进行变更，例如 dictGet。

考虑到，例如，字典可能在节点之间不同步，因此，默认情况下，不允许在复制表上执行从中提取值的变更。启用此设置允许这种行为，用户有责任确保使用的数据在所有节点间同步。

示例

allow_nondeterministic_optimize_skip_unused_shards​

允许在分片键中使用非确定性函数（如 rand 或 dictGet，因为后者在更新时有一些注意事项）。

可能的值：

  • 0 — 不允许。
  • 1 — 允许。

allow_not_comparable_types_in_comparison_functions​

允许或限制在比较函数 equal/less/greater/etc 中使用不可比较类型（如 JSON/对象/聚合函数）。

allow_not_comparable_types_in_order_by​

允许或限制在 ORDER BY 键中使用不可比较类型（如 JSON/对象/聚合函数）。

allow_prefetched_read_pool_for_local_filesystem​

如果所有部分都在本地文件系统上，优先使用预取线程池。

allow_prefetched_read_pool_for_remote_filesystem​

如果所有部分都在远程文件系统上，优先使用预取线程池。

allow_push_predicate_ast_for_distributed_subqueries​

允许在启用分析器的情况下在分布式子查询的 AST 级别推送谓词。

allow_push_predicate_when_subquery_contains_with​

允许在子查询包含 WITH 子句时推送谓词。

allow_reorder_prewhere_conditions​

在从 WHERE 移动条件到 PREWHERE 时，允许重新排序以优化过滤。

allow_settings_after_format_in_insert​

控制在 INSERT 查询中是否允许在 FORMAT 之后使用 SETTINGS。不建议使用此选项，因为这可能会将 SETTINGS 的部分内容解释为值。

示例：

但以下查询将仅在 allow_settings_after_format_in_insert 为 true 时工作：

可能的值：

  • 0 — 不允许。
  • 1 — 允许。
备注

仅在您的用例依赖于旧语法时，使用此设置以实现向后兼容性。

allow_simdjson​

如果可用 AVX2 指令，则允许在 'JSON*' 函数中使用 simdjson 库。如果禁用，将使用 rapidjson。

allow_statistics_optimize​

Experimental feature. Learn more.

允许使用统计信息来优化查询。

allow_suspicious_codecs​

如果设置为 true，允许指定无意义的压缩编解码器。

allow_suspicious_fixed_string_types​

在 CREATE TABLE 语句中允许创建 FixedString(n) 类型的列，其中 n > 256。长度 >= 256 的 FixedString 是可疑的，并且很可能表明误用。

allow_suspicious_indices​

拒绝具有相同表达式的主/次索引和排序键。

allow_suspicious_low_cardinality_types​

允许或限制与固定大小为 8 字节或更小的数据类型使用 LowCardinality：数值数据类型和 FixedString(8_bytes_or_less)。

对于小的固定值，使用 LowCardinality 通常效率较低，因为 ClickHouse 为每一行存储数值索引。结果可能导致：

  • 磁盘空间使用增加。
  • RAM 使用增加，具体取决于字典大小。
  • 由于额外的编码/解码操作，某些函数的工作速度可能变慢。

基于所有前述原因，在 MergeTree 引擎表中的合并时间可能会增长。

可能的值：

  • 1 — 不限制使用 LowCardinality。
  • 0 — 限制使用 LowCardinality。

allow_suspicious_primary_key​

允许可疑的 PRIMARY KEY/ORDER BY 用于 MergeTree（即 SimpleAggregateFunction）。

allow_suspicious_ttl_expressions​

拒绝不依赖于任何表列的 TTL 表达式。这通常表明用户错误。

allow_suspicious_types_in_group_by​

允许或限制在 GROUP BY 键中使用 Variant 和 Dynamic 类型。

allow_suspicious_types_in_order_by​

允许或限制在 ORDER BY 键中使用 Variant 和 Dynamic 类型。

allow_suspicious_variant_types​

在 CREATE TABLE 语句中允许指定与相似变体类型（例如具有不同数值或日期类型）的 Variant 类型。启用该设置可能在处理具有相似类型的值时引入一些歧义。

allow_unrestricted_reads_from_keeper​

允许从 system.zookeeper 表中进行不受限（不带条件的路径）读取，这可能很方便，但对 zookeeper 来说并不安全。

alter_move_to_space_execute_async​

异步执行 ALTER TABLE MOVE ... TO [DISK|VOLUME]。

alter_partition_verbose_result​

启用或禁用显示已成功应用于分区和部分的操作的信息。 适用于 ATTACH PARTITION|PART 和 FREEZE PARTITION。

可能的值：

  • 0 — 禁用详细输出。
  • 1 — 启用详细输出。

示例

alter_sync​

允许设置等待通过 ALTER, OPTIMIZE 或 TRUNCATE 查询在副本上执行的操作。

可能的值：

  • 0 — 不等待。
  • 1 — 等待自己的执行。
  • 2 — 等待所有人的执行。

云默认值： 0。

备注

alter_sync 仅适用于 Replicated 表，对非 Replicated 表的更改没有任何作用。

alter_update_mode​

用于具有 UPDATE 命令的 ALTER 查询的模式。

可能的值：

  • heavy - 运行常规变更。
  • lightweight - 如果可能，运行轻量级更新，否则运行常规变更。
  • lightweight_force - 如果可能，运行轻量级更新，否则抛出异常。

analyze_index_with_space_filling_curves​

如果一个表的索引中有空间填充曲线，例如 ORDER BY mortonEncode(x, y) 或 ORDER BY hilbertEncode(x, y)，并且查询对其参数有条件，例如 x >= 10 AND x <= 20 AND y >= 20 AND y <= 30，则使用空间填充曲线进行索引分析。

analyzer_compatibility_join_using_top_level_identifier​

强制在 JOIN USING 中从投影解析标识符（例如，在 SELECT a + 1 AS b FROM t1 JOIN t2 USING (b) 中，将执行通过 t1.a + 1 = t2.b 连接，而不是 t1.b = t2.b）。

any_join_distinct_right_table_keys​

启用 ClickHouse 服务器在 ANY INNER|LEFT JOIN 操作中的遗留行为。

备注

仅在您的用例依赖于遗留 JOIN 行为时使用该设置以实现向后兼容性。

启用遗留行为时：

  • t1 ANY LEFT JOIN t2 和 t2 ANY RIGHT JOIN t1 操作的结果不相等，因为 ClickHouse 使用许多对一的左到右表键映射逻辑。
  • ANY INNER JOIN 操作的结果包含左表中的所有行，如同 SEMI LEFT JOIN 操作的结果。

禁用遗留行为时：

  • t1 ANY LEFT JOIN t2 和 t2 ANY RIGHT JOIN t1 操作的结果相等，因为 ClickHouse 使用在 ANY RIGHT JOIN 操作中提供一种对多的键映射逻辑。
  • ANY INNER JOIN 操作的结果包含来自左表和右表的每个键的一行。

可能的值：

  • 0 — 禁用遗留行为。
  • 1 — 启用遗留行为。

另见：

apply_deleted_mask​

启用过滤出通过轻量级 DELETE 删除的行。如果禁用，则查询仍可以读取那些行。这对于调试和“撤消删除”场景很有用。

apply_mutations_on_fly​

如果为 true，则未在数据部分中物化的变更（UPDATE 和 DELETE）将在 SELECT 时应用。

apply_patch_parts​

如果为 true，则将在 SELECT 时应用补丁部分（表示轻量级更新）。

apply_settings_from_server​

客户端是否应该接受来自服务器的设置。

这仅影响在客户端上执行的操作，特别是解析 INSERT 输入数据和格式化查询结果。大多数查询执行在服务器上进行，且不受此设置的影响。

通常，此设置应在用户配置文件中设置（users.xml 或 ALTER USER 类的查询），而不是通过客户端（客户端命令行参数，SET 查询或 SELECT 查询的 SETTINGS 部分）。通过客户端可以更改为 false，但无法更改为 true（因为如果用户配置文件中设置了 apply_settings_from_server = false，则服务器将不会发送设置）。

请注意，最初（24.12）有一个服务器设置（send_settings_to_client），但后来它被此客户端设置替代，目的是为了更好的可用性。

asterisk_include_alias_columns​

在通配符查询（SELECT *）时包括 ALIAS 列。

可能的值：

  • 0 - 禁用
  • 1 - 启用

asterisk_include_materialized_columns​

在通配符查询（SELECT *）时包括 MATERIALIZED 列。

可能的值：

  • 0 - 禁用
  • 1 - 启用

async_insert​

如果为 true，INSERT 查询的数据将存储在队列中，稍后在后台刷新到表中。如果 wait_for_async_insert 为 false，INSERT 查询几乎会立即处理，否则客户端将在数据刷新到表中之前等待。

async_insert_busy_timeout_decrease_rate​

自适应异步插入超时时间减少的指数增长率。

async_insert_busy_timeout_increase_rate​

自适应异步插入超时时间增加的指数增长率。

async_insert_busy_timeout_max_ms​

自首次出现数据以来每个查询收集数据的最大等待时间。

async_insert_busy_timeout_min_ms​

如果通过 async_insert_use_adaptive_busy_timeout 启用自我调整，则自首次出现数据以来每个查询收集数据的最小等待时间。它也作为自适应算法的初始值。

async_insert_deduplicate​

对于在复制表中的异步 INSERT 查询，指定应执行插入块的去重。

async_insert_max_data_size​

在插入之前，每个查询收集的未解析数据的最大字节大小。

async_insert_max_query_number​

在插入之前的最大插入查询数量。

async_insert_poll_timeout_ms​

从异步插入队列轮询数据的超时。

async_insert_use_adaptive_busy_timeout​

如果设置为 true，则使用自适应忙时超时进行异步插入。

async_query_sending_for_remote​

在执行远程查询时启用异步连接创建和查询发送。

默认情况下启用。

async_socket_for_remote​

在执行远程查询时启用从套接字进行异步读取。

默认情况下启用。

azure_allow_parallel_part_upload​

使用多个线程进行 Azure 多部分上传。

azure_check_objects_after_upload​

检查在 Azure Blob 存储中每个已上传对象，以确保上传成功

azure_create_new_file_on_insert​

启用或禁用在 Azure 引擎表中每次插入时创建新文件

azure_ignore_file_doesnt_exist​

读取某些键时，如果文件不存在则忽略缺失的文件。

可能的值：

  • 1 — SELECT 返回空结果。
  • 0 — SELECT 抛出异常。

azure_list_object_keys_size​

在 ListObject 请求中可以返回的最大文件数

azure_max_blocks_in_multipart_upload​

Azure 多部分上传中块的最大数量。

azure_max_inflight_parts_for_one_file​

多部分上传请求中一个文件可以并发加载的最大部分数量。 0 表示无限制。

azure_max_single_part_copy_size​

使用单部分复制到 Azure Blob 存储的对象的最大大小。

azure_max_single_part_upload_size​

使用单部分上传到 Azure Blob 存储的对象的最大大小。

azure_max_single_read_retries​

在单个 Azure Blob 存储读取期间的最大重试次数。

azure_max_unexpected_write_error_retries​

在 Azure Blob 存储写入期间遇到意外错误时的最大重试次数

azure_max_upload_part_size​

在 Azure Blob 存储的多部分上传过程中要上传的部分的最大大小。

azure_min_upload_part_size​

在 Azure Blob 存储的多部分上传过程中要上传的部分的最小大小。

azure_sdk_max_retries​

Azure SDK 中的最大重试次数

azure_sdk_retry_initial_backoff_ms​

Azure SDK 中重试之间的最小退避时间

azure_sdk_retry_max_backoff_ms​

Azure SDK 中重试之间的最大退避时间

azure_skip_empty_files​

启用或禁用在 S3 引擎中跳过空文件。

可能的值：

  • 0 — 如果空文件与请求的格式不兼容，SELECT 会抛出异常。
  • 1 — 空文件的 SELECT 返回空结果。

azure_strict_upload_part_size​

在 Azure Blob 存储的多部分上传过程中要上传的部分的确切大小。

azure_throw_on_zero_files_match​

如果根据 glob 扩展规则匹配到的文件数为零，则抛出错误。

可能的值：

  • 1 — SELECT 抛出异常。
  • 0 — SELECT 返回空结果。

azure_truncate_on_insert​

启用或禁用在 Azure 引擎表中插入前截断数据。

azure_upload_part_size_multiply_factor​

上传到 Azure Blob 存储时，每次从单次写入上传 azure_multiply_parts_count_threshold 部分时，将 azure_min_upload_part_size 乘以此因子。

azure_upload_part_size_multiply_parts_count_threshold​

每次向 Azure Blob 存储上传该数量的部分时，azure_min_upload_part_size 会乘以 azure_upload_part_size_multiply_factor。

backup_restore_batch_size_for_keeper_multi​

在备份或恢复期间对 [Zoo]Keeper 发出的多请求的最大批量大小

backup_restore_batch_size_for_keeper_multiread​

在备份或恢复期间对 [Zoo]Keeper 发出的多读取请求的最大批量大小

backup_restore_failure_after_host_disconnected_for_seconds​

如果主机在 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作期间未能在这个时间段内在 ZooKeeper 中重新创建其临时的“存活”节点，则整个备份或恢复将被视为失败。 该值应大于主机在故障后重新连接到 ZooKeeper 的任何合理时间。 零表示无限制。

backup_restore_finish_timeout_after_error_sec​

发起者在当前 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作中等待其他主机对“错误”节点做出反应并停止其工作的时间。

backup_restore_keeper_fault_injection_probability​

备份或恢复期间 Keeper 请求的故障注入的近似概率。有效值在区间 [0.0f, 1.0f] 内

backup_restore_keeper_fault_injection_seed​

0 - 随机种子， 否则为设置值

backup_restore_keeper_max_retries​

在备份或恢复操作中 [Zoo]Keeper 操作的最大重试次数。 应该足够大，以便整个操作不会因临时 [Zoo]Keeper 故障而失败。

backup_restore_keeper_max_retries_while_handling_error​

在处理 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作的错误时 [Zoo]Keeper 操作的最大重试次数。

backup_restore_keeper_max_retries_while_initializing​

在初始化 BACKUP ON CLUSTER 或 RESTORE ON CLUSTER 操作期间 [Zoo]Keeper 操作的最大重试次数。

backup_restore_keeper_retry_initial_backoff_ms​

备份或恢复期间 [Zoo]Keeper 操作的初始退避超时

backup_restore_keeper_retry_max_backoff_ms​

备份或恢复期间 [Zoo]Keeper 操作的最大退避超时

backup_restore_keeper_value_max_size​

备份期间 [Zoo]Keeper 节点的数据的最大大小

backup_restore_s3_retry_attempts​

Aws::Client::RetryStrategy 的设置， Aws::Client 会自行进行重试，0 表示不重试。仅在备份/恢复期间生效。

cache_warmer_threads​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。用于在启用 cache_populated_by_fetch 的情况下，后台线程的数量，以推测性地将新数据部分下载到文件缓存中。零表示禁用。

calculate_text_stack_trace​

在查询执行过程中如果出现异常，则计算文本堆栈跟踪。这是默认设置。它需要符号查找，可能会在执行大量错误查询时减慢模糊测试。正常情况下，不应该禁用此选项。

cancel_http_readonly_queries_on_client_close​

当客户端关闭连接而不等待响应时，取消 HTTP 只读查询（例如 SELECT）。

云默认值：1。

cast_ipv4_ipv6_default_on_conversion_error​

CAST 操作符转换为 IPv4，CAST 操作符转换为 IPV6 类型，toIPv4、toIPv6 函数将在转换错误时返回默认值，而不是抛出异常。

cast_keep_nullable​

启用或禁用在 CAST 操作中保留 Nullable 数据类型。

启用此设置后，CAST 函数的参数为 Nullable 时，结果也会转换为 Nullable 类型。当禁用此设置时，结果始终符合目标类型。

可能的值：

  • 0 — CAST 的结果具有完全指定的目标类型。
  • 1 — 如果参数类型为 Nullable，则 CAST 结果转换为 Nullable(DestinationDataType)。

示例

以下查询的结果为完全符合目标数据类型：

结果：

以下查询在目标数据类型上产生 Nullable 修饰：

结果：

另请参见

cast_string_to_dynamic_use_inference​

在字符串到动态转换时使用类型推断

cast_string_to_variant_use_inference​

在字符串到变体转换时使用类型推断。

check_query_single_value_result​

定义 CHECK TABLE 查询的结果细节级别，适用于 MergeTree 家族引擎。

可能的值：

  • 0 — 查询显示表的每个独立数据部分的检查状态。
  • 1 — 查询显示总体表检查状态。

check_referential_table_dependencies​

检查 DDL 查询（例如 DROP TABLE 或 RENAME）是否不会破坏引用依赖关系

check_table_dependencies​

检查 DDL 查询（例如 DROP TABLE 或 RENAME）是否不会破坏依赖关系

checksum_on_read​

在读取时验证校验和。此设置默认启用，并且在生产环境中应始终启用。请不要期望禁用此设置会有任何好处。此设置仅适用于 MergeTree 家族的表。对于其他表引擎以及通过网络接收数据时，始终会验证校验和。

cloud_mode​

云模式

cloud_mode_database_engine​

云中允许的数据库引擎。1 - 将 DDL 重写为使用 Replicated 数据库，2 - 将 DDL 重写为使用 Shared 数据库

cloud_mode_engine​

云中允许的引擎系列。

  • 0 - 允许所有
  • 1 - 将 DDL 重写为使用 *ReplicatedMergeTree
  • 2 - 将 DDL 重写为使用 SharedMergeTree
  • 3 - 将 DDL 重写为使用 SharedMergeTree，除非显式传递了远程磁盘

UInt64 以最小化公有部分

cluster_for_parallel_replicas​

Beta feature. Learn more.

当前服务器所在分片的集群

collect_hash_table_stats_during_aggregation​

启用收集哈希表统计以优化内存分配

collect_hash_table_stats_during_joins​

启用收集哈希表统计以优化内存分配

compatibility​

compatibility 设置使 ClickHouse 使用先前版本的默认设置，先前版本作为设置提供。

如果设置为非默认值，则遵循这些设置（只有未修改的设置才受 compatibility 设置的影响）。

此设置接受 ClickHouse 版本号作为字符串，例如 22.3、22.8。空值表示禁用此设置。

默认情况下禁用。

备注

在 ClickHouse Cloud 中，兼容性设置必须由 ClickHouse Cloud 支持设置。 请 提交案例 以进行设置。

compatibility_ignore_auto_increment_in_create_table​

如果为真，则忽略列声明中的 AUTO_INCREMENT 关键字，否则返回错误。它简化了从 MySQL 的迁移。

compatibility_ignore_collation_in_create_table​

兼容性忽略在创建表时的排序

compile_aggregate_expressions​

启用或禁用聚合函数的 JIT 编译为本机代码。启用此设置可以提高性能。

可能的值：

  • 0 — 聚合不使用 JIT 编译。
  • 1 — 聚合使用 JIT 编译。

另请参见

compile_expressions​

将一些标量函数和运算符编译为本机代码。

compile_sort_description​

编译排序描述为本机代码。

connect_timeout​

如果没有副本，则连接超时。

connect_timeout_with_failover_ms​

当在集群定义中使用“shard”和“replica”部分时，连接到远程服务器的超时（以毫秒为单位）的分布式表引擎。 如果不成功，将尝试连接到多个副本。

connect_timeout_with_failover_secure_ms​

选择第一个健康副本的连接超时（用于安全连接）。

connection_pool_max_wait_ms​

连接池满时连接的等待时间（以毫秒为单位）。

可能的值：

  • 正整数。
  • 0 — 无限超时。

connections_with_failover_max_tries​

分布式表引擎对每个副本的最大连接尝试次数。

convert_query_to_cnf​

设置为 true 时，SELECT 查询将转换为合取范式（CNF）。在一些场景中，将查询重写为 CNF 可能会更快执行（请查看 Github issue 获得解释）。

例如，以下 SELECT 查询没有被修改（默认行为）：

结果是：

将 convert_query_to_cnf 设置为 true，看看有什么变化：

注意 WHERE 子句被重写为 CNF，但结果集保持不变 - 布尔逻辑没有改变：

可能的值：true, false

count_distinct_implementation​

指定应使用哪些 uniq* 函数来执行 COUNT(DISTINCT ...) 构造。

可能的值：

count_distinct_optimization​

将计算不同计数重写为分组的子查询

create_if_not_exists​

默认启用 CREATE 语句的 IF NOT EXISTS。如果此设置或 IF NOT EXISTS 被指定且提供的表名已存在，则不会抛出异常。

create_index_ignore_unique​

在创建唯一索引时忽略 UNIQUE 关键字。用于 SQL 兼容性测试。

create_replicated_merge_tree_fault_injection_probability​

在创建表时，在 ZooKeeper 中创建元数据后进行故障注入的概率

create_table_empty_primary_key_by_default​

允许在排序 BY 和主键未指定时创建 *MergeTree 表的空主键

cross_join_min_bytes_to_compress​

CROSS JOIN 中要压缩的块的最小字节大小。零值表示禁用此阈值。只有当两者中的任一个阈值（按行或按字节）达到时，该块才会被压缩。

cross_join_min_rows_to_compress​

CROSS JOIN 中压缩块的最小行数。零值表示禁用此阈值。只有当两者中的任一个阈值（按行或按字节）达到时，该块才会被压缩。

data_type_default_nullable​

允许在列定义中没有显式修饰符 NULL 或 NOT NULL 的数据类型将被 Nullable。

可能的值：

  • 1 — 列定义中的数据类型默认设置为 Nullable。
  • 0 — 列定义中的数据类型默认设置为非 Nullable。

database_atomic_wait_for_drop_and_detach_synchronously​

对所有 DROP 和 DETACH 查询添加修饰符 SYNC。

可能的值：

  • 0 — 查询将延迟执行。
  • 1 — 查询将立即执行。

database_replicated_allow_explicit_uuid​

0 - 不允许为复制数据库中的表显式指定 UUID。1 - 允许。2 - 允许，但忽略指定的 UUID，并生成随机的 UUID。

database_replicated_allow_heavy_create​

允许在复制数据库引擎中执行需长时间运行的 DDL 查询（CREATE AS SELECT 和 POPULATE）。请注意，这可能会长时间阻塞 DDL 队列。

database_replicated_allow_only_replicated_engine​

允许在使用复制引擎的数据库中仅创建 Replicated 表

database_replicated_allow_replicated_engine_arguments​

0 - 不允许显式指定复制数据库中的 *MergeTree 表的 ZooKeeper 路径和副本名称。1 - 允许。2 - 允许，但忽略指定的路径，使用默认路径。3 - 允许并且不记录警告。

database_replicated_always_detach_permanently​

如果数据库引擎为 Replicated，则将 DETACH TABLE 执行为 DETACH TABLE PERMANENTLY。

database_replicated_enforce_synchronous_settings​

强制对某些查询进行同步等待（另请参见 database_atomic_wait_for_drop_and_detach_synchronously、mutations_sync、alter_sync）。不建议启用这些设置。

database_replicated_initial_query_timeout_sec​

设置初始 DDL 查询在复制数据库处理之前 DDL 队列条目时应等待的时间（以秒为单位）。

可能的值：

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

decimal_check_overflow​

检查十进制算术/比较操作的溢出

deduplicate_blocks_in_dependent_materialized_views​

启用或禁用对从 Replicated* 表接收数据的物化视图的去重检查。

可能的值：

0 — 禁用。 1 — 启用。

用法

默认情况下，物化视图不会执行去重，而是在源表中完成。 如果由于源表的去重而跳过了一块 INSERT，则不会插入到附加的物化视图中。这种行为是为了使高度聚合的数据插入物化视图成为可能，在这种情况下，插入的块在物化视图聚合后是相同的，但来自源表的不同插入。 同时，这种行为会“打破” INSERT 的幂等性。如果主表中的 INSERT 成功，而物化视图的 INSERT 失败（例如，由于与 ClickHouse Keeper 的通信失败），客户端将收到错误并可以重试操作。但是，物化视图不会接收第二次插入，因为它会被主（源）表中的去重丢弃。设置 deduplicate_blocks_in_dependent_materialized_views 允许更改此行为。在重试时，物化视图将接收重复插入，并自行执行去重检查， 忽略源表的检查结果，并插入因第一次故障而丢失的行。

default_materialized_view_sql_security​

允许在创建物化视图时设置 SQL SECURITY 选项的默认值。有关 SQL 安全的更多信息。

默认值为 DEFINER。

default_max_bytes_in_join​

如果需要限制，但未设置 max_bytes_in_join，则右侧表的最大大小。

default_normal_view_sql_security​

允许在创建常规视图时设置默认的 SQL SECURITY 选项。有关 SQL 安全的更多信息。

默认值为 INVOKER。

default_table_engine​

在 CREATE 语句中未设置 ENGINE 时使用的默认表引擎。

可能的值：

  • 一个字符串，表示任何有效的表引擎名称

云默认值： SharedMergeTree。

示例

查询：

结果：

在这个示例中，任何新表如果未指定 Engine，将使用 Log 表引擎：

查询：

结果：

default_temporary_table_engine​

与 default_table_engine 相同，但适用于临时表。

在这个示例中，任何新的临时表如果未指定 Engine，将使用 Log 表引擎：

查询：

结果：

default_view_definer​

允许在创建视图时设置默认的 DEFINER 选项。有关 SQL 安全的更多信息。

默认值为 CURRENT_USER。

describe_compact_output​

如果为真，则仅在 DESCRIBE 查询的结果中包含列名和类型

describe_extend_object_types​

在 DESCRIBE 查询中推断类型为对象的列的具体类型

describe_include_subcolumns​

启用描述 DESCRIBE 查询的子列。例如， Tuple 的成员或 Map、 Nullable 或 Array 数据类型的子列。

可能的值：

  • 0 — 子列未包含在 DESCRIBE 查询中。
  • 1 — 子列包含在 DESCRIBE 查询中。

示例

请参见 DESCRIBE 语句的示例。

describe_include_virtual_columns​

如果为真，则表中的虚拟列将包含在 DESCRIBE 查询的结果中

dialect​

将使用哪个方言来解析查询

dictionary_validate_primary_key_type​

验证字典的主键类型。默认情况下，简单布局的 ID 类型将被隐式转换为 UInt64。

distinct_overflow_mode​

设置数据量超过其中一个限制时发生的情况。

可能的值：

  • throw: 抛出一个异常（默认）。
  • break: 停止执行查询并返回部分结果，就像源数据耗尽一样。

distributed_aggregation_memory_efficient​

是否启用分布式聚合的节省内存模式。

distributed_background_insert_batch​

启用/禁用批量发送插入数据。

启用批量发送时， Distributed 表引擎尝试将多份插入数据作为一次操作发送，而不是分别发送。批量发送通过更好地利用服务器和网络资源来提高集群性能。

可能的值：

  • 1 — 启用。
  • 0 — 禁用。

distributed_background_insert_max_sleep_time_ms​

Distributed 表引擎发送数据的最大时间间隔。限制 distributed_background_insert_sleep_time_ms 设置中所设立的时间的指数增长。

可能的值：

  • 一个正整数（以毫秒为单位）。

distributed_background_insert_sleep_time_ms​

Distributed 表引擎发送数据的基础时间间隔。在发生错误时，实际的间隔成倍增长。

可能的值：

  • 一个正整数（以毫秒为单位）。

distributed_background_insert_split_batch_on_failure​

启用/禁用在故障时分割批次。

有时将特定批次发送到远程分片可能会失败，因为在之后的某些复杂管道（即带有 GROUP BY 的 MATERIALIZED VIEW）中出现 “内存限制 exceeded” 或类似错误。在这种情况下，重试将没有帮助（这将造成分布式发送被阻塞），但逐个发送该批次中的文件可能会成功 INSERT。

因此，将此设置安装为 1 将禁用对此类批次的分批（即临时禁用失败批次的 distributed_background_insert_batch）。

可能的值：

  • 1 — 启用。
  • 0 — 禁用。
备注

此设置还会影响损坏的批次（这可能是由于服务器（机器）的异常终止以及 Distributed 表引擎没有执行 fsync_after_insert/fsync_directories）。

备注

您不应依赖于自动批次分割，因为这可能会影响性能。

distributed_background_insert_timeout​

插入查询到分布式的超时。仅在启用 insert_distributed_sync 时使用。零值表示没有超时。

distributed_cache_bypass_connection_pool​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。允许绕过分布式缓存连接池

distributed_cache_connect_max_tries​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。如果连接失败，则重新连接到分布式缓存的尝试次数

distributed_cache_data_packet_ack_window​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。用于在单个分布式缓存读取请求中发送 ACK 的数据包序列窗口。

distributed_cache_discard_connection_if_unread_data​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。如果某些数据未被读取，则丢弃连接。

distributed_cache_fetch_metrics_only_from_current_az​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。仅从当前可用区获取 system.distributed_cache_metrics, system.distributed_cache_events 中的指标。

distributed_cache_log_mode​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。提供写入 system.distributed_cache_log 的模式。

distributed_cache_max_unacked_inflight_packets​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。单个分布式缓存读取请求中的最大未确认的在途数据包数量。

distributed_cache_min_bytes_for_seek​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。进行分布式缓存查找的最小字节数。

distributed_cache_pool_behaviour_on_limit​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。定义当达到池限制时分布式缓存连接的行为。

distributed_cache_read_alignment​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。用于测试目的的设置，请勿更改。

distributed_cache_read_only_from_current_az​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。允许仅从当前可用区读取。如果禁用，将从所有可用区的所有缓存服务器读取。

distributed_cache_read_request_max_tries​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。如果请求失败，尝试进行分布式缓存请求的次数。

distributed_cache_receive_response_wait_milliseconds​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。等待时间（以毫秒为单位），以接收来自分布式缓存请求的数据。

distributed_cache_receive_timeout_milliseconds​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。等待时间（以毫秒为单位），以接收来自分布式缓存的任何响应。

distributed_cache_throw_on_error​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。在与分布式缓存通信期间重新抛出发生的异常或从分布式缓存接收到的异常。否则在出现错误时会跳过分布式缓存。

distributed_cache_wait_connection_from_pool_milliseconds​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。如果 distributed_cache_pool_behaviour_on_limit 设置为 wait，等待从连接池接收连接的时间（以毫秒为单位）。

distributed_connections_pool_size​

允许与远程服务器建立的最大并发连接数，以便为单个 分布式表 中的所有查询进行分布式处理。我们建议设置的值不少于集群中的服务器数量。

distributed_ddl_entry_format_version​

分布式 DDL（在集群上）查询的兼容性版本。

distributed_ddl_output_mode​

设置分布式 DDL 查询结果的格式。

可能的值：

  • throw — 返回所有主机上查询执行状态的结果集。如果查询在某些主机上失败，则将重新抛出第一个异常。如果查询在某些主机上尚未完成并且 distributed_ddl_task_timeout 超过，则会抛出 TIMEOUT_EXCEEDED 异常。
  • none — 类似于 throw，但分布式 DDL 查询不返回结果集。
  • null_status_on_timeout — 如果在相应的主机上查询尚未完成，则在结果集的一些行中返回 NULL 作为执行状态，而不是抛出 TIMEOUT_EXCEEDED。
  • never_throw — 如果查询在某些主机上失败，则不抛出 TIMEOUT_EXCEEDED，也不重新抛出异常。
  • none_only_active - 类似于 none，但不等待 Replicated 数据库的非活动副本。注意：使用此模式无法判断某条查询未在某个副本上执行并将在后台执行。
  • null_status_on_timeout_only_active — 类似于 null_status_on_timeout，但不等待 Replicated 数据库的非活动副本。
  • throw_only_active — 类似于 throw，但不等待 Replicated 数据库的非活动副本。

Cloud 默认值：none。

distributed_ddl_task_timeout​

设置集群中所有主机的 DDL 查询响应的超时时间。如果在所有主机上未执行 DDL 请求，响应将包含超时错误，请求将以异步方式执行。负值表示无限制。

可能的值：

  • 正整数。
  • 0 — 异步模式。
  • 负整数 — 无限超时。

distributed_foreground_insert​

启用或禁用将数据同步插入到 Distributed 表中。

默认情况下，当往 Distributed 表中插入数据时，ClickHouse 服务器以后台模式将数据发送到集群节点。当 distributed_foreground_insert=1 时，数据将以同步方式处理，只有在所有数据都保存到所有分片上时（如果 internal_replication 为真，则每个分片至少有一个副本），INSERT 操作才会成功。

可能的值：

  • 0 — 数据以后台模式插入。
  • 1 — 数据以同步模式插入。

Cloud 默认值：1。

另见

distributed_group_by_no_merge​

在分布式查询处理中，不要合并来自不同服务器的聚合状态，在确定不同分片上有不同的键时可以使用此项。

可能的值：

  • 0 — 禁用（最终查询处理在发起节点上完成）。
  • 1 - 不要合并来自不同服务器的聚合状态进行分布式查询处理（查询完全在分片上处理，发起者仅作为数据代理），在确定不同分片上有不同的键时可以使用。
  • 2 - 与 1 相同，但在发起者上应用 ORDER BY 和 LIMIT（当查询完全在远程节点上处理时不可能，例如对于 distributed_group_by_no_merge=1）。

示例

distributed_insert_skip_read_only_replicas​

允许在将数据插入分布式时跳过只读副本的 INSERT 查询。

可能的值：

  • 0 — INSERT 按照通常方式执行，如果请求到只读副本则会失败。
  • 1 — 发起者将跳过只读副本，然后将数据发送到分片。

distributed_plan_default_reader_bucket_count​

Experimental feature. Learn more.

分布式查询的默认并行读取任务数量。任务在副本之间分配。

distributed_plan_default_shuffle_join_bucket_count​

Experimental feature. Learn more.

分布式 shuffle-hash-join 的默认桶数量。

distributed_plan_execute_locally​

Experimental feature. Learn more.

在本地运行分布式查询计划的所有任务。用于测试和调试。

distributed_plan_force_exchange_kind​

Experimental feature. Learn more.

在分布式查询阶段之间强制指定类型的 Exchange 操作符。

可能的值：

  • '' - 不强制任何类型的 Exchange 操作符，让优化器自行选择，
  • 'Persisted' - 使用对象存储中的临时文件，
  • 'Streaming' - 在网络上流交换数据。

distributed_plan_optimize_exchanges​

移除分布式查询计划中不必要的交换。禁用它以用于调试。

distributed_product_mode​

更改 分布式子查询 的行为。

当查询包含分布式表的乘积时，即当针对分布式表的查询包含非 GLOBAL 子查询时，ClickHouse 应用此设置。

限制：

  • 仅适用于 IN 和 JOIN 子查询。
  • 仅当 FROM 部分使用包含多个分片的分布式表时。
  • 如果子查询涉及的分布式表包含多个分片。
  • 不用于表值 remote 函数。

可能的值：

  • deny — 默认值。禁止使用这些类型的子查询（返回 "禁止双重分布式IN/JOIN子查询" 异常）。
  • local — 将子查询中的数据库和表替换为目标服务器（分片）的本地表，保留正常的 IN/JOIN。
  • global — 将 IN/JOIN 查询替换为 GLOBAL IN/GLOBAL JOIN。
  • allow — 允许使用这些类型的子查询。

distributed_push_down_limit​

启用或禁用 LIMIT 在每个分片上分别应用。

这将避免：

  • 在网络上传输额外的行；
  • 在发起者上处理限制后的行。

从 21.9 版本开始，您不能再获得不准确的结果，因为 distributed_push_down_limit 仅在满足以下至少一个条件时改变查询执行：

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

另见：

distributed_replica_error_cap​

  • 类型：无符号整数
  • 默认值：1000

每个副本的错误数量被限制在此值，防止单个副本累积过多错误。

另见：

distributed_replica_error_half_life​

  • 类型：秒
  • 默认值：60 秒

控制分布式表中错误被清零的速度。如果某个副本在一段时间内不可用，累计 5 个错误，并且 distributed_replica_error_half_life 设置为 1 秒，则该副本将在最后一个错误发生后 3 秒被视为正常。

另见：

distributed_replica_max_ignored_errors​

  • 类型：无符号整数
  • 默认值：0

在选择副本时将被忽略的错误数量（根据 load_balancing 算法）。

另见：

do_not_merge_across_partitions_select_final​

在 select final 中仅在一个分区中合并部分。

empty_result_for_aggregation_by_constant_keys_on_empty_set​

在对空集按常数键聚合时返回空结果。

empty_result_for_aggregation_by_empty_set​

在对空集进行无键聚合时返回空结果。

enable_adaptive_memory_spill_scheduler​

Experimental feature. Learn more.

触发处理器自适应地将数据溢出到外部存储。目前支持优雅连接。

enable_blob_storage_log​

将有关 blob 存储操作的信息写入 system.blob_storage_log 表。

enable_deflate_qpl_codec​

如果启用，DEFLATE_QPL 编解码器可用于压缩列。

enable_early_constant_folding​

启用查询优化，我们分析函数和子查询的结果，如果其中有常量则重写查询。

enable_extended_results_for_datetime_functions​

启用或禁用返回类型结果：

可能的值：

  • 0 — 函数对所有类型的参数返回 Date 或 DateTime。
  • 1 — 函数对 Date32 或 DateTime64 参数返回 Date32 或 DateTime64，对其他情况返回 Date 或 DateTime。

enable_filesystem_cache​

为远程文件系统使用缓存。此设置不会打开/关闭磁盘的缓存（必须通过磁盘配置完成），但允许在某些查询中绕过缓存。

enable_filesystem_cache_log​

允许记录每个查询的文件系统缓存日志。

enable_filesystem_cache_on_write_operations​

在写操作时写入缓存。要使此设置实际生效，必须在磁盘配置中也进行添加。

enable_filesystem_read_prefetches_log​

在查询期间记录到 system.filesystem 的预取日志。仅应在测试或调试期间使用，通常不建议默认开启。

enable_global_with_statement​

将 WITH 语句传播到 UNION 查询和所有子查询。

enable_hdfs_pread​

启用或禁用 HDFS 文件的预读取。默认情况下，使用 hdfsPread。如果禁用，则将使用 hdfsRead 和 hdfsSeek 来读取 HDFS 文件。

enable_http_compression​

启用或禁用在 HTTP 请求的响应中进行数据压缩。

有关更多信息，请参阅 HTTP 接口描述。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

enable_job_stack_trace​

在作业结果异常时输出作业创建者的堆栈跟踪。

enable_lightweight_delete​

启用针对 mergetree 表的轻量级 DELETE 变更。

enable_memory_bound_merging_of_aggregation_results​

启用内存限制合并策略以进行聚合。

enable_multiple_prewhere_read_steps​

在 WHERE 中转移多个条件到 PREWHERE，如果有多个条件通过 AND 组合，则从磁盘读取和过滤需分多步进行。

enable_named_columns_in_function_tuple​

在功能 tuple() 中生成名称唯一的元组，可以将其视为无引号标识符。

enable_optimize_predicate_expression​

在 SELECT 查询中开启谓词下推。

谓词下推可以显著减少分布式查询的网络流量。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

使用案例

考虑以下查询：

  1. SELECT count() FROM test_table WHERE date = '2018-10-10'
  2. SELECT count() FROM (SELECT * FROM test_table) WHERE date = '2018-10-10'

如果 enable_optimize_predicate_expression = 1，那么这两个查询的执行时间相等，因为 ClickHouse 在处理子查询时应用 WHERE。

如果 enable_optimize_predicate_expression = 0，则第二个查询的执行时间会更长，因为 WHERE 子句将应用于子查询完成后的所有数据。

enable_optimize_predicate_expression_to_final_subquery​

允许将谓词推送到最终子查询。

enable_order_by_all​

启用或禁用使用 ORDER BY ALL 语法进行排序，详见 ORDER BY。

可能的值：

  • 0 — 禁用 ORDER BY ALL。
  • 1 — 启用 ORDER BY ALL。

示例

查询：

结果：

enable_parsing_to_custom_serialization​

如果为 true，则数据可以直接解析为具有自定义序列化（例如 Sparse）的列，根据从表中获得的序列化提示进行处理。

enable_positional_arguments​

启用或禁用对 GROUP BY, LIMIT BY, ORDER BY 语句的支持位置参数。

可能的值：

  • 0 — 不支持位置参数。
  • 1 — 支持位置参数：可以用列号代替列名。

示例

查询：

结果：

enable_reads_from_query_cache​

如果启用，SELECT 查询的结果将从 查询缓存 中检索。

可能的值：

  • 0 - 禁用。
  • 1 - 启用。

enable_s3_requests_logging​

启用非常详细的 S3 请求日志。仅对调试有意义。

enable_scalar_subquery_optimization​

如果设置为 true，将阻止标量子查询（反序列化） 大的标量值并可能避免多次运行同一子查询。

enable_sharing_sets_for_mutations​

允许为同一变更的不同任务共享为 IN 子查询构建的集合对象。这将减少内存使用和 CPU 消耗。

enable_software_prefetch_in_aggregation​

启用在聚合中的软件预取。

enable_unaligned_array_join​

允许使用大小不同的多个数组进行 ARRAY JOIN。当此设置启用时，数组将调整大小以匹配最长的数组。

enable_url_encoding​

允许在 URL 引擎表中启用/禁用 URI 路径的解码/编码。

默认情况下禁用。

enable_vertical_final​

如果启用，在 FINAL 阶段通过将行标记为已删除并在后续阶段过滤它们来删除重复行，而不是合并行。

enable_writes_to_query_cache​

如果启用，SELECT 查询的结果将存储在 查询缓存 中。

可能的值：

  • 0 - 禁用。
  • 1 - 启用。

enable_zstd_qat_codec​

如果启用，ZSTD_QAT 编解码器可用于压缩列。

enforce_strict_identifier_format​

如果启用，仅允许包含字母数字字符和下划线的标识符。

engine_file_allow_create_multiple_files​

启用或禁用在文件引擎表中每次插入时创建新文件（如果格式的后缀为 (JSON, ORC, Parquet, 等)。如果启用，每次插入时将根据以下模式创建新文件：

data.Parquet -> data.1.Parquet -> data.2.Parquet。

可能的值：

  • 0 — INSERT 查询将新数据附加到文件末尾。
  • 1 — INSERT 查询将创建新文件。

engine_file_empty_if_not_exists​

允许在没有文件的情况下从文件引擎表中选择数据。

可能的值：

  • 0 — SELECT 抛出异常。
  • 1 — SELECT 返回空结果。

engine_file_skip_empty_files​

启用或禁用在 File 引擎表中跳过空文件。

可能的值：

  • 0 — 如果空文件与请求的格式不兼容，则 SELECT 抛出异常。
  • 1 — 对于空文件，SELECT 返回空结果。

engine_file_truncate_on_insert​

启用或禁用在 File 引擎表中插入前截断。

可能的值：

  • 0 — INSERT 查询将新数据附加到文件末尾。
  • 1 — INSERT 查询将用新数据替换文件的现有内容。

engine_url_skip_empty_files​

启用或禁用在 URL 引擎表中跳过空文件。

可能的值：

  • 0 — 如果空文件与请求的格式不兼容，则 SELECT 抛出异常。
  • 1 — 对于空文件，SELECT 返回空结果。

except_default_mode​

在 EXCEPT 查询中设置默认模式。可能的值：空字符串、'ALL'、'DISTINCT'。如果为空，未指定模式的查询将抛出异常。

external_storage_connect_timeout_sec​

连接超时时间（单位：秒）。当前仅支持 MySQL。

external_storage_max_read_bytes​

表使用外部引擎时应刷新历史数据的最大字节数限制。当前仅支持 MySQL 表引擎、数据库引擎和字典。如果设置为 0，则禁用此设置。

external_storage_max_read_rows​

表使用外部引擎时应刷新历史数据的最大行数限制。当前仅支持 MySQL 表引擎、数据库引擎和字典。如果设置为 0，则禁用此设置。

external_storage_rw_timeout_sec​

读/写超时时间（单位：秒）。当前仅支持 MySQL。

external_table_functions_use_nulls​

定义 mysql、postgresql 和 odbc 表函数如何使用 Nullable 列。

可能的值：

  • 0 — 表函数显式使用 Nullable 列。
  • 1 — 表函数隐式使用 Nullable 列。

使用

如果设置为 0，则表函数不创建 Nullable 列，而是插入默认值（而不是 NULL）。这同样适用于数组中的 NULL 值。

external_table_strict_query​

如果设置为 true，则不允许将表达式转换为外部表查询的局部过滤器。

extract_key_value_pairs_max_pairs_per_row​

extractKeyValuePairs 函数可以生成的最大配对数。作为防止占用过多内存的保护措施。

extremes​

是否计算极值（查询结果列中的最小值和最大值）。接受 0 或 1。默认值 0（禁用）。 有关更多信息，请参阅 "极值" 部分。

fallback_to_stale_replicas_for_distributed_queries​

如果没有可用的更新数据，则强制查询访问过期副本。参见 复制。

ClickHouse 从过期副本中选择最相关的数据。

在执行从指向复制表的分布式表的 SELECT 时使用。

默认值为 1（启用）。

filesystem_cache_boundary_alignment​

文件系统缓存边界对齐。此设置仅应用于非磁盘读取（例如，远程表引擎 / 表函数的缓存，但不适用于 MergeTree 表的存储配置）。值为 0 意味着没有对齐。

filesystem_cache_enable_background_download_during_fetch​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。等待时间以锁定缓存以进行空间保留在文件系统缓存中。

filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中有效。等待时间以锁定缓存以进行空间保留在文件系统缓存中。

filesystem_cache_max_download_size​

单个查询可以下载的最大远程文件系统缓存大小。

filesystem_cache_name​

用于无状态表引擎或数据湖的文件系统缓存名称

filesystem_cache_prefer_bigger_buffer_size​

如果启用了文件系统缓存，优先使用更大的缓存缓冲区以避免写入小文件段，这会降低缓存性能。另一方面，启用此设置可能会增加内存使用量。

filesystem_cache_reserve_space_wait_lock_timeout_milliseconds​

文件系统缓存中为空间预留锁定的等待时间

filesystem_cache_segments_batch_size​

从缓存中读取缓冲区请求的单个文件段的批次大小限制。值过小会导致对缓存的过度请求，值过大可能会减慢缓存的驱逐

filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit​

如果超过查询缓存大小，则跳过从远程文件系统的下载

filesystem_prefetch_max_memory_usage​

预取的最大内存使用量。

filesystem_prefetch_step_bytes​

预取的步长（以字节为单位）。零表示 auto - 将自动推断最佳预取步长，但可能不是100%最佳。实际值可能有所不同，因为设置了 filesystem_prefetch_min_bytes_for_single_read_task

filesystem_prefetch_step_marks​

预取的步长（以标记为单位）。零表示 auto - 将自动推断最佳预取步长，但可能不是100%最佳。实际值可能有所不同，因为设置了 filesystem_prefetch_min_bytes_for_single_read_task

filesystem_prefetches_limit​

预取的最大数量。零表示无限。如果你想限制预取数量，建议设置 filesystem_prefetches_max_memory_usage

final​

自动将 FINAL 修饰符应用于查询中的所有表，适用于 FINAL 的表，包括连接的表和子查询中的表，以及分布式表。

可能的值：

  • 0 - 禁用
  • 1 - 启用

示例：

flatten_nested​

设置 nested 列的数据格式。

可能的值：

  • 1 — 嵌套列展平为单独的数组。
  • 0 — 嵌套列保持为单个元组数组。

用法

如果设置为 0，可以使用任意级别的嵌套。

示例

查询：

结果：

查询：

结果：

force_aggregate_partitions_independently​

强制在适用时使用优化，但启发式决策未使用

force_aggregation_in_order​

此设置由服务器本身用于支持分布式查询。不要手动更改，因为这会破坏正常操作。（在分布式聚合期间强制在远程节点上按顺序使用聚合）。

force_data_skipping_indices​

如果未使用传递的数据跳过索引，则禁用查询执行。

考虑以下示例：

force_grouping_standard_compatibility​

使 GROUPING 函数在参数未用作聚合键时返回 1

force_index_by_date​

如果索引不能按日期使用，则禁用查询执行。

适用于 MergeTree 系列的表。

如果 force_index_by_date=1，ClickHouse 将检查查询是否有可以用于限制数据范围的日期键条件。如果没有合适的条件，它将抛出异常。然而，它不会检查该条件是否减少了要读取的数据量。例如，条件 Date != ' 2000-01-01 ' 是可接受的，即使它匹配表中的所有数据（即，运行查询需要全表扫描）。有关 MergeTree 表中数据范围的更多信息，请参阅 MergeTree。

force_optimize_projection​

启用或禁用在 SELECT 查询中强制使用 projections，当启用投影优化时（请参见 optimize_use_projections 设置）。

可能的值：

  • 0 — 投影优化不是强制性的。
  • 1 — 投影优化是强制性的。

force_optimize_projection_name​

如果设置为非空字符串，则检查此投影在查询中至少被使用一次。

可能的值：

  • 字符串：在查询中使用的投影名称

force_optimize_skip_unused_shards​

如果启用了 optimize_skip_unused_shards 且不能跳过未使用的分片，则启用或禁用查询执行。如果跳过不可用且启用此设置，则将抛出异常。

可能的值：

  • 0 — 禁用。ClickHouse 不会抛出异常。
  • 1 — 启用。只有当表具有分片键时，才禁用查询执行。
  • 2 — 启用。无论表的分片键是否定义，查询执行都被禁用。

force_optimize_skip_unused_shards_nesting​

控制 force_optimize_skip_unused_shards（因此仍然需要 force_optimize_skip_unused_shards）取决于分布式查询的嵌套级别（例如，当你有一个 Distributed 表指向另一个 Distributed 表时）。

可能的值：

  • 0 - 禁用，force_optimize_skip_unused_shards 始终生效。
  • 1 — 仅在第一级启用 force_optimize_skip_unused_shards。
  • 2 — 在第二级及以下启用 force_optimize_skip_unused_shards。

force_primary_key​

如果无法按主键索引，则禁用查询执行。

适用于 MergeTree 系列的表。

如果 force_primary_key=1，ClickHouse 将检查查询是否具有可以用于限制数据范围的主键条件。如果没有合适的条件，它将抛出异常。然而，它不会检查该条件是否减少了要读取的数据量。有关 MergeTree 表中数据范围的更多信息，请参阅 MergeTree。

force_remove_data_recursively_on_drop​

在 DROP 查询时递归删除数据。避免出现“目录不为空”错误，但可能会静默删除分离的数据

formatdatetime_e_with_space_padding​

格式化程序 '%e' 在函数 'formatDateTime' 中打印单日期以带前导空格的形式，例如 ' 2' 而不是 '2'。

formatdatetime_f_prints_scale_number_of_digits​

格式化程序 '%f' 在函数 'formatDateTime' 中仅打印 DateTime64 的规模数字，而不是固定的 6 位数字。

formatdatetime_f_prints_single_zero​

格式化程序 '%f' 在函数 'formatDateTime' 中标记如果格式化值没有小数秒，则打印单零而不是六个零。

formatdatetime_format_without_leading_zeros​

格式化程序 '%c'、'%l' 和 '%k' 在函数 'formatDateTime' 中打印月份和小时时没有前导零。

formatdatetime_parsedatetime_m_is_month_name​

格式化程序 '%M' 在函数 'formatDateTime' 和 'parseDateTime' 中打印/解析月份名称而不是分钟。

fsync_metadata​

在写 .sql 文件时启用或禁用 fsync。默认启用。

如果服务器拥有数百万个持续创建和销毁的小表，则将其禁用是有意义的。

function_implementation​

选择特定目标或变体的函数实现（实验性）。如果为空，则启用所有。

function_json_value_return_type_allow_complex​

控制 json_value 函数是否允许返回复杂类型（例如：struct、array、map）。

可能的值：

  • true — 允许。
  • false — 不允许。

function_json_value_return_type_allow_nullable​

控制 json_VALUE 函数在值不存在时是否允许返回 NULL。

可能的值：

  • true — 允许。
  • false — 不允许。

function_locate_has_mysql_compatible_argument_order​

控制函数 locate 中参数的顺序。

可能的值：

  • 0 — 函数 locate 接受参数 (haystack, needle[, start_pos])。
  • 1 — 函数 locate 接受参数 (needle, haystack, [, start_pos])（MySQL 兼容行为）

function_range_max_elements_in_block​

设置函数 range 生成的数据量的安全阈值。定义每个数据块（块中每行的数组大小总和）生成的函数的最大值。

可能的值：

  • 正整数。

另请参见

function_sleep_max_microseconds_per_block​

函数 sleep 在每个块中允许的最大微秒数。如果用户用更大的值调用它，则会抛出异常。这是一个安全阈值。

function_visible_width_behavior​

visibleWidth 行为的版本。0 - 仅计算代码点的数量；1 - 正确计算零宽度和组合字符，将全宽字符计算为二个，估算制表符宽度，计算删除字符。

geo_distance_returns_float64_on_float64_arguments​

如果 geoDistance、greatCircleDistance、greatCircleAngle 函数的四个参数都是 Float64，则返回 Float64，并在内部计算时使用双精度。在以前的 ClickHouse 版本中，这些函数始终返回 Float32。

geotoh3_argument_order​

Beta feature. Learn more.

函数 'geoToH3' 如果设置为 'lon_lat' 则接受 (lon, lat)，如果设置为 'lat_lon' 则接受 (lat, lon)。

glob_expansion_max_elements​

允许的最大地址数量（适用于外部存储、表函数等）。

grace_hash_join_initial_buckets​

Experimental feature. Learn more.

初始的 grace hash join 桶的数量

grace_hash_join_max_buckets​

Experimental feature. Learn more.

grace hash join 桶的数量限制

group_by_overflow_mode​

设置当聚合的唯一键的数量超过限制时发生的情况：

  • throw：抛出异常
  • break：停止执行查询并返回部分结果
  • any：继续聚合已进入集合的键，但不添加新键到集合中。

使用 'any' 值可以运行 GROUP BY 的近似值。这个近似值的质量取决于数据的统计性质。

group_by_two_level_threshold​

从多少数量的键开始，二级聚合开始。0 - 未设定阈值。

group_by_two_level_threshold_bytes​

从聚合状态的字节大小开始，开始使用二级聚合。0 - 未设定阈值。两级聚合在至少触发一个阈值时使用。

group_by_use_nulls​

改变 GROUP BY 子句 处理聚合键类型的方式。 当使用 ROLLUP、CUBE 或 GROUPING SETS 谓词时，某些聚合键可能不会用于生成某些结果行。 根据此设置，填充这些键的列的默认值或 NULL。

可能的值：

  • 0 — 使用聚合键类型的默认值来生成缺失值。
  • 1 — ClickHouse 以 SQL 标准所述的相同方式执行 GROUP BY。聚合键的类型转换为 Nullable。在未使用聚合键的行中，对于相应聚合键的列填充 NULL。

另请参见：

h3togeo_lon_lat_result_order​

函数 'h3ToGeo' 返回 (lon, lat) 如果为 true，否则返回 (lat, lon)。

handshake_timeout_ms​

在握手期间接收来自副本的 Hello 数据包的超时时间（以毫秒为单位）。

hdfs_create_new_file_on_insert​

启用或禁用在 HDFS 引擎表中每次插入时创建新文件。如果启用，则在每次插入时，将创建一个新的 HDFS 文件，名称类似于以下模式：

初始： data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz，等。

可能的值：

  • 0 — INSERT 查询将新数据添加到文件末尾。
  • 1 — INSERT 查询将创建新文件。

hdfs_ignore_file_doesnt_exist​

在读取某些键时，如果文件不存在，忽略文件的缺失。

可能的值：

  • 1 — SELECT 返回空结果。
  • 0 — SELECT 抛出异常。

hdfs_replication​

创建 hdfs 文件时可以指定实际的复制数量。

hdfs_skip_empty_files​

启用或禁用在 HDFS 引擎表中跳过空文件。

可能的值：

  • 0 — 如果空文件与请求的格式不兼容，则 SELECT 抛出异常。
  • 1 — 对于空文件，SELECT 返回空结果。

hdfs_throw_on_zero_files_match​

如果根据 glob 扩展规则匹配了零文件，则抛出错误。

可能的值：

  • 1 — SELECT 抛出异常。
  • 0 — SELECT 返回空结果。

hdfs_truncate_on_insert​

启用或禁用在 hdfs 引擎表中插入前截断。如果禁用，则在尝试插入时如果 HDFS 中已存在文件，将抛出异常。

可能的值：

  • 0 — INSERT 查询将新数据添加到文件末尾。
  • 1 — INSERT 查询用新数据替换文件的现有内容。

hedged_connection_timeout_ms​

Hedged 请求时建立与副本的连接超时

Beta feature. Learn more.

搜索向量相似度索引时的动态候选者列表的大小，也称为 'ef_search'。

hsts_max_age​

HSTS 的过期时间。0表示禁用 HSTS。

http_connection_timeout​

HTTP 连接超时（以秒为单位）。

可能的值：

  • 任何正整数。
  • 0 - 禁用（无限超时）。

http_headers_progress_interval_ms​

在每个指定的间隔内，勿更频繁地发送 HTTP 头 X-ClickHouse-Progress。

http_make_head_request​

http_make_head_request 设置允许在从 HTTP 读取数据时执行 HEAD 请求，以检索要读取的文件的信息，例如文件大小。默认情况下启用，在服务器不支持 HEAD 请求的情况下，可能希望禁用此设置。

http_max_field_name_size​

HTTP 头中字段名称的最大长度

http_max_field_value_size​

HTTP 头中字段值的最大长度

http_max_fields​

HTTP 头中字段的最大数量

http_max_multipart_form_data_size​

对 multipart/form-data 内容大小的限制。此设置不能从 URL 参数解析，应该在用户配置文件中设置。请注意，内容是在查询执行开始之前解析的，并在内存中创建外部表。这是对该阶段唯一有效的限制（对最大内存使用和最大执行时间的限制在读取 HTTP 表单数据时没有效果）。

http_max_request_param_data_size​

用于预定义 HTTP 请求中作为查询参数的请求数据大小的限制。

http_max_tries​

通过 http 读取的最大尝试次数。

http_max_uri_size​

设置 HTTP 请求的最大 URI 长度。

可能的值：

  • 正整数。

http_native_compression_disable_checksumming_on_decompress​

启用或禁用从客户端解压缩 HTTP POST 数据时的校验和验证。仅用于 ClickHouse 原生压缩格式（不适用于 gzip 或 deflate）。

有关更多信息，请阅读 HTTP 接口描述。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

http_receive_timeout​

HTTP 接收超时（以秒为单位）。

可能的值：

  • 任何正整数。
  • 0 - 禁用（无限超时）。

http_response_buffer_size​

在向客户端发送 HTTP 响应或刷新到磁盘（当启用 http_wait_end_of_query 时）之前在服务器内存中缓冲的字节数。

http_response_headers​

允许添加或覆盖服务器在成功查询结果中将返回的 HTTP 头。这仅影响 HTTP 接口。

如果头已经默认设置，则提供的值将覆盖它。 如果头未默认设置，则将其添加到头列表中。 由服务器默认设置并未被此设置覆盖的头将保持不变。

该设置允许将头设置为常量值。目前没有方法将头设置为动态计算的值。

名称或值不得包含 ASCII 控制字符。

如果实现了一个允许用户修改设置但同时基于返回的头做出决定的 UI 应用程序，建议将此设置限制为只读。

示例： SET http_response_headers = '{"Content-Type": "image/png"}'

http_retry_initial_backoff_ms​

重试通过 http 读取时的回退最小毫秒数

http_retry_max_backoff_ms​

重试通过 http 读取时的回退最大毫秒数

http_send_timeout​

HTTP 发送超时（以秒为单位）。

可能的值：

  • 任何正整数。
  • 0 - 禁用（无限超时）。
备注

仅适用于默认配置文件。更改需要服务器重启才能生效。

http_skip_not_found_url_for_globs​

对于 HTTP_NOT_FOUND 错误，跳过glob URLs

http_wait_end_of_query​

启用服务器端的 HTTP 响应缓冲。

http_write_exception_in_output_format​

在输出格式中写入异常以产生有效的输出。适用于 JSON 和 XML 格式。

http_zlib_compression_level​

如果 enable_http_compression = 1，则设置对 HTTP 请求响应中数据的压缩级别。

可能的值： 1 到 9 的数字。

iceberg_snapshot_id​

使用特定快照 ID 查询 Iceberg 表。

iceberg_timestamp_ms​

查询 Iceberg 表，使用在特定时间戳下的快照。

idle_connection_timeout​

在指定秒数后关闭空闲 TCP 连接的超时。

可能的值：

  • 正整数（0 - 立即关闭，0秒后）。

ignore_cold_parts_seconds​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。在 SELECT 查询中排除新数据部分，直到它们被预热（见 cache_populated_by_fetch）或达到指定的秒数。仅适用于 Replicated-/SharedMergeTree。

ignore_data_skipping_indices​

如果查询使用指定的数据跳过索引，则忽略它们。

考虑以下示例：

不忽略任何索引的查询：

忽略 xy_idx 索引：

适用于 MergeTree 系列的表。

ignore_drop_queries_probability​

如果启用，服务器将以指定的概率忽略所有 DROP 表查询（对于 Memory 和 JOIN 引擎，替换 DROP 为 TRUNCATE）。用于测试目的

ignore_materialized_views_with_dropped_target_table​

在推送到视图时忽略具有已删除目标表的物化视图

ignore_on_cluster_for_replicated_access_entities_queries​

忽略用于管理复制访问实体查询的 ON CLUSTER 子句。

ignore_on_cluster_for_replicated_named_collections_queries​

忽略用于管理复制命名集合查询的 ON CLUSTER 子句。

ignore_on_cluster_for_replicated_udf_queries​

忽略用于管理复制 UDF 查询的 ON CLUSTER 子句。

implicit_select​

允许在不使用前导 SELECT 关键字的情况下编写简单的 SELECT 查询，这样可以简单用于计算器样式的用法，例如 1 + 2 成为有效查询。

在 clickhouse-local 中，它默认启用并可以显式禁用。

implicit_table_at_top_level​

如果不为空，顶层不带 FROM 的查询将从该表中读取，而不是 system.one。

这在 clickhouse-local 中用于输入数据处理。 此设置可以由用户显式设置，但并不打算用于这种类型的使用。

子查询不受此设置的影响（无论是标量、FROM 还是 IN 子查询）。 在 UNION、INTERSECT、EXCEPT 链的顶层处的 SELECT 被统一对待并受此设置影响，无论它们在括号中的分组如何。 此设置如何影响视图和分布式查询并未指定。

该设置接受一个表名（然后从当前数据库解析表）或以 'database.table' 形式的限定名称。 数据库和表名称必须未加引号 - 只能使用简单标识符。

implicit_transaction​

Experimental feature. Learn more.

如果启用并且还没有处于事务中，则将查询包装在完整事务中（开始 + 提交或回滚）

input_format_parallel_parsing​

启用或禁用有序并行解析数据格式。仅支持 TSV、TSKV、CSV 和 JSONEachRow 格式。

可能的值：

  • 1 — 启用。
  • 0 — 禁用。

insert_allow_materialized_columns​

如果设置启用，允许在 INSERT 中使用物化列。

insert_deduplicate​

启用或禁用 INSERT 的块去重（适用于 Replicated* 表）。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

默认情况下，通过 INSERT 语句插入到复制表的块会进行去重（请参见 数据复制）。 对于复制表，默认情况下，每个分区只有最近的 100 个块会被去重（请参见 replicated_deduplication_window、replicated_deduplication_window_seconds）。 对于非复制表，请参见 non_replicated_deduplication_window。

insert_deduplication_token​

该设置允许用户提供自己在 MergeTree/ReplicatedMergeTree 中的去重语义。 例如，通过在每个 INSERT 语句中提供唯一值，用户可以避免重复插入的数据被去重。

可能的值：

  • 任何字符串

insert_deduplication_token 仅在不为空时用于去重。

对于复制表，默认情况下，每个分区只有最近的 100 个插入会被去重（请参见 replicated_deduplication_window、replicated_deduplication_window_seconds）。 对于非复制表，请参见 non_replicated_deduplication_window。

备注

insert_deduplication_token 在分区级别有效（和 insert_deduplication 校验和相同）。多个分区可以具有相同的 insert_deduplication_token。

示例：

insert_keeper_fault_injection_probability​

在插入过程中，keeper 请求的失败的近似概率。有效值范围为 [0.0f, 1.0f]

insert_keeper_fault_injection_seed​

0 - 随机种子，否则为设置的值

insert_keeper_max_retries​

该设置设定了在插入到副本 MergeTree 时 ClickHouse Keeper（或 ZooKeeper）请求的最大重试次数。只有由于网络错误、Keeper 会话超时或请求超时而导致的 Keeper 请求才会被考虑进行重试。

可能的值：

  • 正整数。
  • 0 — 禁用重试。

云默认值： 20。

Keeper 请求的重试在某个超时后进行。超时由以下设置控制： insert_keeper_retry_initial_backoff_ms， insert_keeper_retry_max_backoff_ms。第一次重试在 insert_keeper_retry_initial_backoff_ms 超时后进行。后续的超时将按照如下计算：

例如，如果 insert_keeper_retry_initial_backoff_ms=100， insert_keeper_retry_max_backoff_ms=10000 和 insert_keeper_max_retries=8，则超时将为 100, 200, 400, 800, 1600, 3200, 6400, 10000。

除了容错机制外，重试还致力于提供更好的用户体验——它们可以避免在 INSERT 执行时返回错误，例如在 Keeper 因升级而重启时。

insert_keeper_retry_initial_backoff_ms​

在 INSERT 查询执行过程中，重试失败的 Keeper 请求的初始超时（以毫秒为单位）。

可能的值：

  • 正整数。
  • 0 — 无超时。

insert_keeper_retry_max_backoff_ms​

在 INSERT 查询执行过程中，重试失败的 Keeper 请求的最大超时（以毫秒为单位）。

可能的值：

  • 正整数。
  • 0 — 最大超时没有限制。

insert_null_as_default​

启用或禁用在不 nullable 数据类型的列中插入 default values 代替 NULL。如果列类型为非可空类型且此设置被禁用，则插入 NULL 会引发异常。如果列类型为可空类型，则无论此设置如何， NULL 值将原样插入。

此设置适用于 INSERT ... SELECT 查询。注意 SELECT 子查询可以与 UNION ALL 子句连接。

可能的值：

  • 0 — 向非可空列插入 NULL 会引发异常。
  • 1 — 将默认列值插入而不是 NULL。

insert_quorum​

备注

此设置不适用于 SharedMergeTree，请参阅 SharedMergeTree consistency 以获取更多信息。

启用法定人数写入。

  • 如果 insert_quorum < 2，则禁用法定人数写入。
  • 如果 insert_quorum >= 2，则启用法定人数写入。
  • 如果 insert_quorum = 'auto'，则使用大多数数量（number_of_replicas / 2 + 1）作为法定人数。

法定人数写入

只有当 ClickHouse 成功将数据正确写入 insert_quorum 个副本时， INSERT 才会成功，在 insert_quorum_timeout 内。如果出于任何原因，成功写入的副本的数量没有达到 insert_quorum，则写入将被视为失败，ClickHouse 将从所有已写入数据的副本中删除插入的块。

当 insert_quorum_parallel 被禁用时，法定人数中的所有副本是一致的，即它们包含所有先前 INSERT 查询的数据（INSERT 序列是线性的）。在读取使用 insert_quorum 写入的数据时，如果 insert_quorum_parallel 被禁用，可以使用 select_sequential_consistency 将 SELECT 查询的顺序一致性打开。

ClickHouse 会生成异常：

  • 如果查询时可用副本的数量少于 insert_quorum。
  • 当 insert_quorum_parallel 被禁用并尝试写入数据时，如果先前的块尚未插入到 insert_quorum 的副本中。用户在前一个 INSERT 使用 insert_quorum 完成之前尝试对同一表执行另一个 INSERT 查询时，可能会发生这种情况。

另请参见：

insert_quorum_parallel​

备注

此设置不适用于 SharedMergeTree，请参阅 SharedMergeTree consistency 以获取更多信息。

启用或禁用法定人数 INSERT 查询的并行性。如果启用，可以在先前的查询尚未完成时发送额外的 INSERT 查询。如果禁用，则拒绝对同一表的额外写入。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

另请参见：

insert_quorum_timeout​

写入法定人数超时时间（以毫秒为单位）。如果超时已过去且尚未发生写入，ClickHouse 将生成异常，客户端必须重复查询以将同一块写入同一或任意其他副本。

另请参见：

insert_shard_id​

如果不是 0，则指定要同步插入数据的 Distributed 表的分片。

如果 insert_shard_id 值不正确，服务器将抛出异常。

要获取 requested_cluster 中的分片数量，您可以检查服务器配置或使用以下查询：

可能的值：

  • 0 — 禁用。
  • 从 1 到相应的 Distributed 表的 shards_num 的任何数字。

例子

查询：

结果：

interactive_delay​

检查请求执行是否已被取消以及发送进度的间隔，单位为微秒。

intersect_default_mode​

在 INTERSECT 查询中设置默认模式。可能的值：空字符串，'ALL'， 'DISTINCT'。如果为空，未指定模式的查询将抛出异常。

join_algorithm​

指定使用哪个 JOIN 算法。

可以指定多个算法，并将根据种类/严格性和表引擎选择可用的算法以供特定查询使用。

可能的值：

  • grace_hash

Grace hash join 被使用。Grace hash 提供了一种算法选项，可以在保持内存使用限制的同时提供高效的复杂连接。

Grace join 的第一阶段读取右表，并根据关键列的哈希值将其划分为 N 个桶（最初， N 为 grace_hash_join_initial_buckets）。这样做的目的是确保每个桶可以独立处理。第一个桶中的行被添加到内存哈希表中，而其他行则保存在磁盘上。如果哈希表的大小超过内存限制（例如，由 max_bytes_in_join 设置），则增加桶的数量并重新分配每行的桶。任何不属于当前桶的行都会被冲洗并重新分配。

支持 INNER/LEFT/RIGHT/FULL ALL/ANY JOIN。

  • hash

Hash join algorithm 被使用。这是最通用的实现，支持所有种类和严格性及多个连接键在 JOIN ON 部分通过 OR 组合。

使用 hash 算法时， JOIN 的右侧部分被加载到 RAM 中。

  • parallel_hash

hash 连接的一种变体，将数据分为桶，并同时构建多个哈希表以加速该过程。

使用 parallel_hash 算法时， JOIN 的右侧部分被加载到 RAM 中。

  • partial_merge

一种 sort-merge algorithm 的变体，其中只有右表是完全排序的。

RIGHT JOIN 和 FULL JOIN 仅支持 ALL 严格性（不支持 SEMI， ANTI， ANY 和 ASOF）。

使用 partial_merge 算法时，ClickHouse 对数据进行排序并将其转储到磁盘。ClickHouse 中的 partial_merge 算法与经典实现略有不同。首先，ClickHouse 按连接键将右表按块排序并为已排序的块创建 min-max 索引。然后，它按 join key 排序左表的部分，并与右表进行连接。min-max 索引也用于跳过不需要的右表块。

  • direct

该算法可在右表的存储支持键值请求时应用。

direct 算法使用左表的行作为键在右表中执行查找。仅支持特殊存储，如 Dictionary 或 EmbeddedRocksDB，且仅支持 LEFT 和 INNER JOIN。

  • auto

当设置为 auto 时，会先尝试 hash 连接，并在违反内存限制时动态切换到其他算法。

  • full_sorting_merge

对连接表执行全排序的 Sort-merge algorithm。

  • prefer_partial_merge

ClickHouse 始终尝试使用 partial_merge 连接，如果不可能，则使用 hash。已弃用，与 partial_merge,hash 相同。

  • default (deprecated)

过时的值，请不要再使用。 与 direct,hash 相同，即尝试先使用 direct 连接，然后使用 hash 连接（按此顺序）。

join_any_take_last_row​

更改 ANY 严格性连接操作的行为。

备注

此设置仅适用于 Join 引擎表的 JOIN 操作。

可能的值：

  • 0 — 如果右表有多条匹配行，则只连接找到的第一条。
  • 1 — 如果右表有多条匹配行，则只连接找到的最后一条。

另请参见：

join_default_strictness​

为 JOIN 子句 设置默认严格性。

可能的值：

  • ALL — 如果右表有多条匹配行，ClickHouse 会从匹配行中创建一个 Cartesian product。这是标准 SQL 中的正常 JOIN 行为。
  • ANY — 如果右表有多条匹配行，则只连接找到的第一条。如果右表仅有一条匹配行，则 ANY 和 ALL 的结果相同。
  • ASOF — 用于不确定匹配的序列连接。
  • 空字符串 — 如果查询中未指定 ALL 或 ANY，ClickHouse 将抛出异常。

join_on_disk_max_files_to_merge​

限制在执行磁盘上的 MergeJoin 操作时并行排序允许的文件数量。

该设置的值越大，使用的 RAM 越多，而所需的磁盘 I/O 越少。

可能的值：

  • 从 2 开始的任何正整数。

join_output_by_rowlist_perkey_rows_threshold​

在右表中每个键的平均行数的下限，以确定在哈希连接中是否按行列表输出。

join_overflow_mode​

定义当达到以下任一连接限制时 ClickHouse 执行的操作：

可能的值：

  • THROW — ClickHouse 抛出异常并中断操作。
  • BREAK — ClickHouse 中断操作但不抛出异常。

默认值： THROW。

另请参见

join_to_sort_maximum_table_rows​

Experimental feature. Learn more.

右表中的最大行数，以确定是否在左或内连接中通过键对右表进行重新排列。

join_to_sort_minimum_perkey_rows​

Experimental feature. Learn more.

右表中每个键的平均行数的下限，以确定在左或内连接中是否通过键对右表进行重新排列。此设置确保不对稀疏表键应用优化。

join_use_nulls​

设置 JOIN 行为的类型。在合并表时，可能会出现空单元格。ClickHouse 根据此设置以不同方式填充它们。

可能的值：

  • 0 — 空单元格用相应字段类型的默认值填充。
  • 1 — JOIN 的行为与标准 SQL 相同。相应字段的类型转换为 Nullable，空单元格用 NULL 填充。

joined_subquery_requires_alias​

强制连接子查询和表函数具有别名以进行正确的名称限定。

kafka_disable_num_consumers_limit​

禁用针对可用 CPU 核心数量的 kafka_num_consumers 限制。

kafka_max_wait_ms​

从 Kafka 读取消息之前的等待时间（以毫秒为单位）。

可能的值：

  • 正整数。
  • 0 — 无限超时。

另请参见：

keeper_map_strict_mode​

在 KeeperMap 操作期间执行额外检查。例如，在尝试插入已存在的键时抛出异常。

keeper_max_retries​

一般 Keeper 操作的最大重试次数。

keeper_retry_initial_backoff_ms​

一般 Keeper 操作的初始回退超时。

keeper_retry_max_backoff_ms​

一般 Keeper 操作的最大回退超时。

least_greatest_legacy_null_behavior​

如果启用，函数 'least' 和 'greatest' 如果其任一参数为 NULL 则返回 NULL。

legacy_column_name_of_tuple_literal​

在大型元组文字中列出其列名的所有元素名称，而不是哈希。此设置仅用于兼容性原因。在将集群从低于 21.7 的版本滚动更新到更高版本时，设置为 'true' 是有意义的。

lightweight_delete_mode​

作为轻量级删除一部分执行的内部更新查询模式。

可能的值：

  • alter_update - 运行创建重负载变更的 ALTER UPDATE 查询。
  • lightweight_update - 如果可能运行轻量级更新，否则运行 ALTER UPDATE。
  • lightweight_update_force - 如果可能运行轻量级更新，否则抛出异常。

lightweight_deletes_sync​

与 mutations_sync 相同，但仅控制轻量级删除的执行。

可能的值：

  • 0 - 变更异步执行。
  • 1 - 查询在当前服务器上等待轻量级删除完成。
  • 2 - 查询等待所有副本（如果存在）上的轻量级删除完成。

另请参见

limit​

设置从查询结果获取的最大行数。它调整由 LIMIT 子句设置的值，因此查询中指定的限制不能超过由此设置设置的限制。

可能的值：

  • 0 — 行数没有限制。
  • 正整数。

live_view_heartbeat_interval​

Experimental feature. Learn more.

在秒为单位的心跳间隔，以指示实时查询仍然活着。

load_balancing​

指定用于分布式查询处理的副本选择算法。

ClickHouse 支持以下选择副本的算法：

另请参见：

随机（默认）​

每个副本的错误数量被计数。查询被发送到错误最少的副本，如果有多个副本，则发送到其中任何一个。 缺点：未考虑服务器邻近性；如果副本有不同的数据，您也会得到不同的数据。

最近的主机名​

每个副本的错误数量被计数。每 5 分钟，错误数量被整体除以 2。这样，错误数量是基于最近时间的指数平滑计算的。如果有一个副本的错误数量最少（即最近在其他副本上发生了错误），查询将发送到该副本。如果有多个副本的错误数量相同，查询将发送到配置文件中主机名与服务器主机名最相似的副本（在相同位置有不同字符数量，最多等于两个主机名的最小长度）。

例如，example01-01-1 和 example01-01-2 在一个位置不同，而 example01-01-1 和 example01-02-2 在两个位置不同。 这种方法可能看起来简单，但是它不需要网络拓扑的外部数据，也不比较 IP 地址，这在我们的 IPv6 地址中会很复杂。

因此，如果存在等效副本，首选名称相似度最高的副本。 我们还可以假设在没有故障的情况下，向同一服务器发送查询时，分布式查询也将发送到相同的服务器。因此，即使副本中放置了不同的数据，查询返回的结果仍然大致相同。

主机名编辑距离​

与 nearest_hostname 类似，但它以 编辑距离 的方式比较主机名。例如：

按顺序​

具有相同错误数量的副本以配置中指定的顺序访问。 当确切知道哪个副本更可取时，此方法是合适的。

第一个或随机​

该算法选择设置中的第一个副本或随机副本，如果第一个不可用。在交叉复制作拓扑设置中有效，但在其他配置中没有用。

first_or_random 算法解决了 in_order 算法的问题。通过 in_order，如果一个副本关闭，下一个副本将承受双重负担，而其他副本处理常规流量。当使用 first_or_random 算法时，负载将在仍然可用的副本之间均匀分配。

可以使用设置 load_balancing_first_offset 明确指定第一个副本。这使得在副本之间重新平衡查询工作负载具有更大的控制权。

轮询​

该算法在错误数量相同的副本之间使用轮询策略（仅计入具有 round_robin 策略的查询）。

load_balancing_first_offset​

在使用 FIRST_OR_RANDOM 负载均衡策略时，首选将查询发送到哪个副本。

load_marks_asynchronously​

异步加载 MergeTree 标记。

local_filesystem_read_method​

从本地文件系统读取数据的方法之一：read、pread、mmap、io_uring、pread_threadpool。

'io_uring' 方法是实验性的，不适用于 Log、TinyLog、StripeLog、File、Set 和 Join 等在并发读取和写入时具有追加文件的表。 如果您在互联网上阅读有关 'io_uring' 的各种文章，请不要被其迷惑。除非是在大量小 IO 请求的情况下，这种读取文件方法并不是更好的方法，而这在 ClickHouse 中并不是这种情况。没有理由启用 'io_uring'。

local_filesystem_read_prefetch​

在从本地文件系统读取数据时应使用预提取。

lock_acquire_timeout​

定义锁定请求等待失败的时间（以秒为单位）。

锁定超时用于在执行带有表的读/写操作时防止死锁。当超时到期且锁定请求失败时，ClickHouse 服务器会抛出异常 "锁定尝试超时！可能已避免死锁。客户端应重试。"，错误代码为 DEADLOCK_AVOIDED。

可能的值：

  • 正整数（以秒为单位）。
  • 0 — 无锁定超时。

log_comment​

指定 system.query_log 表的 log_comment 字段的值及服务器日志的注释文本。

它可以用于提高服务器日志的可读性。此外，它有助于从运行 clickhouse-test 后在 system.query_log 中选择与测试相关的查询。

可能的值：

  • 任何长度不超过 max_query_size 的字符串。如果超过了 max_query_size，服务器将抛出异常。

例子

查询：

结果：

log_formatted_queries​

允许将格式化查询记录到 system.query_log 系统表中（填充 formatted_query 列到 system.query_log）。

可能的值：

  • 0 — 系统表中不记录格式化查询。
  • 1 — 系统表中记录格式化查询。

log_processors_profiles​

将处理器在执行/等待数据期间花费的时间写入 system.processors_profile_log 表。

另请参见：

log_profile_events​

将查询性能统计信息记录到 query_log、query_thread_log 和 query_views_log 中。

log_queries​

设置查询日志记录。

使用此设置发送到 ClickHouse 的查询将根据 query_log 服务器配置参数中的规则进行记录。

示例：

log_queries_cut_to_length​

如果查询长度超过指定的阈值（以字节为单位），则在写入查询日志时切割查询。还限制普通文本日志中打印的查询长度。

log_queries_min_query_duration_ms​

如果启用（非零），则执行速度快于此设置值的查询将不会被记录（您可以将其视为 MySQL Slow Query Log 的 long_query_time），这基本上意味着您将不会在以下表中找到它们：

  • system.query_log
  • system.query_thread_log

只有以下类型的查询会进入日志：

  • QUERY_FINISH

  • EXCEPTION_WHILE_PROCESSING

  • 类型：毫秒

  • 默认值：0（任何查询）。

log_queries_min_type​

query_log 最小类型的日志。

可能的值：

  • QUERY_START (=1)
  • QUERY_FINISH (=2)
  • EXCEPTION_BEFORE_START (=3)
  • EXCEPTION_WHILE_PROCESSING (=4)

可以用来限制哪些条目会进入 query_log，例如如果您只对错误感兴趣，则可以使用 EXCEPTION_WHILE_PROCESSING：

log_queries_probability​

允许用户以指定概率仅随机写入 query_log、query_thread_log 和 query_views_log 系统表中的一部分查询。这有助于在每秒查询量大时减少负载。

可能的值：

  • 0 — 查询不记录在系统表中。
  • 0 到 1 之间的正浮点数。例如，如果设置值为 0.5，大约一半的查询将记录在系统表中。
  • 1 — 所有查询都记录在系统表中。

log_query_settings​

将查询设置记录到 query_log 和 OpenTelemetry span 日志中。

log_query_threads​

设置查询线程日志记录。

查询线程记录到 system.query_thread_log 表中。仅当 log_queries 为真时，使用此设置启动的 ClickHouse 查询线程将根据 query_thread_log 服务器配置参数中的规则进行记录。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

示例

log_query_views​

设置查询视图日志记录。

当 ClickHouse 运行的查询与此设置启用时关联的视图（物化视图或实时视图）会在 query_views_log 服务器配置参数中记录。

示例：

low_cardinality_allow_in_native_format​

允许或限制在 Native 格式中使用 LowCardinality 数据类型。

如果限制使用 LowCardinality，ClickHouse 服务器将在 SELECT 查询中将 LowCardinality 列转换为普通列，并在 INSERT 查询中将普通列转换为 LowCardinality 列。

此设置主要用于不支持 LowCardinality 数据类型的第三方客户端。

可能的值：

  • 1 — 不限制使用 LowCardinality。
  • 0 — 限制使用 LowCardinality。

low_cardinality_max_dictionary_size​

设置可以写入存储文件系统的 LowCardinality 数据类型共享全局字典的最大行数。此设置防止字典无限增长而出现内存问题。 ClickHouse 将以普通方法写入因最大字典大小限制而无法编码的所有数据。

可能的值：

  • 任何正整数。

low_cardinality_use_single_dictionary_for_part​

启用或禁用对数据部分使用单个字典。

默认情况下，ClickHouse 服务器监控字典的大小，如果字典溢出，则服务器开始写入下一个字典。要禁止为数据部分创建多个字典，请设置 low_cardinality_use_single_dictionary_for_part = 1。

可能的值：

  • 1 — 禁止为数据部分创建多个字典。
  • 0 — 不禁止为数据部分创建多个字典。

low_priority_query_wait_time_ms​

Beta feature. Learn more.

当查询优先级机制被应用时（参见设置 priority），低优先级查询会等待高优先级查询完成。此设置指定等待的持续时间。

make_distributed_plan​

Experimental feature. Learn more.

生成分布式查询计划。

materialize_skip_indexes_on_insert​

如果INSERT操作构建并存储跳过索引。如果禁用，跳过索引将在合并时构建和存储或通过显式 MATERIALIZE INDEX。

materialize_statistics_on_insert​

如果INSERT操作构建并插入统计数据。如果禁用，统计信息将在合并时构建和存储或通过显式 MATERIALIZE STATISTICS。

materialize_ttl_after_modify​

在ALTER MODIFY TTL 查询后，对旧数据应用生存时间（TTL）。

materialized_views_ignore_errors​

允许忽略物化视图的错误，并将原始块传递到表中，而不管物化视图的情况。

max_analyze_depth​

解释器执行的最大分析次数。

max_ast_depth​

查询语法树的最大嵌套深度。如果超出，则抛出异常。

备注

此时，这个检查只在解析之后而非解析期间进行。 这意味着在解析期间可以生成一个过深的语法树， 但查询将失败。

max_ast_elements​

查询语法树中元素的最大数量。如果超出，则抛出异常。

备注

此时，这个检查只在解析之后而非解析期间进行。 这意味着在解析期间可以生成一个过深的语法树， 但查询将失败。

max_autoincrement_series​

由 generateSeriesID 函数创建的序列的最大数量。

由于每个序列代表 Keeper 中的一个节点，建议不超过几百万个序列。

max_backup_bandwidth​

特定备份的最大读取速度（字节/秒）。零表示无限制。

max_block_size​

在 ClickHouse 中，数据通过块处理，块是一组列部分。单个块的内部处理周期是高效的，但处理每个块时会产生明显的成本。

max_block_size 设置指示在从表加载数据时，单个块中应包含的最大行数。大小为 max_block_size 的块并不总是从表中加载：如果 ClickHouse 确定需要检索的数据量较少，则处理较小的块。

块大小不应太小，以避免在处理每个块时产生明显的成本。也不应太大，以确保在处理第一个块后带有 LIMIT 子句的查询快速执行。设置 max_block_size 时，目标应避免在多个线程中提取大量列时消耗过多内存，并尽量保持一定的缓存局部性。

max_bytes_before_external_group_by​

云默认值：每个副本内存量的一半。

使能或禁用在外部内存中执行 GROUP BY 子句。 （参见 外部内存中的 GROUP BY）

可能值：

  • 单个 GROUP BY 操作可以使用的最大 RAM 量（字节）。
  • 0 — 禁用外部内存中的 GROUP BY。
备注

如果在 GROUP BY 操作期间的内存使用超过此字节阈值， 则激活“外部聚合”模式（溢出数据到磁盘）。

推荐值是可用系统内存的一半。

max_bytes_before_external_sort​

云默认值：每个副本内存量的一半。

使能或禁用在外部内存中执行 ORDER BY 子句。查看 ORDER BY 实现细节 如果 ORDER BY 操作期间的内存使用超过此字节阈值，则激活“外部排序”模式（溢出数据到磁盘）。

可能值：

  • 单个 ORDER BY 操作可以使用的最大 RAM 量（字节）。 推荐值是可用系统内存的一半。
  • 0 — 禁用外部内存中的 ORDER BY。

max_bytes_before_remerge_sort​

在带有 LIMIT 的 ORDER BY 情况下，当内存使用高于指定阈值时，在最终合并之前执行附加的块合并步骤，以确保仅保留顶部 LIMIT 行。

max_bytes_in_distinct​

使用 DISTINCT 时，哈希表的状态的最大字节数（以未压缩字节计算）。

max_bytes_in_join​

在连接表时使用的哈希表的最大字节数。

此设置适用于 SELECT ... JOIN 操作和 Join 表引擎。

如果查询包含连接，ClickHouse 会检查此设置的每个中间结果。

当达到限制时，ClickHouse 可以执行不同的操作。使用 join_overflow_mode 设置来选择操作。

可能值：

  • 正整数。
  • 0 — 禁用内存控制。

max_bytes_in_set​

从子查询创建的 IN 子句中使用的集合的最大字节数（未压缩数据）。

max_bytes_ratio_before_external_group_by​

允许用于 GROUP BY 的可用内存比例。一旦达到此比例， 将使用外部内存进行聚合。

例如，如果设置为 0.6，GROUP BY 将允许在执行开始时使用可用内存的 60%（对于服务器/用户/合并）， 之后将开始使用外部聚合。

max_bytes_ratio_before_external_sort​

允许用于 ORDER BY 的可用内存比例。一旦达到此比例， 将使用外部排序。

例如，如果设置为 0.6，ORDER BY 将允许在执行开始时使用可用内存的 60%（对于服务器/用户/合并）， 之后将开始使用外部排序。

max_bytes_to_read​

执行查询时可以从表中读取的最大字节数（未压缩数据）。 此限制适用于每个处理过的数据块，只适用于最深的表表达式，并且在从远程服务器读取时，仅在远程服务器上检查。

max_bytes_to_read_leaf​

在执行分布式查询时可以从叶节点的本地表中读取的最大字节数（未压缩数据）。虽然分布式查询可以针对每个分片（叶子）发出多个子查询 - 但是这个限制只会在叶节点的读取阶段检查，在合并结果的根节点阶段将被忽略。

例如，一个集群包含 2 个分片，每个分片包含 100 字节的数据。一个声称要从两个表中读取所有数据的分布式查询，如果设置为 max_bytes_to_read=150 将失败，因为总计为 200 字节。一个针对 max_bytes_to_read_leaf=150 的查询将成功，因叶节点最多只读取 100 字节。

此限制适用于每个处理过的数据块。

备注

此设置在 prefer_localhost_replica=1 时不稳定。

max_bytes_to_sort​

在排序之前的最大字节数。如果要处理的未压缩字节数超过指定的数量，ORDER BY 操作的行为将由 sort_overflow_mode 决定，默认设置为 throw。

max_bytes_to_transfer​

在执行 GLOBAL IN/JOIN 部分时，可以传递到远程服务器或保存在临时表中的最大字节数（未压缩数据）。

max_columns_to_read​

可以从表中在单个查询中读取的最大列数。 如果查询需要读取的列数超过指定的数量，则会抛出异常。

提示

此设置可用于防止过于复杂的查询。

0 值表示无限制。

max_compress_block_size​

在写入表之前对未压缩数据块的最大大小。默认值为 1,048,576（1 MiB）。指定较小的块大小一般会导致压缩率略微降低，由于缓存局部性，压缩和解压缩速度会略微增加，同时内存消耗也会减少。

备注

这是一个专家级设置，如果你刚开始使用 ClickHouse，建议不要更改此设置。

不要将压缩块（由字节组成的内存块）与用于查询处理的块（来自表的一组行）混淆。

max_concurrent_queries_for_all_users​

如果此设置的值小于或等于当前并发处理的查询数量，则抛出异常。

示例：将 max_concurrent_queries_for_all_users 设置为 99，以便所有用户使用，而数据库管理员可以将其设置为 100，以便在服务器过载时执行调查查询。

为一个查询或用户修改设置不会影响其他查询。

可能值：

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

示例

另请参见

max_concurrent_queries_for_user​

每个用户同时处理的查询的最大数量。

可能值：

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

示例

max_distributed_connections​

每个查询对单个分布式表与远程服务器的最大同时连接数。建议设置的值不少于集群中的服务器数量。

以下参数仅在创建分布式表（和启动服务器）时使用，因此在运行时没有理由更改它们。

max_distributed_depth​

限制 Distributed 表的递归查询的最大深度。

如果超过此值，服务器将抛出异常。

可能值：

  • 正整数。
  • 0 — 无限深度。

max_download_buffer_size​

每个线程的并行下载（例如，对于 URL 引擎）的最大缓冲区大小。

max_download_threads​

下载数据的最大线程数（例如，针对 URL 引擎）。

max_estimated_execution_time​

查询预估的最大执行时间（秒）。在每个数据块上检查， 当 timeout_before_checking_execution_speed 到期时。

max_execution_speed​

每秒执行的最大行数。当 timeout_before_checking_execution_speed 到期时，在每个数据块上检查。如果执行速度过高，则执行速度将降低。

max_execution_speed_bytes​

每秒执行的最大字节数。当 timeout_before_checking_execution_speed 到期时，在每个数据块上检查。如果执行速度过高，则执行速度将降低。

max_execution_time​

查询的最大执行时间（秒）。

max_execution_time 参数可能有些复杂。它相对于当前查询执行速度的插值操作（这一行为由 timeout_before_checking_execution_speed 控制）。

ClickHouse 将中断查询，如果预计的执行时间超过指定的 max_execution_time。默认情况下，timeout_before_checking_execution_speed 被设置为 10 秒。这意味着在查询执行 10 秒后，ClickHouse 将开始估算总执行时间。例如，如果 max_execution_time 设置为 3600 秒（1 小时），如果预计的时间超过 3600 秒的限制，ClickHouse 将终止该查询。如果您将 timeout_before_checking_execution_speed 设置为 0，ClickHouse 将基于时钟时间作为 max_execution_time。

如果查询运行时间超过指定的秒数，则行为将由 timeout_overflow_mode 决定，默认设置为 throw。

备注

超时只会在数据处理的特定位置进行检查，查询只能在这些位置停止。 目前无法在合并聚合状态或查询分析期间停止，实际运行时间将高于此设置的值。

max_execution_time_leaf​

语义上类似于 max_execution_time，但仅适用于分布式或远程查询的叶节点。

例如，如果我们想在叶节点上将执行时间限制为 10s，而在初始节点上没有限制，而不是在嵌套子查询的设置中有 max_execution_time：

我们可以将 max_execution_time_leaf 用作查询设置：

max_expanded_ast_elements​

扩展别名和星号后查询语法树的最大节点数。

max_fetch_partition_retries_count​

从另一主机提取分区时的重试次数。

max_final_threads​

设置具有 FINAL 修饰符的 SELECT 查询的数据读取阶段的最大并行线程数。

可能值：

  • 正整数。
  • 0 或 1 — 禁用。SELECT 查询将在单个线程中执行。

max_http_get_redirects​

允许的最大 HTTP GET 重定向跳数。确保采取额外的安全措施，以防止恶意服务器将您的请求重定向到意外服务。\n\n 当外部服务器重定向到另一个地址，而该地址看似属于公司的基础设施时，就会出现这种情况，通过向内部服务器发送 HTTP 请求，您可以从内部网络请求内部 API，绕过身份验证，甚至查询其他服务，如 Redis 或 Memcached。当您没有内部基础设施（包括在本地主机上运行的东西）或您信任服务器时，允许重定向是安全的。尽管请记住，如果 URL 使用 HTTP 而非 HTTPS，您将不仅需要信任远程服务器，还需要信任您的 ISP 及中间路径上的每个网络。

max_hyperscan_regexp_length​

定义 hyperscan 多匹配函数 中每个正则表达式的最大长度。

可能值：

  • 正整数。
  • 0 - 长度不受限制。

示例

查询：

结果：

查询：

结果：

另请参见

max_hyperscan_regexp_total_length​

设置每个 hyperscan多匹配函数 中所有正则表达式的最大总长度。

可能值：

  • 正整数。
  • 0 - 长度不受限制。

示例

查询：

结果：

查询：

结果：

另请参见

max_insert_block_size​

插入到表中的区块大小（以行数计）。此设置仅在服务器形成块的情况下适用。例如，对于通过 HTTP 接口的 INSERT，服务器解析数据格式并形成指定大小的块。但是，当使用 clickhouse-client 时，客户端自己解析数据，服务器上的 'max_insert_block_size' 设置不影响插入块的大小。使用 INSERT SELECT 时，该设置也没有用，因为数据使用 SELECT 后形成的相同块插入。

默认值略高于 max_block_size。这样做的原因是某些表引擎（*MergeTree）会为每个插入的块在磁盘上形成一部分数据，这是一种相对较大的实体。同时，*MergeTree 表在插入期间会对数据进行排序，足够大的块大小允许在 RAM 中对更多数据进行排序。

max_insert_delayed_streams_for_parallel_write​

延迟最终部分刷新上的最大流（列）数。默认值 - 自动（在底层存储支持并行写时为 100，否则禁用）

max_insert_threads​

执行 INSERT SELECT 查询的最大线程数。

可能值：

  • 0（或 1） — INSERT SELECT 不进行并行执行。
  • 正整数。大于 1。

云默认值：从 2 到 4，根据服务规模不同而不同。

并行 INSERT SELECT 仅在 SELECT 部分并行执行时有效，参见 max_threads 设置。 较高的值将导致更高的内存使用。

max_joined_block_size_rows​

JOIN 结果的最大块大小（如果连接算法支持此功能）。0 表示无限制。

max_limit_for_vector_search_queries​

Beta feature. Learn more.

LIMIT 大于此设置的 SELECT 查询无法使用向量相似度索引。帮助防止在向量相似度索引中发生内存溢出。

max_live_view_insert_blocks_before_refresh​

Experimental feature. Learn more.

限制插入块的最大数量，超过该数量后，合并块将被丢弃并重新执行查询。

max_local_read_bandwidth​

本地读取的最大速度（字节/秒）。

max_local_write_bandwidth​

本地写入的最大速度（字节/秒）。

max_memory_usage​

云默认值：取决于副本上的内存量。

在单台服务器上执行查询时可使用的最大 RAM 量。 0 的值表示无限制。

此设置不考虑可用内存的大小或机器的总内存量。此限制适用于单个服务器上的单个查询。

您可以使用 SHOW PROCESSLIST 查看每个查询的当前内存消耗。 每个查询的峰值内存消耗被跟踪并记录到日志中。

对于以下聚合函数的状态，内存使用量不会完全跟踪：

  • min
  • max
  • any
  • anyLast
  • argMin
  • argMax

内存消耗也受到 max_memory_usage_for_user 和 max_server_memory_usage 参数的限制。

max_memory_usage_for_user​

在单台服务器上执行用户查询时可使用的最大 RAM 量。零表示无限制。

默认情况下，该数值没有限制（max_memory_usage_for_user = 0）。

另请参见 max_memory_usage 的描述。

例如，如果您希望将 max_memory_usage_for_user 设置为 clickhouse_read 用户的 1000 字节，可以使用以下语句

您可以通过注销客户端后重新登录，然后使用 getSetting 函数来验证设置是否生效：

max_network_bandwidth​

限制每秒通过网络交换的数据速度（字节）。此设置适用于每个查询。

可能值：

  • 正整数。
  • 0 — 禁用带宽控制。

max_network_bandwidth_for_all_users​

限制每秒通过网络交换的数据速度（字节）。此设置适用于服务器上同时运行的所有查询。

可能值：

  • 正整数。
  • 0 — 禁用数据速度控制。

max_network_bandwidth_for_user​

限制每秒通过网络交换的数据速度（字节）。此设置适用于由单个用户执行的所有并发查询。

可能值：

  • 正整数。
  • 0 — 禁用数据速度控制。

max_network_bytes​

限制在执行查询时通过网络接收或传输的数据量（字节）。此设置适用于每个独立查询。

可能值：

  • 正整数。
  • 0 — 禁用数据量控制。

max_number_of_partitions_for_independent_aggregation​

表中适用优化的最大分区数。

max_os_cpu_wait_time_ratio_to_throw​

考虑拒绝查询的操作系统 CPU 等待与繁忙时间的最大比率（OSCPUWaitMicroseconds 指标和 OSCPUVirtualTimeMicroseconds 指标之间的比率）。使用最小和最大比率之间的线性插值得到概率，当到达此点时，概率为 1。

max_parallel_replicas​

在执行查询时，每个分片的最大副本数量。

可能值：

  • 正整数。

附加信息

此选项将根据使用的设置生成不同的结果。

备注

如果涉及到连接或子查询，并且所有表不符合某些要求，则此设置将生成不正确的结果。有关更多详细信息，请参见 Distributed Subqueries 和 max_parallel_replicas。

使用 SAMPLE 键的并行处理​

如果在多个服务器上并行执行查询，可以更快地处理查询。但在以下情况下，查询性能可能会下降：

  • 采样键在分区键中的位置不允许有效的范围扫描。
  • 向表中添加采样键使得根据其他列的过滤效率降低。
  • 采样键是一个计算成本高昂的表达式。
  • 集群延迟分布有长尾，因此查询更多服务器会增加总体查询延迟。

使用 parallel_replicas_custom_key 的并行处理​

此设置对于任何复制表都是有用的。

max_parser_backtracks​

解析器的最大回溯次数（在递归下降解析过程中尝试不同的替代方案的次数）。

max_parser_depth​

限制递归下降解析器中的最大递归深度。用于控制堆栈大小。

可能值：

  • 正整数。
  • 0 — 递归深度无限制。

max_parsing_threads​

用于解析支持并行解析的输入格式数据的最大线程数。默认情况下，将自动确定该值。

max_partition_size_to_drop​

在查询时删除分区的限制。值为 0 意味着您可以无限制地删除分区。

云默认值：1 TB。

备注

此查询设置将覆盖其服务器设置等效项，请参见 max_partition_size_to_drop。

max_partitions_per_insert_block​

限制单个插入块中最大分区数量，如果块包含过多分区，则抛出异常。

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

详细信息

在插入数据时，ClickHouse 会计算插入块中的分区数。如果分区数量超过 max_partitions_per_insert_block，ClickHouse 会根据 throw_on_max_partitions_per_insert_block 条件要么记录警告，要么抛出异常。异常文本如下：

“单个 INSERT 块分区过多（ partitions_count 片段，限制为 ' + toString(max_partitions) + ）。该限制由 'max_partitions_per_insert_block' 参数控制。过多的分区是一个常见误解，它将导致严重的负性能影响，包括服务器启动缓慢、INSERT 查询缓慢和 SELECT 查询缓慢。建议的表总分区数应低于 1000..10000。请注意，分区的目的并不是为了加速 SELECT 查询（ORDER BY 键足以使范围查询快速）。分区的目的在于数据操作（DROP PARTITION 等）。”

备注

此设置是一个安全阈值，因为使用过多的分区是一个常见误解。

max_partitions_to_read​

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

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

可能值：

  • 正整数。
  • -1 - 无限（默认值）
备注

您也可以在表设置中指定 MergeTree 设置 max_partitions_to_read。

max_parts_to_move​

限制在一个查询中可以移动的部分数量。零表示无限制。

max_query_size​

可由 SQL 解析器解析的查询字符串的最大字节数。 INSERT 查询的 VALUES 子句中的数据由单独的流解析器处理（占用 O(1) RAM），不会受到此限制的影响。

备注

max_query_size 不能在 SQL 查询中设置（例如，SELECT now() SETTINGS max_query_size=10000），因为 ClickHouse 需要分配一个缓冲区来解析查询，而这个缓冲区的大小由 max_query_size 设置决定，该值必须在查询执行之前配置。

max_read_buffer_size​

从文件系统读取的缓冲区的最大大小。

max_read_buffer_size_local_fs​

从本地文件系统读取的缓冲区的最大大小。如果设置为 0，那么将使用 max_read_buffer_size。

max_read_buffer_size_remote_fs​

从远程文件系统读取的缓冲区的最大大小。如果设置为 0，那么将使用 max_read_buffer_size。

max_recursive_cte_evaluation_depth​

递归 CTE 评估深度的最大限制。

max_remote_read_network_bandwidth​

读取时网络数据交换的最大速度（字节/秒）。

max_remote_write_network_bandwidth​

写入时网络数据交换的最大速度（字节/秒）。

max_replica_delay_for_distributed_queries​

禁用延迟副本以进行分布式查询。请参见 Replication。

设置以秒为单位的时间。如果副本的延迟大于或等于设置的值，则不使用该副本。

可能的值：

  • 正整数。
  • 0 — 不检查副本延迟。

要防止使用任何具有非零延迟的副本，请将此参数设置为 1。

在执行 SELECT 从指向复制表的分布式表时使用此参数。

max_result_bytes​

限制结果大小（未压缩）的字节数。如果处理数据块时达到阈值，则查询将停止，但不会截断结果的最后一个块，因此结果大小可能大于阈值。

注意事项

此阈值考虑内存中的结果大小。 即使结果大小较小，它也可能引用内存中的较大数据结构， 表示 LowCardinality 列的字典和 AggregateFunction 列的 Arena， 因此尽管结果大小较小，该阈值仍可能被超出。

危险

该设置较为底层，应谨慎使用

max_result_rows​

云默认值：0。

限制结果中的行数。对子查询进行检查，并在运行分布式查询的不同服务器上进行检查。 当值为 0 时不施加限制。

如果处理数据块时达到阈值，查询将停止，但 不截断结果的最后一个块，因此结果大小可能大于阈值。

max_rows_in_distinct​

使用 DISTINCT 时最大不同的行数。

max_rows_in_join​

限制用于连接表的哈希表中的行数。

该设置适用于 SELECT ... JOIN 操作和 Join 表引擎。

如果查询包含多个连接，ClickHouse 会检查此设置以获得每个中间结果。

在达到限制时，ClickHouse 可以采取不同的操作。使用 join_overflow_mode 设置来选择操作。

可能的值：

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

max_rows_in_set​

从子查询创建的 IN 子句中数据集的最大行数。

max_rows_in_set_to_optimize_join​

在连接之前，在各连接表之间按行集过滤的最大集合大小。

可能的值：

  • 0 — 禁用。
  • 任何正整数。

max_rows_to_group_by​

从聚合中接收的唯一键的最大数量。此设置允许您限制聚合时的内存消耗。

如果在 GROUP BY 中生成的聚合行数（唯一的 GROUP BY 键）超过指定数量，则行为将由 'group_by_overflow_mode' 确定，该模式默认值为 throw，但也可以切换到近似 GROUP BY 模式。

max_rows_to_read​

在运行查询时可以从表中读取的最大行数。 该限制对每个处理的数据块都进行检查，仅适用于最深的表表达式，并且在从远程服务器读取时，仅在远程服务器上进行检查。

max_rows_to_read_leaf​

在运行分布式查询时，能从叶子节点的本地表中读取的最大行数。虽然分布式查询可以对每个分片（叶子）发出多个子查询——但此限制只在读取阶段检查，并在根节点的结果合并阶段忽略。

例如，一个集群由 2 个分片构成，且每个分片包含一张有 100 行的表。假定分布式查询需要读取来自两张表的所有数据且设置为 max_rows_to_read=150，则会失败，因为总共有 200 行。查询设置为 max_rows_to_read_leaf=150 则会成功，因为叶节点最多会读取 100 行。

该限制对每个处理的数据块进行检查。

备注

该设置在 prefer_localhost_replica=1 时不稳定。

max_rows_to_sort​

排序前的最大行数。这允许您限制排序时的内存消耗。 如果在 ORDER BY 操作中需要处理的记录数超过指定数量，则 行为将由 sort_overflow_mode 决定，默认值设置为 throw。

max_rows_to_transfer​

在执行 GLOBAL IN/JOIN 部分时，可以传递到远程服务器或保存到临时表中的最大大小（以行计）。

max_sessions_for_user​

每个经过身份验证的用户与 ClickHouse 服务器的最大并发会话数。

示例：

可能的值：

  • 正整数
  • 0 - 无限制并发会话（默认）

max_size_to_preallocate_for_aggregation​

在聚合之前，总共允许在所有哈希表中预分配的元素数量。

max_size_to_preallocate_for_joins​

在连接之前，总共允许在所有哈希表中预分配的元素数量。

max_streams_for_merge_tree_reading​

如果不为零，限制 MergeTree 表的读取流数。

max_streams_multiplier_for_merge_tables​

在从 Merge 表中读取时请求更多流。流将分配到合并表将使用的表中。这允许在线程之间更均匀地分配工作，并在合并表的大小不同的情况下尤为有用。

max_streams_to_max_threads_ratio​

允许您使用的源多于线程数——以便在线程之间更均匀地分配工作。假定这是一个临时解决方案，因为将来可能会使源数等于线程数，但每个源会动态选择可用工作。

max_subquery_depth​

如果查询的嵌套子查询数量超过指定数量，则抛出异常。

提示

这允许您进行合理性检查，以防止集群的用户编写过于复杂的查询。

max_table_size_to_drop​

删除表的查询时间限制。值为 0 的意思是您可以删除所有表而没有任何限制。

云默认值：1 TB。

备注

该查询设置会覆盖其服务器设置的等价项，请参见 max_table_size_to_drop

max_temporary_columns​

在运行查询时，同时必须保留在内存中的临时列的最大数量，包括常量列。如果查询在中间计算的过程中生成的临时列超过指定的数量，则会抛出异常。

提示

该设置有助于防止过于复杂的查询。

0 值意味着无限制。

max_temporary_data_on_disk_size_for_query​

所有并发运行的查询中，临时文件在磁盘上消耗的最大数据量（以字节为单位）。

可能的值：

  • 正整数。
  • 0 — 无限（默认）

max_temporary_data_on_disk_size_for_user​

所有并发运行的用户查询中，临时文件在磁盘上消耗的最大数据量（以字节为单位）。

可能的值：

  • 正整数。
  • 0 — 无限（默认）

max_temporary_non_const_columns​

与 max_temporary_columns 类似，在运行查询时，同时必须保留在内存中的临时列的最大数量，但不包括常量列。

备注

常量列在运行查询时相对频繁地形成，但它们几乎不需要计算资源。

max_threads​

查询处理线程的最大数量，不包括从远程服务器检索数据的线程（请参见 'max_distributed_connections' 参数）。

该参数适用于并行进行查询处理管道相同阶段的线程。 例如，在从表中读取时，如果可能同时评估包含函数的表达、筛选 WHERE 以及对 GROUP BY 进行预聚合，使用至少 'max_threads' 数量的线程，则会使用 'max_threads'。

对于因 LIMIT 而快速完成的查询，您可以设置较低的 'max_threads'。例如，如果所需的条目位于每个块中，并且 max_threads = 8，则会检索 8 个块，尽管只需读取一个就足够了。

max_threads 值越小，消耗的内存就越少。

max_threads_for_indexes​

处理索引的最大线程数量。

max_untracked_memory​

小的分配和释放在线程本地变量中分组，只有当 (绝对值) 超过指定值时才进行跟踪或分析。如果值高于 'memory_profiler_step'，则有效降低到 'memory_profiler_step'。

memory_overcommit_ratio_denominator​

表示在全局级别达到硬限制时的软内存限制。 此值用于计算查询的超额分配比例。 为零表示跳过查询。 阅读有关 memory overcommit 的更多信息。

memory_overcommit_ratio_denominator_for_user​

表示在用户级别达到硬限制时的软内存限制。 此值用于计算查询的超额分配比例。 为零表示跳过查询。 阅读有关 memory overcommit 的更多信息。

memory_profiler_sample_max_allocation_size​

以 memory_profiler_sample_probability 的概率收集小于或等于指定值的随机分配。0表示禁用。您可能希望将 'max_untracked_memory' 设置为 0，以使此阈值按预期工作。

memory_profiler_sample_min_allocation_size​

以 memory_profiler_sample_probability 的概率收集大于或等于指定值的随机分配。0表示禁用。您可能希望将 'max_untracked_memory' 设置为 0，以使此阈值按预期工作。

memory_profiler_sample_probability​

收集随机分配和释放，并将它们写入 system.trace_log，标记为 'MemorySample' trace_type。该概率对于每个分配/释放都是适用的，而不取决于分配的大小（可以通过 memory_profiler_sample_min_allocation_size 和 memory_profiler_sample_max_allocation_size 进行更改）。请注意，只有在未追踪内存超过 'max_untracked_memory' 时，才会进行采样。您可能希望将 'max_untracked_memory' 设置为 0，以实现更细粒度的采样。

memory_profiler_step​

设置内存分析器的步长。每当查询内存使用量超过每个下一步字节数时，内存分析器将收集分配的堆栈跟踪并将其写入 trace_log。

可能的值：

  • 正整数字节数。

  • 0 表示关闭内存分析器。

memory_tracker_fault_probability​

用于测试 exception safety - 每次您分配内存时，根据指定的概率抛出异常。

memory_usage_overcommit_max_wait_microseconds​

在用户级别，当出现内存超额分配时，线程等待释放内存的最大时间。 如果超时到期且内存未释放，则抛出异常。 阅读有关 memory overcommit 的更多信息。

merge_table_max_tables_to_look_for_schema_inference​

在创建没有显式模式的 Merge 表或使用 merge 表函数时，推断模式作为不超过指定数量匹配表的联合。 如果表的数量更大，则模式将从前面指定的数量的表中推断。

merge_tree_coarse_index_granularity​

在搜索数据时，ClickHouse 检查索引文件中的数据标记。如果 ClickHouse 发现所需键位于某个范围内，它将把该范围分割成 merge_tree_coarse_index_granularity 子范围并递归地在那里搜索所需键。

可能的值：

  • 任何正偶数。

merge_tree_compact_parts_min_granules_to_multibuffer_read​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。用于支持并行读取和预读取的 MergeTree 表紧凑部分的条带中 granule 的数量。如果从远程文件系统读取，使用多缓冲读取会增加读取请求的数量。

merge_tree_determine_task_size_by_prewhere_columns​

是否仅使用预过滤列的大小来确定读取任务的大小。

merge_tree_max_bytes_to_use_cache​

如果 ClickHouse 应该在一个查询中读取超过 merge_tree_max_bytes_to_use_cache 字节的数据，则不使用未压缩块的缓存。

未压缩块的缓存存储提取用于查询的数据。ClickHouse 使用该缓存加速对重复小查询的响应。该设置保护缓存不被大量读取数据的查询冲击。uncompressed_cache_size 服务器设置定义未压缩块缓存的大小。

可能的值：

  • 任何正整数。

merge_tree_max_rows_to_use_cache​

如果 ClickHouse 应该在一个查询中读取超过 merge_tree_max_rows_to_use_cache 行，则不使用未压缩块的缓存。

未压缩块的缓存存储提取用于查询的数据。ClickHouse 使用该缓存加速对重复小查询的响应。该设置保护缓存不被大量读取数据的查询冲击。uncompressed_cache_size 服务器设置定义未压缩块缓存的大小。

可能的值：

  • 任何正整数。

merge_tree_min_bytes_for_concurrent_read​

如果从 MergeTree 引擎表的一个文件读取的字节数超过 merge_tree_min_bytes_for_concurrent_read，则 ClickHouse 尝试在多个线程中同时读取此文件。

可能的值：

  • 正整数。

merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem​

读取来自远程文件系统的 MergeTree 引擎时，在并行化读取之前从一个文件读取的最小字节数。我们不建议使用此设置。

可能的值：

  • 正整数。

merge_tree_min_bytes_for_seek​

如果要读取的两个数据块在一个文件中的字节数小于 merge_tree_min_bytes_for_seek，则 ClickHouse 会顺序读取包含这两个块的文件范围，从而避免额外的寻址。

可能的值：

  • 任何正整数。

merge_tree_min_bytes_per_task_for_remote_reading​

每个任务要读取的最小字节数。

merge_tree_min_read_task_size​

任务大小的硬下限（即使 granule 数量少且可用线程数量多，我们也不会分配更小的任务）。

merge_tree_min_rows_for_concurrent_read​

如果要从 MergeTree 表的一个文件中读取的行数超过 merge_tree_min_rows_for_concurrent_read，则 ClickHouse 尝试在多个线程中执行并发读取。

可能的值：

  • 正整数。

merge_tree_min_rows_for_concurrent_read_for_remote_filesystem​

在从远程文件系统读取 MergeTree 引擎表的一个文件之前，读取的行数最小值。我们不建议使用此设置。

可能的值：

  • 正整数。

merge_tree_min_rows_for_seek​

如果要读取的两个数据块在一个文件中的行数小于 merge_tree_min_rows_for_seek，则 ClickHouse 不会在文件中寻址，而是顺序读取数据。

可能的值：

  • 任何正整数。

merge_tree_read_split_ranges_into_intersecting_and_non_intersecting_injection_probability​

用于测试 PartsSplitter - 每次从 MergeTree 读取时，按指定概率将读取范围拆分为相交和不相交的插入。

merge_tree_use_const_size_tasks_for_remote_reading​

是否在从远程表读取时使用固定大小的任务。

merge_tree_use_deserialization_prefixes_cache​

启用从 MergeTree 中宽部分读取时文件前缀的列元数据缓存。

merge_tree_use_prefixes_deserialization_thread_pool​

启用在 MergeTree 的宽部分中进行并行前缀读取的线程池。该线程池的大小由服务器设置 max_prefixes_deserialization_thread_pool_size 控制。

merge_tree_use_v1_object_and_dynamic_serialization​

启用后，MergeTree 中将使用 JSON 和动态类型的 V1 序列化版本，而不是 V2。更改此设置仅在服务器重启后生效。

metrics_perf_events_enabled​

如果启用，则在查询执行过程中将测量某些性能事件。

metrics_perf_events_list​

由逗号分隔的性能指标列表，在查询执行过程中会测量这些指标。为空表示所有事件。请参见源中的 PerfEventInfo 以获取可用事件。

min_bytes_to_use_direct_io​

使用直接 I/O 访问存储磁盘所需的最小数据量。

ClickHouse 在从表中读取数据时使用此设置。如果要读取的所有数据的总存储量超过 min_bytes_to_use_direct_io 字节，则 ClickHouse 使用 O_DIRECT 选项从存储磁盘读取数据。

可能的值：

  • 0 — 禁用直接 I/O。
  • 正整数。

min_bytes_to_use_mmap_io​

这是一个实验性设置。设置读取大文件而不复制数据从内核到用户空间所需的最小内存量。建议的阈值约为 64MB，因为 mmap/munmap 较慢。对于大文件只有在数据存在于页面缓存中时，才有意义。

可能的值：

  • 正整数。
  • 0 — 大文件仅通过复制数据从内核到用户空间读取。

min_chunk_bytes_for_parallel_parsing​

  • 类型：无符号整型
  • 默认值：1 MiB

每个线程将并行解析的最小块大小（以字节为单位）。

min_compress_block_size​

针对 MergeTree 表。在处理查询时，为了减少延迟，如果下一个标记的大小至少为 min_compress_block_size，则在写入时压缩块。默认值为 65,536。

如果未压缩数据的实际大小小于 max_compress_block_size，则此块的大小不小于该值，且不小于一个标记所需的数据量。

我们看一个例子。假设在创建表时将 index_granularity 设置为 8192。

我们写入一个 UInt32 类型的列（每个值 4 字节）。当写入 8192 行时，总共有 32 KB 的数据。由于 min_compress_block_size = 65,536，因此每两个标记形成一个压缩块。

我们写入一个字符串类型的 URL 列（每个值的平均大小为 60 字节）。当写入 8192 行时，平均的数据量略少于 500 KB。因为这大于 65,536，所以每个标记形成一个压缩块。在这种情况下，读取单个标记范围内的数据时，不会额外解压缩。

备注

这是一个专家级别的设置，如果您刚开始使用 ClickHouse，不应该更改它。

min_count_to_compile_aggregate_expression​

启动 JIT 编译所需的最少相同聚合表达式数量。仅在启用 compile_aggregate_expressions 设置时有效。

可能的值：

  • 正整数。
  • 0 — 始终 JIT 编译相同的聚合表达式。

min_count_to_compile_expression​

执行相同表达式之前的最小计数。

min_count_to_compile_sort_description​

在 JIT 编译之前相同排序描述的数量。

min_execution_speed​

每秒的最小执行速度（以行计）。在 timeout_before_checking_execution_speed 到期时，会检查每个数据块。如果执行速度较低，则会抛出异常。

min_execution_speed_bytes​

每秒的最小执行字节数。会在 timeout_before_checking_execution_speed 到期时检查每个数据块。如果执行速度较低，则会抛出异常。

min_external_sort_block_bytes​

外部排序的最小块大小（以字节为单位），需转储到磁盘，以避免过多文件。

min_external_table_block_size_bytes​

将传递给外部表的块压缩到指定的字节大小，如果块不够大。

min_external_table_block_size_rows​

将传递给外部表的块压缩到指定的行大小，如果块不够大。

min_free_disk_bytes_to_perform_insert​

执行插入所需的最小空闲磁盘空间（以字节为单位）。

min_free_disk_ratio_to_perform_insert​

执行插入所需的最小空闲磁盘空间比例。

min_free_disk_space_for_temporary_data​

写入在外部排序和聚合中使用的临时数据时所需保持的最小磁盘空间。

min_hit_rate_to_use_consecutive_keys_optimization​

进行连续键优化以维持启用的缓存的最小命中率。

min_insert_block_size_bytes​

设置通过 INSERT 查询插入到表中的块的最小字节数。较小的块会被压缩为更大的块。

可能的值：

  • 正整数。
  • 0 — 禁用压缩。

min_insert_block_size_bytes_for_materialized_views​

通过 INSERT 查询插入到表中的块的最小字节数。较小的块会被压缩为更大的块。此设置仅适用于插入到 物化视图 中的块。通过调整此设置，可以控制在推送到物化视图时的块压缩，避免过多的内存使用。

可能的值：

  • 任何正整数。
  • 0 — 禁用压缩。

另请参见

min_insert_block_size_rows​

通过 INSERT 查询插入到表中的块的最小行数。较小的块会被压缩为更大的块。

可能的值：

  • 正整数。
  • 0 — 禁用压缩。

min_insert_block_size_rows_for_materialized_views​

通过 INSERT 查询插入到表中的块的最小行数。较小的块会被压缩为更大的块。此设置仅适用于插入到 物化视图 中的块。通过调整此设置，可以控制在推送到物化视图时的块压缩，避免过多的内存使用。

可能的值：

  • 任何正整数。
  • 0 — 禁用压缩。

另请参见

min_joined_block_size_bytes​

JOIN 结果的最小块大小（如果连接算法支持）。0 表示无限制。

min_os_cpu_wait_time_ratio_to_throw​

操作系统 CPU 等待（OSCPUWaitMicroseconds 指标）和繁忙（OSCPUVirtualTimeMicroseconds 指标）时间之间的最小比率，以考虑拒绝查询。使用最小和最大比率之间的线性插值来计算概率，该点的概率为 0。

mongodb_throw_on_unsupported_query​

如果启用，当无法构建 MongoDB 查询时，MongoDB 表将返回错误。否则，ClickHouse 将读取完整表并在本地处理。如果 'allow_experimental_analyzer=0'，则此选项不适用。

move_all_conditions_to_prewhere​

将所有可行的条件从 WHERE 移动到 PREWHERE。

move_primary_key_columns_to_end_of_prewhere​

将包含主键列的 PREWHERE 条件移动到 AND 链的末尾。这些条件在主键分析过程中可能会被考虑，因此不会对 PREWHERE 过滤贡献太多。

multiple_joins_try_to_keep_original_names​

在多个连接重写时，不要向顶级表达式列表添加别名。

mutations_execute_nondeterministic_on_initiator​

如果为真，则在触发器上执行恒定的非确定性函数（例如函数 now()），并在 UPDATE 和 DELETE 查询中替换为文字。这有助于在使用恒定非确定性函数执行变更时保持副本中的数据同步。默认值：false。

mutations_execute_subqueries_on_initiator​

如果为真，则标量子查询在触发器上执行，并在 UPDATE 和 DELETE 查询中替换为文字。默认值：false。

mutations_max_literal_size_to_replace​

在 UPDATE 和 DELETE 查询中要替换的序列化文字的最大大小（以字节为单位）。仅在上述两个设置中至少有一个启用时生效。默认值：16384（16 KiB）。

mutations_sync​

允许在同步方式下执行 ALTER TABLE ... UPDATE|DELETE|MATERIALIZE INDEX|MATERIALIZE PROJECTION|MATERIALIZE COLUMN|MATERIALIZE STATISTICS 查询 (mutations)。

可能的值：

  • 0 - 变更异步执行。
  • 1 - 查询等待当前服务器上所有变更完成。
  • 2 - 查询等待所有副本（如果存在）的所有变更完成。

mysql_datatypes_support_level​

定义 MySQL 类型如何转换为相应的 ClickHouse 类型。以逗号分隔的列表，可以是 decimal、datetime64、date2Date32 或 date2String 的任何组合。

  • decimal：将 NUMERIC 和 DECIMAL 类型转换为 Decimal，当精度允许时。
  • datetime64：将 DATETIME 和 TIMESTAMP 类型转换为 DateTime64，而不是 DateTime，当精度不为 0 时。
  • date2Date32：将 DATE 转换为 Date32，而不是 Date。优先于 date2String。
  • date2String：将 DATE 转换为 String，而不是 Date。被 datetime64 覆盖。

mysql_map_fixed_string_to_text_in_show_columns​

启用后，ClickHouse 的 FixedString 数据类型将在 SHOW COLUMNS 中显示为 TEXT。

仅在通过 MySQL 线协议连接时有效。

  • 0 - 使用 BLOB。
  • 1 - 使用 TEXT。

mysql_map_string_to_text_in_show_columns​

启用后，ClickHouse 的 String 数据类型将在 SHOW COLUMNS 中显示为 TEXT。

仅在通过 MySQL 线协议连接时有效。

  • 0 - 使用 BLOB。
  • 1 - 使用 TEXT。

mysql_max_rows_to_insert​

MySQL 存储引擎批量插入的最大行数。

network_compression_method​

设置用于服务器之间以及服务器与 clickhouse-client 之间通信的数据压缩方法。

可能的值：

  • LZ4 — 设置 LZ4 压缩方法。
  • ZSTD — 设置 ZSTD 压缩方法。

另请参见

network_zstd_compression_level​

调整 ZSTD 压缩级别。仅在 network_compression_method 设置为 ZSTD 时使用。

可能的值：

  • 从 1 到 15 的正整数。

normalize_function_names​

将函数名称规范化为其规范名称。

number_of_mutations_to_delay​

如果变更表中包含至少这么多未完成的变更，人工减慢表的变更速度。0 - 禁用。

number_of_mutations_to_throw​

如果变更表中包含至少这么多未完成的变更，则抛出“变更过多...”异常。0 - 禁用。

odbc_bridge_connection_pool_size​

ODBC 桥每个连接设置字符串的连接池大小。

odbc_bridge_use_connection_pooling​

在 ODBC 桥中使用连接池。如果设置为 false，则每次都会创建一个新连接。

offset​

设置在开始返回查询行之前要跳过的行数。它调整由 OFFSET 子句设置的偏移量，以便这两个值相加。

可能的值：

  • 0 — 不跳过任何行。
  • 正整数。

示例

输入表：

查询：

结果：

opentelemetry_start_trace_probability​

设置 ClickHouse 可以为执行的查询启动跟踪的概率（如果没有提供父 trace context）。

可能的值：

  • 0 — 禁用所有执行查询的跟踪（如果没有提供父跟踪上下文）。
  • 在 [0..1] 范围内的正浮点数。例如，如果设置值为 0.5，ClickHouse 可以平均对一半的查询启动跟踪。
  • 1 — 启用所有执行查询的跟踪。

opentelemetry_trace_processors​

收集 OpenTelemetry 的处理程序跨度。

optimize_aggregation_in_order​

启用 GROUP BY 优化，以便在 MergeTree 表中按照相应顺序聚合数据。

可能的值：

  • 0 — 禁用 GROUP BY 优化。
  • 1 — 启用 GROUP BY 优化。

另请参见

optimize_aggregators_of_group_by_keys​

消除 SELECT 部分 GROUP BY 键的 min/max/any/anyLast 聚合器。

optimize_and_compare_chain​

填充常量比较，以及 AND 链以增强过滤能力。支持运算符 <、<=、>、>=、= 及其混合。例如，(a < b) AND (b < c) AND (c < 5) 将变成 (a < b) AND (b < c) AND (c < 5) AND (b < 5) AND (a < 5)。

optimize_append_index​

使用 constraints 以附加索引条件。默认值为 false。

可能的值：

  • true，false

optimize_arithmetic_operations_in_aggregate_functions​

将算术运算移出聚合函数。

optimize_count_from_files​

启用或禁用从不同输入格式的文件中计算行数的优化。适用于表函数/引擎 file/s3/url/hdfs/azureBlobStorage。

可能的值：

  • 0 — 优化禁用。
  • 1 — 优化启用。

optimize_distinct_in_order​

如果某些 DISTINCT 列形成排序的前缀，则启用 DISTINCT 优化。例如，MergeTree 中的排序键前缀或 ORDER BY 语句。

optimize_distributed_group_by_sharding_key​

优化 GROUP BY sharding_key 查询，通过避免在触发器服务器上进行昂贵的聚合（这将减少触发器服务器上查询的内存使用）。

支持以下类型的查询（及其组合）：

  • SELECT DISTINCT [..., ]sharding_key[, ...] FROM dist
  • SELECT ... FROM dist GROUP BY sharding_key[, ...]
  • SELECT ... FROM dist GROUP BY sharding_key[, ...] ORDER BY x
  • SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1
  • SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 BY x

以下类型的查询不支持（某些查询的支持可能稍后添加）：

  • SELECT ... GROUP BY sharding_key[, ...] WITH TOTALS
  • SELECT ... GROUP BY sharding_key[, ...] WITH ROLLUP
  • SELECT ... GROUP BY sharding_key[, ...] WITH CUBE
  • SELECT ... GROUP BY sharding_key[, ...] SETTINGS extremes=1

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

另请参见：

备注

现在它需要 optimize_skip_unused_shards（原因在于，某一天这可能会默认启用，而只有在数据通过分布式表插入时才能正确工作，即数据根据 sharding_key 分布）。

optimize_extract_common_expressions​

允许从 WHERE、PREWHERE、ON、HAVING 和 QUALIFY 表达式中的析取中提取公共表达式。逻辑表达式如 (A AND B) OR (A AND C) 可以重写为 A AND (B OR C)，这可能有助于利用：

  • 在简单过滤表达式中使用索引
  • 交叉到内部连接优化

optimize_functions_to_subcolumns​

启用或禁用通过将某些函数转换为读取子列进行优化。这可以减少要读取的数据量。

可以转换的这些函数：

可能的值：

  • 0 — 优化禁用。
  • 1 — 优化启用。

optimize_group_by_constant_keys​

优化 GROUP BY，当块中的所有键都是常量时。

optimize_group_by_function_keys​

消除 GROUP BY 部分的其他键的函数。

optimize_if_chain_to_multiif​

将 if(cond1, then1, if(cond2, ...)) 链替换为 multiIf。当前这对数值类型没有益处。

optimize_if_transform_strings_to_enum​

将 If 和 Transform 中的字符串类型参数替换为枚举。默认情况下禁用，因为这样可能导致分布式查询中的不一致变化，从而导致失败。

optimize_injective_functions_in_group_by​

在 GROUP BY 部分用其参数替换注入函数。

optimize_injective_functions_inside_uniq​

删除 uniq*() 函数内部一个参数的注入函数。

optimize_min_equality_disjunction_chain_length​

用于优化的表达式 expr = x1 OR ... expr = xN 的最小长度。

optimize_min_inequality_conjunction_chain_length​

用于优化的表达式 expr <> x1 AND ... expr <> xN 的最小长度。

optimize_move_to_prewhere​

启用或禁用在 SELECT 查询中自动优化 PREWHERE。

仅适用于 *MergeTree 表。

可能的值：

  • 0 — 自动 PREWHERE 优化禁用。
  • 1 — 自动 PREWHERE 优化启用。

optimize_move_to_prewhere_if_final​

启用或禁用在带有 FINAL 修饰符的 SELECT 查询中自动优化 PREWHERE。

仅适用于 *MergeTree 表。

可能的值：

  • 0 — 在带有 FINAL 修饰符的 SELECT 查询中自动优化 PREWHERE 被禁用。
  • 1 — 在带有 FINAL 修饰符的 SELECT 查询中自动优化 PREWHERE 被启用。

另请参见

optimize_multiif_to_if​

将具有唯一条件的 'multiIf' 替换为 'if'。

optimize_normalize_count_variants​

重写在语义上等同于 count() 的聚合函数为 count()。

optimize_on_insert​

启用或禁用在插入之前进行数据转换，就像在此块上执行了一次合并（根据表引擎）。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

示例

启用和禁用之间的差异：

查询：

结果：

注意，此设置会影响 物化视图 的行为。

optimize_or_like_chain​

优化多个 OR LIKE 的查询为 multiMatchAny。此优化在某些情况下不应默认启用，因为它会破坏索引分析。

optimize_read_in_order​

启用在 SELECT 查询中对 MergeTree 表读取数据的 ORDER BY 优化。

可能的值：

  • 0 — ORDER BY 优化禁用。
  • 1 — ORDER BY 优化启用。

另请参见

optimize_read_in_window_order​

在窗口子句中启用 ORDER BY 优化，以按相应顺序读取 MergeTree 表中的数据。

optimize_redundant_functions_in_order_by​

从 ORDER BY 移除函数，如果其参数也在 ORDER BY 中。

optimize_respect_aliases​

如果设置为 true，则将遵循 WHERE/GROUP BY/ORDER BY 中的别名，这将有助于分区修剪/二级索引/优化聚合顺序/优化读取顺序/优化琐碎计数。

optimize_rewrite_aggregate_function_with_if​

重写带有 if 表达式的聚合函数作为参数，当逻辑上等效时。例如，avg(if(cond, col, null)) 可以重写为 avgOrNullIf(cond, col)。这可能会提高性能。

备注

仅在分析器(enable_analyzer = 1)支持下。

optimize_rewrite_array_exists_to_has​

在逻辑上等效时将 arrayExists() 函数重写为 has()。例如，arrayExists(x -> x = 1, arr) 可以重写为 has(arr, 1)。

optimize_rewrite_sum_if_to_count_if​

当逻辑上等效时，将 sumIf() 和 sum(if()) 函数重写为 countIf() 函数。

optimize_skip_merged_partitions​

如果只有一个级别大于 0 的分区且没有过期 TTL，则启用或禁用 OPTIMIZE TABLE ... FINAL 查询的优化。

  • OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1

默认情况下，即使只有一个分区也会重写 OPTIMIZE TABLE ... FINAL 查询。

可能的值：

  • 1 - 启用优化。
  • 0 - 禁用优化。

optimize_skip_unused_shards​

启用或禁用对具有 sharding key 条件的 SELECT 查询跳过未使用的分片（假设数据是通过 sharding key 分布的，否则查询的结果不正确）。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

optimize_skip_unused_shards_limit​

sharding key 值的数量限制，如果达到这个限制则关闭 optimize_skip_unused_shards。

过多的值可能需要大量处理，而好处可疑，因为如果你在 IN (...) 中有大量值，查询基本上会被发送到所有分片。

optimize_skip_unused_shards_nesting​

控制 optimize_skip_unused_shards（因此仍然需要 [optimize_skip_unused_shards](#optimize_skip_unused_shards））依赖于分布式查询的嵌套级别（在你有 Distributed 表查询另一个 Distributed 表的情况下）。

可能的值：

  • 0 — 禁用，optimize_skip_unused_shards 始终有效。
  • 1 — 仅在第一层启用 optimize_skip_unused_shards。
  • 2 — 启用 optimize_skip_unused_shards 直至第二层。

optimize_skip_unused_shards_rewrite_in​

对于远程分片重写查询中的 IN，以排除不属于分片的值（需要 optimize_skip_unused_shards）。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

optimize_sorting_by_input_stream_properties​

根据输入流的排序属性优化排序。

optimize_substitute_columns​

使用 constraints 进行列替换。默认值为 false。

可能的值：

  • true，false

optimize_syntax_fuse_functions​

启用将具有相同参数的聚合函数融合。它重写查询，其中包含至少两个具有相同参数的 sum、count 或 avg 聚合函数为 sumCount。

可能的值：

  • 0 — 不融合相同参数的函数。
  • 1 — 融合相同参数的函数。

示例

查询：

结果：

optimize_throw_if_noop​

启用或禁用在 OPTIMIZE 查询未执行合并时抛出异常。

默认情况下，即使没有执行任何操作，OPTIMIZE 也会成功返回。此设置使你可以区分这些情况并在异常消息中得到原因。

可能的值：

  • 1 — 启用抛出异常。
  • 0 — 禁用抛出异常。

optimize_time_filter_with_preimage​

通过将函数转换为等效比较而优化 Date 和 DateTime 谓词，而不进行转换（例如 toYear(col) = 2023 -> col >= '2023-01-01' AND col <= '2023-12-31'）。

optimize_trivial_approximate_count_query​

对支持此类估计的存储的琐碎计数优化使用近似值，例如 EmbeddedRocksDB。

可能的值：

  • 0 — 优化禁用。
  • 1 — 优化启用。

optimize_trivial_count_query​

启用或禁用对琐碎查询 SELECT count() FROM table 的优化，使用来自 MergeTree 的元数据。如果需要使用行级安全性，则禁用此设置。

可能的值：

  • 0 — 优化禁用。
  • 1 — 优化启用。

另请参见：

optimize_trivial_insert_select​

优化琐碎的 'INSERT INTO table SELECT ... FROM TABLES' 查询。

optimize_uniq_to_count​

在子查询具有 distinct 或 group by 子句时，将 uniq 及其变体（不包括 uniqUpTo）重写为 count。

optimize_use_implicit_projections​

自动选择隐式投影以执行 SELECT 查询。

optimize_use_projections​

启用或禁用在处理 SELECT 查询时对 projections 的优化。

可能的值：

  • 0 — 禁用投影优化。
  • 1 — 启用投影优化。

optimize_using_constraints​

使用 constraints 进行查询优化。默认值为 false。

可能的值：

  • true，false

os_thread_priority​

设置执行查询的线程的优先级（nice）。操作系统调度程序在选择每个可用 CPU 内核上运行的下一个线程时会考虑此优先级。

备注

要使用此设置，您需要设置 CAP_SYS_NICE 权限。clickhouse-server 包在安装期间会设置该权限。某些虚拟环境不允许您设置 CAP_SYS_NICE 权限。在这种情况下，clickhouse-server 会在启动时显示相关信息。

可能的值：

  • 您可以在 [-20, 19] 范围内设置值。

较低的值表示更高的优先级。优先级较低的线程执行频率高于优先级较高的线程。高值适用于长时间运行的非交互式查询，因为它允许它们在短的交互式查询到达时快速放弃资源。

output_format_compression_level​

如果查询输出被压缩，则为默认压缩级别。当 SELECT 查询包含 INTO OUTFILE 或写入表函数 file、url、hdfs、s3 或 azureBlobStorage 时，该设置生效。

可能的值：从 1 到 22。

output_format_compression_zstd_window_log​

当输出压缩方法为 zstd 时可使用。如果大于 0，则此设置明确设置压缩窗口大小（2 的幂）并启用 zstd 压缩的长范围模式。这有助于实现更好的压缩比。

可能的值：非负数。请注意，如果值太小或太大，zstdlib 将抛出异常。典型值范围为 20（窗口大小 = 1MB）至 30（窗口大小 = 1GB）。

output_format_parallel_formatting​

启用或禁用数据格式的并行格式化。仅支持 TSV、TSKV、CSV 和 JSONEachRow 格式。

可能的值：

  • 1 — 启用。
  • 0 — 禁用。

page_cache_block_size​

在用户空间页缓存中存储的文件块大小（以字节为单位）。所有通过缓存的读取将向上舍入为此大小的倍数。

可以根据每个查询级别进行调整，但具有不同块大小的缓存条目无法重复使用。更改此设置实际上会使缓存中的现有条目失效。

较高的值，如 1 MiB 适用于高吞吐量的查询，而较低的值，如 64 KiB 适用于低延迟的点查询。

page_cache_inject_eviction​

用户空间页缓存有时会随机失效某些页面。用于测试目的。

page_cache_lookahead_blocks​

在用户空间页缓存未命中时，如果相应块也不在缓存中，则从底层存储一次读取多达这一数量的连续块。每个块的大小为 page_cache_block_size 字节。

较高的值适合高吞吐量查询，而低延迟的点查询在无需提前读取的情况下效果更佳。

parallel_distributed_insert_select​

启用并行分布式 INSERT ... SELECT 查询。

如果我们执行 INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b 查询，并且两个表使用相同的集群，且两个表都是 replicated 或非复制的，则该查询在每个分片上都在本地处理。

可能的值：

  • 0 — 禁用。
  • 1 — SELECT 将在分布式引擎的底层表的每个分片上执行。
  • 2 — SELECT 和 INSERT 将在分布式引擎的每个分片上执行到/从底层表。

parallel_hash_join_threshold​

当应用基于哈希的连接算法时，此阈值有助于决定使用 hash 还是 parallel_hash（仅在右表大小估计可用时）。 当我们知道右表大小小于该阈值时使用前者。

parallel_replica_offset​

Beta feature. Learn more.

这是内部设置，不应直接使用，表示“并行副本”模式的实现细节。此设置将由分布式查询的发起服务器自动设置，以用于参与查询处理的副本索引。

parallel_replicas_allow_in_with_subquery​

Beta feature. Learn more.

如果为真，IN 子查询将在每个后续副本上执行。

parallel_replicas_connect_timeout_ms​

Beta feature. Learn more.

在使用并行副本执行查询期间，连接到远程副本的超时时间（以毫秒为单位）。如果超时时间到，则对应的副本将不用于查询执行。

parallel_replicas_count​

Beta feature. Learn more.

这是内部设置，不应直接使用，表示“并行副本”模式的实现细节。此设置将由分布式查询的发起服务器自动设置，用于参与查询处理的并行副本数量。

parallel_replicas_custom_key​

Beta feature. Learn more.

可以用于在特定表中拆分副本工作的任意整数表达式。 该值可以是任何整数表达式。

简单表达式使用主键更为理想。

如果该设置用于由单个分片和多个副本组成的集群，则这些副本将被转换为虚拟分片。 否则，它将按 SAMPLE 键的行为，使用每个分片的多个副本。

parallel_replicas_custom_key_range_lower​

Beta feature. Learn more.

允许过滤类型为 range 的查询在副本之间均匀地分配工作，基于自定义范围 [parallel_replicas_custom_key_range_lower, INT_MAX]。

与 parallel_replicas_custom_key_range_upper 结合使用时，它允许过滤器在范围 [parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper] 上均匀地分配副本之间的工作。

注意：此设置不会导致在查询处理期间过滤任何额外的数据，而是更改范围过滤器在 [0, INT_MAX] 范围上进行并行处理时的切分点。

parallel_replicas_custom_key_range_upper​

Beta feature. Learn more.

允许过滤类型为 range 的查询在副本之间均匀地分配工作，基于自定义范围 [0, parallel_replicas_custom_key_range_upper]。值为0将禁用上限，将其设置为自定义键表达式的最大值。

与 parallel_replicas_custom_key_range_lower 结合使用时，它允许过滤器在范围 [parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper] 上均匀地分配副本之间的工作。

注意：此设置不会导致在查询处理期间过滤任何额外的数据，而是更改范围过滤器在 [0, INT_MAX] 范围上进行并行处理时的切分点。

parallel_replicas_for_cluster_engines​

用其 -Cluster 替代表函数引擎。

parallel_replicas_for_non_replicated_merge_tree​

Beta feature. Learn more.

如果为真，ClickHouse 将对非复制的 MergeTree 表也使用并行副本算法。

parallel_replicas_index_analysis_only_on_coordinator​

Beta feature. Learn more.

只在副本协调者上进行索引分析，跳过其他副本。仅在启用 parallel_replicas_local_pla 时有效。

parallel_replicas_insert_select_local_pipeline​

Beta feature. Learn more.

在使用并行副本的分布式 INSERT SELECT 时使用本地管道。

parallel_replicas_local_plan​

Beta feature. Learn more.

为本地副本构建本地计划。

parallel_replicas_mark_segment_size​

Beta feature. Learn more.

分片在虚拟上划分为段，以便在副本之间进行并行读取。该设置控制这些段的大小。建议在充分理解的情况下再更改此设置。值应在范围 [128; 16384] 内。

parallel_replicas_min_number_of_rows_per_replica​

Beta feature. Learn more.

限制查询中使用的副本数量为（预估读取行数 / min_number_of_rows_per_replica）。最大值仍然受 'max_parallel_replicas' 的限制。

parallel_replicas_mode​

Beta feature. Learn more.

用于指定自定义键的并行副本的过滤器类型。默认值 - 对自定义键使用模运算，范围 - 使用自定义键的范围过滤器，使用自定义键的所有可能值类型。

parallel_replicas_only_with_analyzer​

Beta feature. Learn more.

启用分析器才能使用并行副本。如果禁用分析器，查询执行将回退到本地执行，即使启用了从副本的并行读取。不支持在未启用分析器的情况下使用并行副本。

parallel_replicas_prefer_local_join​

Beta feature. Learn more.

如果为真，当JOIN可以使用并行副本算法执行，并且右侧JOIN部分的所有存储都是 *MergeTree，将使用本地JOIN而不是全局JOIN。

parallel_view_processing​

启用同时推送到附加视图，而不是顺序推送。

parallelize_output_from_storages​

并行化从存储的读取步骤的输出。如果可能，在从存储读取之后允许查询处理的并行化。

parsedatetime_e_requires_space_padding​

函数 'parseDateTime' 中的格式符 '%e' 期望单个数字的日期有空格填充，例如 ' 2' 被接受，但 '2' 会引发错误。

parsedatetime_parse_without_leading_zeros​

函数 'parseDateTime' 中的格式符 '%c'、'%l' 和 '%k' 对月份和小时进行解析时不带前导零。

partial_merge_join_left_table_buffer_bytes​

如果不为0，则在部分合并连接中将左表块组合为更大的块。每个连接线程使用最多2倍指定内存。

partial_merge_join_rows_in_right_blocks​

限制在部分合并连接算法中右侧连接数据块的大小，以进行 JOIN 查询。

ClickHouse 服务器：

  1. 将右侧连接数据拆分为最大指定行数的块。
  2. 以其最小值和最大值为每个块创建索引。
  3. 如果可能，将准备好的块卸载到磁盘。

可能值：

  • 任何正整数。建议值范围：[1000, 100000]。

partial_result_on_first_cancel​

允许查询在取消后返回部分结果。

parts_to_delay_insert​

如果目标表在单个分区中包含至少这么多的活动分片，则人工减慢对表的插入速度。

parts_to_throw_insert​

如果目标表的单个分区中活动分片超过该数字，则抛出'碎片太多...'异常。

periodic_live_view_refresh​

强制在指定间隔后定期刷新实时视图。

poll_interval​

在服务器的查询等待循环中阻塞指定的秒数。

postgresql_connection_attempt_timeout​

连接到 PostgreSQL 端点的单次尝试的连接超时（以秒为单位）。该值作为连接 URL 的 connect_timeout 参数传递。

postgresql_connection_pool_auto_close_connection​

在将连接返回到池之前关闭连接。

postgresql_connection_pool_retries​

PostgreSQL 表引擎和数据库引擎的连接池推送/弹出重试次数。

postgresql_connection_pool_size​

PostgreSQL 表引擎和数据库引擎的连接池大小。

postgresql_connection_pool_wait_timeout​

在 PostgreSQL 表引擎和数据库引擎的空池中推送/弹出连接超时。默认情况下在空池内将被阻塞。

postgresql_fault_injection_probability​

内部（用于复制）的 PostgreSQL 查询失败的概率。有效值在区间 [0.0f, 1.0f] 内。

prefer_column_name_to_alias​

启用或禁用在查询表达式和子句中使用原始列名而不是别名。当别名与列名相同时，这一点尤其重要，见 表达式别名。启用此设置可以使 ClickHouse 的别名语法规则与大多数其他数据库引擎更兼容。

可能值：

  • 0 — 用别名替换列名。
  • 1 — 列名不被替换为别名。

示例

启用和禁用之间的差异：

查询：

结果：

查询：

结果：

prefer_external_sort_block_bytes​

偏好外部排序的最大块字节，减少合并过程中的内存使用。

prefer_global_in_and_join​

启用将 IN/JOIN 操作符替换为 GLOBAL IN/GLOBAL JOIN。

可能值：

  • 0 — 禁用。IN/JOIN 操作符不会被替换为 GLOBAL IN/GLOBAL JOIN。
  • 1 — 启用。IN/JOIN 操作符被替换为 GLOBAL IN/GLOBAL JOIN。

使用

虽然 SET distributed_product_mode=global 可以改变分布式表的查询行为，但不适合本地表或来自外部资源的表。这时 prefer_global_in_and_join 设置就发挥作用了。

例如，我们有服务节点的查询，这些节点包含不适合分发的本地表。在分布式处理过程中，我们需要通过 GLOBAL 关键字动态地分散它们的数据 — GLOBAL IN/GLOBAL JOIN。

prefer_global_in_and_join 的另一个用例是访问由外部引擎创建的表。该设置可以帮助减少在连接这些表时对外部源的调用次数：每次查询只需一次调用。

另请参见：

  • 关于如何使用 GLOBAL IN/GLOBAL JOIN 的更多信息，请参见 分布式子查询。

prefer_localhost_replica​

启用/禁用在处理分布式查询时优先使用本地主机副本。

可能值：

  • 1 — 如果存在，ClickHouse 总是将查询发送到本地主机副本。
  • 0 — ClickHouse 使用 load_balancing 设置指定的负载均衡策略。
备注

如果您在没有 parallel_replicas_custom_key 的情况下使用 max_parallel_replicas，请禁用此设置。 如果设置了 parallel_replicas_custom_key，只有在它用于包含多个副本的多个分片的集群时，才能禁用此设置。 如果用于单个分片和多个副本的集群，禁用此设置将产生负面影响。

prefer_warmed_unmerged_parts_seconds​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。如果合并的部分距离现在不超过这个秒数，并且尚未预热（参见 cache_populated_by_fetch），但它的所有源部分都可用且预热，则 SELECT 查询将从这些部分中读取。仅适用于 Replicated-/SharedMergeTree。注意，这仅检查缓存预热器是否处理了该部分；如果该部分是由其他东西提取到缓存的，它仍会被视为冷缓存，直到缓存预热器处理它；如果它已被预热，随后从缓存中驱逐，则仍会被视为温缓存。

preferred_block_size_bytes​

此设置调整查询处理的数据块大小，并表示对更粗略的 'max_block_size' 设置的额外微调。如果列较大且具有 'max_block_size' 行，则块大小可能会大于指定字节数，其大小将被降低以实现更好的 CPU 缓存局部性。

preferred_max_column_in_block_size_bytes​

限制在读取时块中列的最大大小。帮助减少缓存未命中计数。应该接近 L2 缓存大小。

preferred_optimize_projection_name​

如果设置为非空字符串，ClickHouse 将尝试在查询中应用指定的投影。

可能值：

  • 字符串：首选投影的名称。

prefetch_buffer_size​

预取缓冲区从文件系统读取的最大大小。

允许在 DESCRIBE 查询和 toTypeName() 函数中以美观的方式打印深度嵌套的类型名称并带有缩进。

示例：

priority​

查询的优先级。1 - 最高，较高值 - 较低优先级；0 - 不使用优先级。

push_external_roles_in_interserver_queries​

启用在执行查询时将用户角色从发起者推送到其他节点。

query_cache_compress_entries​

压缩 查询缓存 中的条目。以牺牲插入到缓存中的速度来减少查询缓存的内存消耗。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_cache_max_entries​

当前用户可以存储在 查询缓存 中的查询结果的最大数量。0 表示无限制。

可能值：

  • 正整数 >= 0。

query_cache_max_size_in_bytes​

当前用户在 查询缓存 中可以分配的最大内存量（以字节为单位）。0 表示无限制。

可能值：

  • 正整数 >= 0。

query_cache_min_query_duration​

存储查询结果在 查询缓存 中所需的最小持续时间（以毫秒为单位）。

可能值：

  • 正整数 >= 0。

query_cache_min_query_runs​

SELECT 查询必须运行的最小次数，才能将其结果存储在 查询缓存 中。

可能值：

  • 正整数 >= 0。

query_cache_nondeterministic_function_handling​

控制 查询缓存 如何处理包含非确定性函数（如 rand() 或 now()）的 SELECT 查询。

可能值：

  • 'throw' - 抛出异常并不缓存查询结果。
  • 'save' - 缓存查询结果。
  • 'ignore' - 不缓存查询结果并且不抛出异常。

query_cache_share_between_users​

如果启用，缓存的 SELECT 查询结果可以被其他用户读取。由于安全原因，不建议启用此设置。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_cache_squash_partial_results​

将部分结果块压缩为大小为 max_block_size 的块。降低插入到 查询缓存 的性能，但提高缓存条目的压缩能力（参见 query_cache_compress-entries）。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_cache_system_table_handling​

控制 查询缓存 如何处理针对系统表的 SELECT 查询，即数据库 system.* 和 information_schema.* 中的表。

可能值：

  • 'throw' - 抛出异常并不缓存查询结果。
  • 'save' - 缓存查询结果。
  • 'ignore' - 不缓存查询结果并且不抛出异常。

query_cache_tag​

充当 查询缓存 条目的标签的字符串。相同的查询具有不同的标签时，查询缓存会将其视为不同的查询。

可能值：

  • 任何字符串。

query_cache_ttl​

在此时间（以秒为单位）之后，查询缓存 中的条目变为过期。

可能值：

  • 正整数 >= 0。

query_condition_cache_store_conditions_as_plaintext​

存储 查询条件缓存 过滤条件为明文。如果启用，system.query_condition_cache 显示逐字的过滤条件，这使得调试缓存问题更容易。默认禁用，因为明文过滤条件可能会暴露敏感信息。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_metric_log_interval​

收集单个查询的 query_metric_log 的间隔（以毫秒为单位）。

如果设置为负值，将采用 query_metric_log setting 中的 collect_interval_milliseconds 值，或如果不存在则默认值为1000。

要禁用单个查询的收集，将 query_metric_log_interval 设置为 0。

默认值：-1。

query_plan_aggregation_in_order​

切换查询计划级别的按顺序聚合优化。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_convert_join_to_in​

允许将 JOIN 转换为只有左表绑定的 IN 子查询。如果与非-ANY JOIN（例如默认的 ALL JOIN）一起使用，可能会导致结果错误。

query_plan_convert_outer_join_to_inner_join​

允许将 OUTER JOIN 转换为 INNER JOIN 如果 JOIN 后的过滤器总是过滤默认值。

query_plan_enable_multithreading_after_window_functions​

启用在评估窗口函数后进行多线程处理，以允许并行流处理。

query_plan_enable_optimizations​

切换查询计划级别的查询优化。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用查询计划级别的所有优化。
  • 1 - 启用查询计划级别的优化（但单个优化仍可以通过其各自的设置禁用）。

query_plan_execute_functions_after_sorting​

切换查询计划级别的优化，将表达式移动到排序步骤之后。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_filter_push_down​

切换查询计划级别的优化，将过滤器向下移动至执行计划中。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_join_shard_by_pk_ranges​

如果连接键包含两个表的主键前缀，则对 JOIN 应用分片。支持哈希、并行哈希和全排序合并算法。通常不会加速查询，但可能降低内存消耗。

query_plan_join_swap_table​

确定JOIN中应该哪一侧是构建表（也称为内表，插入到哈希表中的表）在查询计划中。该设置仅支持具有 JOIN ON 子句的 "ALL" 连接严格性。可能的值是：

  • 'auto': 让计划器决定使用哪个表作为构建表。
  • 'false': 永远不交换表（右表为构建表）。
  • 'true': 始终交换表（左表为构建表）。

query_plan_lift_up_array_join​

切换查询计划级别的优化，提升 ARRAY JOIN 在执行计划中的位置。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_lift_up_union​

切换查询计划级别的优化，将查询计划中较大的子树提升到联合中，以启用进一步优化。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_max_limit_for_lazy_materialization​

控制查询计划允许使用懒惰物化优化的最大限制值。如果为零，则没有限制。

query_plan_max_optimizations_to_apply​

限制应用于查询计划的优化总数，请参阅设置 query_plan_enable_optimizations。用于避免复杂查询的长时间优化时间。在 EXPLAIN PLAN 查询中，在达到此限制后停止应用优化并返回原始计划。对于常规查询执行，如果实际应用的优化数量超过此设置，将抛出异常。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

query_plan_merge_expressions​

切换查询计划级别的优化，合并连续的过滤器。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_merge_filter_into_join_condition​

允许将过滤器合并到JOIN条件中，并将 CROSS JOIN 转换为 INNER JOIN。

query_plan_merge_filters​

允许合并查询计划中的过滤器。

query_plan_optimize_lazy_materialization​

使用查询计划实现懒惰物化优化。

query_plan_optimize_prewhere​

允许将过滤器下推到支持存储的 PREWHERE 表达式。

query_plan_push_down_limit​

切换查询计划级别的优化，将 LIMIT 下推到执行计划中。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_read_in_order​

切换查询计划级别的按顺序读取优化。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_remove_redundant_distinct​

切换查询计划级别的优化，移除冗余的 DISTINCT 步骤。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_remove_redundant_sorting​

切换查询计划级别的优化，移除冗余的排序步骤，例如在子查询中。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_reuse_storage_ordering_for_window_functions​

切换查询计划级别的优化，当对窗口函数进行排序时使用存储排序。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_split_filter​

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

切换查询计划级别的优化，将过滤器分割为表达式。仅在设置 query_plan_enable_optimizations 为1时生效。

可能值：

  • 0 - 禁用
  • 1 - 启用

切换查询计划级别的优化，尝试使用向量相似性索引。仅在设置 query_plan_enable_optimizations 为1时生效。

备注

这是一个专家级设置，仅供开发人员调试使用。该设置可能会在未来以不向后兼容的方式更改或被移除。

可能值：

  • 0 - 禁用
  • 1 - 启用

query_plan_use_new_logical_join_step​

在查询计划中使用新的逻辑连接步骤。

query_profiler_cpu_time_period_ns​

设置 查询分析器 CPU 时钟计时器的周期。该计时器仅计数 CPU 时间。

可能值：

  • 一个正整数的纳秒数。

    推荐的值：

    • 10000000（每秒100次）纳秒及以上用于单个查询。
    • 1000000000（每秒一次）用于集群范围的分析。

  • 0 用于关闭计时器。

在 ClickHouse Cloud 中暂时禁用。

另请参见：

query_profiler_real_time_period_ns​

设置 query profiler 的实时时钟计时器的周期。实时时钟计时器计算墙钟时间。

可能的值：

  • 正整数，以纳秒为单位。

    推荐值：

    • 单个查询使用 10000000（每秒 100 次）纳秒及以下。
    • 集群范围内的分析使用 1000000000（每秒一次）。

  • 0 表示关闭计时器。

在 ClickHouse Cloud 中暂时禁用。

另请参见：

queue_max_wait_ms​

请求队列中的等待时间，如果并发请求数量超过最大值。

rabbitmq_max_wait_ms​

从 RabbitMQ 读取之前的等待时间。

read_backoff_max_throughput​

在读取缓慢的情况下减少线程数的设置。当读取带宽低于指定字节数每秒时，统计事件。

read_backoff_min_concurrency​

在读取缓慢的情况下尝试保持最小线程数的设置。

read_backoff_min_events​

在读取缓慢的情况下减少线程数的设置。在达到一定事件数量后，将减少线程数。

read_backoff_min_interval_between_events_ms​

在读取缓慢的情况下减少线程数的设置。如果前一个事件经过的时间少于特定时间，则不考虑该事件。

read_backoff_min_latency_ms​

在读取缓慢的情况下减少线程数的设置。仅关注至少花费该时间的读取。

read_from_filesystem_cache_if_exists_otherwise_bypass_cache​

允许在被动模式下使用文件系统缓存 - 利用现有的缓存条目，但不向缓存中添加更多条目。如果您为重型临时查询设置此设置，并将其关闭用于短实时查询，这将有助于避免因重型查询而导致的缓存抖动，并改善系统整体效率。

read_from_page_cache_if_exists_otherwise_bypass_cache​

在被动模式下使用用户空间页缓存，类似于 read_from_filesystem_cache_if_exists_otherwise_bypass_cache。

read_in_order_two_level_merge_threshold​

在按主键顺序多线程读取期间运行初步合并步骤所需读取的最小部分数。

read_in_order_use_buffering​

在按主键顺序读取时合并之前使用缓冲。这增加了查询执行的并行性。

read_in_order_use_virtual_row​

在按主键或其单调函数格式读取时使用虚拟行。在搜索多个部分时非常有用，因为仅会涉及相关部分。

read_overflow_mode​

当超出限制时该怎么办。

read_overflow_mode_leaf​

设置读取的数据量超过某一叶子限制时发生的事情。

可能的选项：

  • throw：抛出异常（默认）。
  • break：停止执行查询并返回部分结果。

read_priority​

从本地文件系统或远程文件系统读取数据的优先级。仅支持本地文件系统的 'pread_threadpool' 方法和远程文件系统的 threadpool 方法。

read_through_distributed_cache​

ClickHouse Cloud only

仅在 ClickHouse Cloud 中生效。允许从分布式缓存中读取。

readonly​

0 - 无只读限制。 1 - 仅允许读请求，以及更改显式允许的设置。 2 - 仅允许读请求，以及更改设置，除了 'readonly' 设置。

receive_data_timeout_ms​

接收数据的连接超时，用于接收第一个数据包或来自副本的正进展包。

receive_timeout​

从网络接收数据的超时（以秒为单位）。如果在此间隔内未收到字节，则抛出异常。如果您在客户端设置此设置，则相应连接端上的 'send_timeout' 也将设置在服务器上。

regexp_max_matches_per_row​

设置每行单个正则表达式的最大匹配次数。使用它来防止在 extractAllGroupsHorizontal 函数中使用贪婪正则表达式时的内存过载。

可能的值：

  • 正整数。

reject_expensive_hyperscan_regexps​

拒绝在使用 hyperscan 时可能代价高昂的模式（由于 NFA 状态爆炸）。

remerge_sort_lowered_memory_bytes_ratio​

如果重新合并后的内存使用未按此比例减少，则将禁用重新合并。

remote_filesystem_read_method​

从远程文件系统读取数据的方法之一：read、threadpool。

remote_filesystem_read_prefetch​

在从远程文件系统读取数据时是否应该使用预取。

remote_fs_read_backoff_max_tries​

最大带回尝试次数。

remote_fs_read_max_backoff_ms​

尝试从远程磁盘读取数据时的最大等待时间。

remote_read_min_bytes_for_seek​

远程读取（url、s3）进行查找所需的最小字节数，而不是忽略读取。

rename_files_after_processing​

  • 类型： 字符串

  • 默认值： 空字符串

此设置允许为通过 file 表函数处理的文件指定重命名模式。当选项设置为成功处理文件时，所有通过 file 表函数读取的文件将根据指定的模式和占位符重命名。

占位符​

  • %a — 完整的原始文件名（例如 "sample.csv"）。
  • %f — 无扩展名的原始文件名（例如 "sample"）。
  • %e — 带点的原始文件扩展名（例如 ".csv"）。
  • %t — 时间戳（以微秒为单位）。
  • %% — 百分号 ("%")。

示例​

  • 选项： --rename_files_after_processing="processed_%f_%t%e"

  • 查询： SELECT * FROM file('sample.csv')

如果成功读取 sample.csv，文件将重命名为 processed_sample_1683473210851438.csv。

replace_running_query​

在使用 HTTP 接口时，可以传递 'query_id' 参数。这是充当查询标识符的任意字符串。 如果此时同一用户的查询中已存在相同 'query_id' 的查询，则行为取决于 'replace_running_query' 参数。

0（默认） – 抛出异常（不允许运行已有相同 'query_id' 的查询）。

1 – 取消旧查询并开始运行新查询。

将此参数设置为 1 以实现分割条件的建议。在输入下一个字符后，如果旧查询尚未完成，则应取消。

replace_running_query_max_wait_ms​

当 replace_running_query 设置处于活动状态时，运行相同 query_id 的查询完成的等待时间。

可能的值：

  • 正整数。
  • 0 - 抛出异常，不允许在服务器已执行相同 query_id 的查询时运行新查询。

replication_wait_for_inactive_replica_timeout​

指定等待非活动副本执行 ALTER、OPTIMIZE 或 TRUNCATE 查询多长时间（以秒为单位）。

可能的值：

  • 0 - 不等待。
  • 负整数 - 等待无限时间。
  • 正整数 - 等待的秒数。

restore_replace_external_dictionary_source_to_null​

在恢复时将外部字典源替换为 Null。用于测试目的。

restore_replace_external_engines_to_null​

仅用于测试目的。将所有外部引擎替换为 Null，以避免启动外部连接。

restore_replace_external_table_functions_to_null​

仅用于测试目的。将所有外部表函数替换为 Null，以避免启动外部连接。

restore_replicated_merge_tree_to_shared_merge_tree​

在恢复期间将表引擎从 ReplicatedMergeTree 替换为 SharedMergeTree。

result_overflow_mode​

云默认值： throw

如果结果的量超过某一限制，则设置该怎么办。

可能的值：

  • throw：抛出异常（默认）。
  • break：停止执行查询并返回部分结果，仿佛源数据已用尽。

使用 'break' 类似于使用 LIMIT。 Break 仅在块级别中中断执行。这意味着返回的行数大于 max_result_rows，是 max_block_size 的倍数，并且取决于 max_threads。

示例

rewrite_count_distinct_if_with_count_distinct_implementation​

允许您使用 count_distinct_implementation 设置重写 countDistinctIf 。

可能的值：

  • true — 允许。
  • false — 禁止。

s3_allow_multipart_copy​

允许在 S3 中进行分块复制。

s3_allow_parallel_part_upload​

使用多个线程进行 s3 分块上传。这可能会导致略微更高的内存使用。

s3_check_objects_after_upload​

对每个已上传对象执行头请求，以确保上传成功。

s3_connect_timeout_ms​

S3 磁盘主机的连接超时。

s3_create_new_file_on_insert​

在 s3 引擎表中，每次插入时启用或禁用创建新文件。如果启用，每次插入将创建一个新的 S3 对象，其键类似于以下模式：

初始： data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz 等等。

可能的值：

  • 0 — INSERT 查询创建新文件，或如果文件已存在且未设置 s3_truncate_on_insert，则失败。
  • 1 — INSERT 查询在每次插入时使用后缀（从第二个开始）创建新文件，前提是未设置 s3_truncate_on_insert。

有关更多详细信息，请参见 这里。

s3_disable_checksum​

在将文件发送到 S3 时不计算校验和。这通过避免对文件进行过多的处理来加快写入速度。由于 MergeTree 表中的数据仍由 ClickHouse 进行校验和，因此这在大多数情况下是安全的，并且当通过 HTTPS 访问 S3 时，TLS 层已经在网络传输中提供了完整性。虽然在 S3 上额外的校验和可以提供深层防御。

s3_ignore_file_doesnt_exist​

如果读取某些键时文件不存在，则忽略缺失。

可能的值：

  • 1 — SELECT 返回空结果。
  • 0 — SELECT 抛出异常。

s3_list_object_keys_size​

通过 ListObject 请求可以批量返回的最大文件数量。

s3_max_connections​

每个服务器的最大连接数。

s3_max_get_burst​

在达到每秒请求限制之前同时发出的最大请求数。默认情况下（0）等于 s3_max_get_rps。

s3_max_get_rps​

对 S3 GET 请求的每秒速率进行限制，然后进行限流。零表示无限制。

s3_max_inflight_parts_for_one_file​

在分块上传请求中，要并发加载的最大部分数。0 表示无限制。

s3_max_part_number​

S3 上传部分的最大部分编号。

s3_max_put_burst​

在达到每秒请求限制之前同时发出的最大请求数。默认情况下（0）等于 s3_max_put_rps。

s3_max_put_rps​

对 S3 PUT 请求的每秒速率进行限制，然后进行限流。零表示无限制。

s3_max_redirects​

允许的 S3 重定向跳转的最大数量。

s3_max_single_operation_copy_size​

S3 中单次操作复制的最大大小。此设置仅在 s3_allow_multipart_copy 为 true 时使用。

s3_max_single_part_upload_size​

使用单次上传到 S3 的对象的最大大小。

s3_max_single_read_retries​

在单次 S3 读取过程中最大的重试次数。

s3_max_unexpected_write_error_retries​

在 S3 写入时遇到意外错误时的最大重试次数。

s3_max_upload_part_size​

在 multipart 上传到 S3 时的最大部分大小。

s3_min_upload_part_size​

在 multipart 上传到 S3 时的最小部分大小。

s3_request_timeout_ms​

与 S3 发送和接收数据的空闲超时。如果单个 TCP 读取或写入调用阻塞超过此时间，则失败。

s3_retry_attempts​

用于 Aws::Client::RetryStrategy 的设置，Aws::Client 自行进行重试，0 表示不重试。

s3_skip_empty_files​

在 S3 引擎表中启用或禁用跳过空文件。

可能的值：

  • 0 — 如果空文件与请求格式不兼容，SELECT 将抛出异常。
  • 1 — 对于空文件，SELECT 返回空结果。

s3_slow_all_threads_after_network_error​

设置为 true 时，在某个 S3 请求因可重试的网络错误而失败后，所有执行 S3 请求的线程将在一段时间内减慢。 设置为 false 时，每个执行 S3 请求的线程在网络错误时使用独立的退避时间。

s3_strict_upload_part_size​

在 multipart 上传到 S3 时确切的部分大小（某些实现不支持可变大小的部分）。

s3_throw_on_zero_files_match​

当 ListObjects 请求无法匹配任何文件时抛出错误。

s3_truncate_on_insert​

启用或禁用在 S3 引擎表中的插入前截断。如果禁用，在尝试插入时，如果 S3 对象已存在，则将抛出异常。

可能的值：

  • 0 — INSERT 查询创建新文件，或如果文件已存在而未设置 s3_create_new_file_on_insert，则失败。
  • 1 — INSERT 查询用新数据替换文件的现有内容。

有关更多详细信息，请参见 这里。

s3_upload_part_size_multiply_factor​

每当从单次写入到 S3 上传的 s3_multiply_parts_count_threshold 部分时，将 s3_min_upload_part_size 乘以此因子。

s3_upload_part_size_multiply_parts_count_threshold​

每次上传到 S3 的部分数量达到此数时，将 s3_min_upload_part_size 乘以 s3_upload_part_size_multiply_factor。

s3_use_adaptive_timeouts​

设置为 true 时，所有 S3 请求前两个尝试都以较低的发送和接收超时进行。 设置为 false 时，所有尝试都以相同的超时进行。

s3_validate_request_settings​

启用 S3 请求设置验证。

可能的值：

  • 1 — 验证设置。
  • 0 — 不验证设置。

s3queue_default_zookeeper_path​

S3Queue 引擎的默认 zookeeper 路径前缀。

s3queue_enable_logging_to_s3queue_log​

启用写入 system.s3queue_log。可以通过表设置覆盖该值。

s3queue_migrate_old_metadata_to_buckets​

将 S3Queue 表的旧元数据结构迁移到新结构。

schema_inference_cache_require_modification_time_for_url​

在进行最后修改时间验证（对于带有 Last-Modified 标头的 URL）时从缓存使用架构。

schema_inference_use_cache_for_azure​

在使用 Azure 表函数时在架构推断中使用缓存。

schema_inference_use_cache_for_file​

在使用文件表函数时在架构推断中使用缓存。

schema_inference_use_cache_for_hdfs​

在使用 HDFS 表函数时在架构推断中使用缓存。

schema_inference_use_cache_for_s3​

在使用 S3 表函数时在架构推断中使用缓存。

schema_inference_use_cache_for_url​

在使用 URL 表函数时在架构推断中使用缓存。

secondary_indices_enable_bulk_filtering​

启用索引的批量过滤算法。预计总是更好，但我们有此设置以便兼容和控制。

select_sequential_consistency​

备注

此设置在 SharedMergeTree 和 ReplicatedMergeTree 之间的行为不同，更多信息请参见 SharedMergeTree 一致性。

启用或禁用 SELECT 查询的顺序一致性。需要禁用 insert_quorum_parallel（默认启用）。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

使用

启用顺序一致性时，ClickHouse 允许客户端仅对所有之前执行的 INSERT 查询包含数据的副本执行 SELECT 查询。如果客户端引用部分副本，ClickHouse 将生成异常。SELECT 查询将不包括尚未写入副本 quorum 的数据。

当 insert_quorum_parallel 启用时（默认为启用），则 select_sequential_consistency 不起作用。这是因为并行 INSERT 查询可以写入不同的副本 quorum，因此没有保证单个副本会接收到所有写入。

另请参见：

send_logs_level​

要向客户端发送具有指定最低级别的服务器文本日志。有效值：'trace', 'debug', 'information', 'warning', 'error', 'fatal', 'none'。

send_logs_source_regexp​

发送与指定正则表达式匹配的日志源名称的服务器文本日志。空意味着所有源。

send_progress_in_http_headers​

启用或禁用在 clickhouse-server 响应中包含 X-ClickHouse-Progress HTTP 响应头。

有关更多信息，请参见 HTTP 接口描述。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

send_timeout​

向网络发送数据的超时（以秒为单位）。如果客户端需要发送数据，但在此间隔内无法发送任何字节，则抛出异常。如果您在客户端设置此设置，则相应连接端上的 'receive_timeout' 也将在服务器上设置。

serialize_query_plan​

序列化用于分布式处理的查询计划。

session_timezone​

Beta feature. Learn more.

设置当前会话或查询的隐式时区。 隐式时区是应用于没有显式指定时区的 DateTime/DateTime64 类型值的时区。 此设置优先于全局配置的（服务器级别）隐式时区。 值为 ''（空字符串）意味着当前会话或查询的隐式时区等于 服务器时区。

您可以使用函数 timeZone() 和 serverTimeZone() 获取会话时区和服务器时区。

可能的值：

  • 来自 system.time_zones 的任意时区名称，例如 Europe/Berlin、UTC 或 Zulu。

示例：

将会话时区 'America/Denver' 分配给未显式指定时区的内部 DateTime：

危险

并非所有解析 DateTime/DateTime64 的函数均尊重 session_timezone。这可能导致细微错误。 请参见以下示例和说明。

这一现象是由于不同的解析流程造成的：

  • toDateTime() 在第一条 SELECT 查询中未显式给出时区，遵循设置的 session_timezone 和全局时区。
  • 在第二个查询中，从字符串解析 DateTime，并继承现有列 d 的类型和时区。因此，设置 session_timezone 和全局时区不会得到遵循。

另请参见

set_overflow_mode​

设置数据量超过某一限制时发生的事情。

可能的值：

  • throw：抛出异常（默认）。
  • break：停止执行查询并返回部分结果，仿佛源数据已用尽。

shared_merge_tree_sync_parts_on_partition_operations​

在 SMT 表中进行 MOVE | REPLACE | ATTACH 分区操作后自动同步数据部分集。仅限云。

short_circuit_function_evaluation​

允许根据 短路方案 计算 if、multiIf、and 和 or 函数。这有助于优化这些函数中复杂表达式的执行并防止可能的异常（例如，在未预期的情况下除以零）。

可能的值：

  • enable — 启用适用于短路的函数的短路函数评估（可能抛出异常或计算繁重）。
  • force_enable — 为所有函数启用短路函数评估。
  • disable — 禁用短路函数评估。

short_circuit_function_evaluation_for_nulls​

优化当任一参数为 NULL 时返回 NULL 的函数评估。当函数参数中的 NULL 值所占的比例超过 short_circuit_function_evaluation_for_nulls_threshold 时，系统会跳过逐行评估该函数。相反，它立即对所有行返回 NULL，从而避免不必要的计算。

short_circuit_function_evaluation_for_nulls_threshold​

NULL 值的比率阈值，仅在所有参数中非 NULL 值的行上执行具有 Nullable 参数的函数。当包含 NULL 值的行数与总行数的比例超过此阈值时，将不会评估包含 NULL 值的行。

show_table_uuid_in_table_create_query_if_not_nil​

设置 SHOW TABLE 查询显示。

可能的值：

  • 0 — 查询将不显示表 UUID。
  • 1 — 查询将显示表 UUID。

single_join_prefer_left_table​

在单次 JOIN 中，如果标识符模糊则优先选择左表。

skip_redundant_aliases_in_udf​

在用户定义函数中不使用（替换）冗余别名，以简化其用法。

可能的值：

  • 1 — 在 UDF 中跳过（替换）别名。
  • 0 — 在 UDF 中不跳过（替换）别名。

示例

启用和禁用之间的区别：

查询：

结果：

查询：

结果：

skip_unavailable_shards​

启用或禁用无声跳过不可用的分片。

如果所有副本不可用，则认为分片不可用。副本在以下情况下不可用：

  • ClickHouse 无法以任何原因连接到副本。

    连接到副本时，ClickHouse 会进行多次尝试。如果所有尝试都失败，则该副本被视为不可用。

  • 副本无法通过 DNS 解析。

    如果无法通过 DNS 解析副本的主机名，这可能表示以下情况：

    • 副本的主机没有 DNS 记录。这可能发生在动态 DNS 的系统中，例如 Kubernetes，在该系统中，节点在停机期间可能无法解析，这并不是错误。

    • 配置错误。ClickHouse 配置文件包含错误的主机名。

可能的值：

  • 1 — 启用跳过。

    如果分片不可用，ClickHouse 根据部分数据返回结果，而不报告节点可用性问题。

  • 0 — 禁用跳过。

    如果分片不可用，ClickHouse 抛出异常。

sleep_after_receiving_query_ms​

在 TCPHandler 中接收查询后等待的时间。

sleep_in_send_data_ms​

在 TCPHandler 中发送数据时的等待时间。

sleep_in_send_tables_status_ms​

在 TCPHandler 中发送表状态响应时的等待时间。

sort_overflow_mode​

设置在排序之前收到的行数超过某一限制时发生的事情。

可能的值：

  • throw：抛出异常。
  • break：停止执行查询并返回部分结果。

split_parts_ranges_into_intersecting_and_non_intersecting_final​

在FINAL优化期间，将分片范围分为相交和不相交

splitby_max_substrings_includes_remaining_string​

控制函数 splitBy*() 的参数 max_substrings > 0 时，是否将剩余字符串包含在结果数组的最后一个元素中。

可能的值：

  • 0 - 剩余字符串将不会包含在结果数组的最后一个元素中。
  • 1 - 剩余字符串将包含在结果数组的最后一个元素中。这是Spark的split()函数和Python的'string.split()'方法的行为。

stop_refreshable_materialized_views_on_startup​

Experimental feature. Learn more.

在服务器启动时，防止调度可刷新的物化视图，就像使用SYSTEM STOP VIEWS一样。之后可以使用SYSTEM START VIEWS或SYSTEM START VIEW <name>手动启动它们。这也适用于新创建的视图。对不可刷新的物化视图没有影响。

storage_file_read_method​

从存储文件读取数据的方法，可以是read，pread，mmap之一。mmap方法不适用于clickhouse-server（它是为clickhouse-local设计的）。

storage_system_stack_trace_pipe_read_timeout_ms​

从管道读取信息的最大时间，以接收查询system.stack_trace表中线程的信息。此设置用于测试目的，不应由用户更改。

stream_flush_interval_ms​

在超时情况下，或当线程生成 max_insert_block_size行时对流式表有效。

默认值为7500。

值越小，数据越频繁地被刷新到表中。设置值过低会导致性能下降。

stream_like_engine_allow_direct_select​

允许对于Kafka、RabbitMQ、FileLog、Redis Streams和NATS引擎使用直接的SELECT查询。如果存在附加的物化视图，即使启用此设置，SELECT查询也是不允许的。

stream_like_engine_insert_queue​

当流式引擎从多个队列读取时，用户需要在写入时选择一个队列进行插入。由Redis Streams和NATS使用。

stream_poll_timeout_ms​

从/到流式存储轮询数据的超时。

system_events_show_zero_values​

允许从system.events中选择零值事件。

一些监控系统要求将所有指标值传递给它们，甚至当指标值为零时。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

示例

查询

结果

查询

结果

table_function_remote_max_addresses​

设置从模式生成的remote函数的最大地址数。

可能的值：

  • 正整数。

tcp_keep_alive_timeout​

在TCP开始发送保活探测之前，连接需要保持空闲的时间（秒数）

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds​

锁定缓存以便为临时数据在文件系统缓存中保留空间的等待时间

temporary_files_codec​

设置用于磁盘上排序和连接操作的临时文件的压缩编码。

可能的值：

  • LZ4 — 采用LZ4压缩。
  • NONE — 不使用压缩。

throw_if_deduplication_in_dependent_materialized_views_enabled_with_async_insert​

当设置deduplicate_blocks_in_dependent_materialized_views与async_insert同时启用时，在INSERT查询时引发异常。它保证了正确性，因为这些功能无法共存。

throw_if_no_data_to_insert​

允许或禁止空INSERT，默认启用（在空插入时引发错误）。仅适用于使用clickhouse-client或使用gRPC接口的INSERT操作。

throw_on_error_from_cache_on_write_operations​

在写操作缓存（INSERT，合并）时忽略来自缓存的错误。

throw_on_max_partitions_per_insert_block​

允许控制达到max_partitions_per_insert_block时的行为。

可能的值：

  • true - 当插入块达到max_partitions_per_insert_block时，引发异常。
  • false - 当达到max_partitions_per_insert_block时，记录警告。
提示

如果您尝试了解更改max_partitions_per_insert_block对用户的影响，这可能会很有用。

throw_on_unsupported_query_inside_transaction​

Experimental feature. Learn more.

如果在事务内部使用不支持的查询，则引发异常

timeout_before_checking_execution_speed​

在指定的时间（秒数）过后，检查执行速度是否过慢（不低于min_execution_speed）。

timeout_overflow_mode​

设置当查询运行时间超过max_execution_time或估计运行时间超过max_estimated_execution_time时要怎么做。

可能的值：

  • throw: 抛出异常（默认）。
  • break: 停止执行查询并返回部分结果，仿佛源数据用完了。

timeout_overflow_mode_leaf​

设置当叶子节点中的查询运行时间超过max_execution_time_leaf时发生的情况。

可能的值：

  • throw: 抛出异常（默认）。
  • break: 停止执行查询并返回部分结果，仿佛源数据用完了。

totals_auto_threshold​

totals_mode = 'auto'的阈值。 请参见“WITH TOTALS修饰符”部分。

totals_mode​

在存在HAVING时，以及在存在max_rows_to_group_by和group_by_overflow_mode = 'any'时，如何计算TOTALS。 请参见“WITH TOTALS修饰符”部分。

trace_profile_events​

启用或禁用在更新配置事件时收集堆栈跟踪，连同配置事件的名称和增量的值，并将它们发送到trace_log。

可能的值：

  • 1 — 启用配置事件的跟踪。
  • 0 — 禁用配置事件的跟踪。

transfer_overflow_mode​

设置当数据量超过某个限制时的行为。

可能的值：

  • throw: 抛出异常（默认）。
  • break: 停止执行查询并返回部分结果，仿佛源数据用完了。

transform_null_in​

启用NULL值在IN操作符中的相等性。

默认情况下，NULL值不能进行比较，因为NULL表示未定义的值。因此，比较expr = NULL必须始终返回false。通过此设置，NULL = NULL在IN操作符中返回true。

可能的值：

  • 0 — 在IN操作符中比较NULL值返回false。
  • 1 — 在IN操作符中比较NULL值返回true。

示例

考虑null_in表：

查询：

结果：

查询：

结果：

另见

traverse_shadow_remote_data_paths​

在查询system.remote_data_paths时，遍历冻结数据（影子目录）以外的实际表数据。

union_default_mode​

设置合并SELECT查询结果的模式。此设置仅在与UNION共享时使用，而不显式指定UNION ALL或UNION DISTINCT。

可能的值：

  • 'DISTINCT' — ClickHouse在合并查询结果时输出去重行。
  • 'ALL' — ClickHouse输出合并查询结果的所有行，包括重复行。
  • '' — ClickHouse在与UNION一起使用时生成异常。

请参见UNION中的示例。

unknown_packet_in_send_data​

发送未知数据包而不是第N个数据数据包

update_parallel_mode​

确定并发更新查询的行为。

可能的值：

  • sync - 按顺序运行所有UPDATE查询。
  • auto - 仅按顺序运行在一个查询中更新的列与另一个查询中的表达式所用列之间有关联的UPDATE查询。
  • async - 不同步更新查询。

update_sequential_consistency​

如果为真，在执行更新之前将部分集合更新到最新版本。

use_async_executor_for_materialized_views​

使用异步且可能是多线程的执行物化视图查询，可以加速在INSERT期间的视图处理，但也会消耗更多内存。

use_cache_for_count_from_files​

启用在表函数file/s3/url/hdfs/azureBlobStorage中计算行数时的缓存。

默认启用。

use_client_time_zone​

使用客户端时区解释DateTime字符串值，而不是采用服务器时区。

use_compact_format_in_distributed_parts_names​

在后台（distributed_foreground_insert）INSERT到使用Distributed引擎的表时，使用紧凑格式存储块。

可能的值：

  • 0 — 使用user[:password]@host:port#default_database目录格式。
  • 1 — 使用[shard{shard_index}[_replica{replica_index}]]目录格式。
备注
  • 设置use_compact_format_in_distributed_parts_names=0时，来自集群定义的更改不会应用于后台INSERT。
  • 设置use_compact_format_in_distributed_parts_names=1时，改变集群定义中节点的顺序，将改变shard_index / replica_index，请注意。

use_concurrency_control​

遵循服务器的并发控制（详见全局服务器设置concurrent_threads_soft_limit_num和concurrent_threads_soft_limit_ratio_to_cores）。如果禁用，允许使用更大量的线程，即使服务器超载（不推荐正常使用，主要用于测试）。

use_hedged_requests​

启用远程查询的hedged请求逻辑。它允许为查询与不同副本建立多个连接。 当现有与副本的连接在hedged_connection_timeout内未建立或在receive_data_timeout内没有接收到数据时，启用新连接。查询使用第一个发送非空进度数据包（或数据数据包，如果allow_changing_replica_until_first_data_packet）的连接；其他连接将被取消。支持max_parallel_replicas > 1的查询。

默认启用。

在Cloud上默认禁用。

use_hive_partitioning​

启用时，ClickHouse将检测文件样式表引擎File/S3/URL/HDFS/AzureBlobStorage中的路径中的Hive样式分区（/name=value/），并允许在查询中使用分区列作为虚拟列。这些虚拟列的名称与分区路径中的名称相同，但以_开头。

use_iceberg_metadata_files_cache​

如果启用，冰山表函数和冰山存储可以利用冰山元数据文件缓存。

可能的值：

  • 0 - 禁用
  • 1 - 启用

use_iceberg_partition_pruning​

用于冰山表的冰山分区修剪

use_index_for_in_with_subqueries​

如果在IN操作符的右侧有子查询或表表达式，则尝试使用索引进行过滤。

use_index_for_in_with_subqueries_max_values​

使用表索引进行过滤的IN操作符右侧集合的最大大小。它可以避免由于为大查询准备额外数据结构而导致的性能下降和内存使用增加。零意味着没有限制。

use_json_alias_for_old_object_type​

启用时，将使用JSON数据类型别名以创建旧的Object('json')类型，而不是新的JSON类型。

use_page_cache_for_disks_without_file_cache​

对于未启用文件系统缓存的远程磁盘，使用用户空间页面缓存。

use_page_cache_with_distributed_cache​

在使用分布式缓存时使用用户空间页面缓存。

use_query_cache​

如果启用，SELECT查询可以利用查询缓存。参数enable_reads_from_query_cache和enable_writes_to_query_cache更详细地控制缓存的使用。

可能的值：

  • 0 - 禁用
  • 1 - 启用

use_query_condition_cache​

启用查询条件缓存。该缓存存储不满足WHERE子句条件的数据部分中的粒度范围，并在后续查询中重复使用该信息作为临时索引。

可能的值：

  • 0 - 禁用
  • 1 - 启用

use_skip_indexes​

在执行查询期间使用数据跳过索引。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

use_skip_indexes_if_final​

控制在执行带有FINAL修饰符的查询时，是否使用跳过索引。

默认情况下，这个设置是禁用的，因为跳过索引可能会排除包含最新数据的行（粒度），这可能导致不正确的结果。启用时，即使带有FINAL修饰符也会应用跳过索引，可能提高性能，但有错过最近更新的风险。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

use_skip_indexes_if_final_exact_mode​

控制查询执行中，跳过索引返回的粒度是否在新部分中展开，以返回正确的结果。

使用跳过索引可能会排除包含最新数据的行（粒度），这可能导致不正确的结果。该设置可以确保通过扫描与跳过索引返回的范围重叠的新部分，返回正确的结果。

可能的值：

  • 0 — 禁用。
  • 1 — 启用。

use_structure_from_insertion_table_in_table_functions​

使用插入表的结构，而不是从数据推断模式。可能的值：0 - 禁用，1 - 启用，2 - 自动

use_uncompressed_cache​

是否使用未压缩块的缓存。接受0或1。默认情况下，0（禁用）。 使用未压缩缓存（仅针对MergeTree家族中的表）可以显著降低延迟并提高处理大量短查询的吞吐量。对于频繁发送短请求的用户启用此设置。还需注意uncompressed_cache_size配置参数（仅在配置文件中设置） - 未压缩缓存块的大小。默认为8 GiB。未压缩缓存根据需要填充，最少使用的数据会被自动删除。

对于读取至少一定数据量（百万行或更多）的查询，自动禁用未压缩缓存以节省真正小查询的空间。这意味着您可以始终将'使用未压缩缓存'设置为1。

use_variant_as_common_type​

允许将Variant类型用作if/multiIf/array/map函数的返回类型，当参数类型没有共同类型时。

示例：

use_with_fill_by_sorting_prefix​

ORDER BY子句中与WITH FILL列前面的列形成排序前缀。排序前缀中具有不同值的行独立填充

validate_enum_literals_in_operators​

如果启用，在IN，NOT IN，==，!=等操作符中验证枚举字面值是否与枚举类型一致，并且如果字面值不是有效的枚举值，则引发异常。

validate_mutation_query​

接受变更查询之前验证它们。变更将在后台执行，运行无效查询将导致变更卡住，需要手动干预。

仅在您遇到向后不兼容的错误时更改此设置。

validate_polygons​

启用或禁用在pointInPolygon函数中抛出异常，如果多边形是自相交或自切线。

可能的值：

  • 0 — 禁用抛出异常。pointInPolygon接受无效多边形，并可能为它们返回不正确的结果。
  • 1 — 启用抛出异常。

vector_search_filter_strategy​

Beta feature. Learn more.

如果向量搜索查询有WHERE子句，则此设置决定是先评估（预过滤）还是先检查向量相似度索引（后过滤）。可能的值：

  • 'auto' - 后过滤（具体语义可能会在未来更改）。
  • 'postfilter' - 使用向量相似度索引识别最近邻，然后应用其他过滤器。
  • 'prefilter' - 先评估其他过滤器，然后执行暴力搜索以识别邻居。

vector_search_postfilter_multiplier​

Beta feature. Learn more.

在对其他谓词执行后过滤之前，从向量相似度索引获取的最近邻居乘以此数字。

wait_changes_become_visible_after_commit_mode​

Experimental feature. Learn more.

等待已提交的更改在最新快照中真正可见

wait_for_async_insert​

如果为真，等待异步插入处理

wait_for_async_insert_timeout​

等待异步插入处理的超时

wait_for_window_view_fire_signal_timeout​

Experimental feature. Learn more.

在事件时间处理过程中等待窗口视图触发信号的超时

window_view_clean_interval​

Experimental feature. Learn more.

窗口视图的清理间隔，以秒为单位，用于释放过时数据。

window_view_heartbeat_interval​

Experimental feature. Learn more.

以秒为单位的心跳间隔，用于指示监视查询处于活动状态。

workload​

用于访问资源的工作负载名称

write_through_distributed_cache​

ClickHouse Cloud only

仅在ClickHouse Cloud中生效。允许写入分布式缓存（写入s3也将通过分布式缓存进行）。

zstd_window_log_max​

允许您选择ZSTD的最大窗口日志（它不会用于MergeTree家族）