add_http_cors_header
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_inline_views
any_join_distinct_right_table_keys
ANY INNER|LEFT JOIN 操作中的旧版 ClickHouse server 行为。
仅当你的用例依赖旧版
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 — 旧版行为已启用。
archive_adaptive_buffer_max_size_bytes
arrow_flight_request_descriptor_type
- ‘path’ — 使用 FlightDescriptor::Path (默认值,适用于大多数 Arrow Flight 服务器)
- ‘command’ — 使用包含 SELECT 查询的 FlightDescriptor::Command (Dremio 需要这种方式)
backup_slow_all_threads_after_retryable_s3_error
true 时,只要有任意一个 S3 请求遇到可重试的 S3 错误 (例如 ‘Slow Down’) ,
所有向同一备份端点发起 S3 请求的线程都会被放慢。
当设置为 false 时,每个线程都会独立处理 S3 请求的退避,而不受其他线程影响。
cache_warmer_threads
calculate_text_stack_trace
cancel_http_readonly_queries_on_client_close
SELECT) 。
Cloud 默认值:1。
checksum_on_read
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,但结果集完全相同——布尔逻辑并未改变:
count_matches_stop_at_empty_match
countMatches 函数中,一旦模式匹配到零长度内容,就停止计数。
cross_to_inner_join_rewrite
data_type_default_nullable
- 1 — 列定义中的数据类型默认设置为
Nullable。 - 0 — 列定义中的数据类型默认不设置为
Nullable。
decimal_check_overflow
deduplicate_blocks_in_dependent_materialized_views
- 0 — 禁用。
- 1 — 启用。
defer_partition_pruning_after_final
FINAL 查询会跳过分区裁剪。这是 26.3 引入的、可确保正确性的行为:FINAL 可能需要对主键相同但位于不同分区的行进行去重,而分区裁剪会在不提示的情况下将这些行排除在去重输入之外。
禁用时,即使使用 FINAL 也会应用分区裁剪,从而恢复 26.3 之前的行为。对于在分区列上带有 WHERE 条件的查询,这种方式可能会显著更快,但只有在不同分区中不可能存在主键相同的行时才是正确的——例如事件日志表,其分区列在 insert 时设定,之后永不更改。
此设置仅影响分区键列未包含在 sorting key 中的分区表;对于其他表,始终会应用分区裁剪。
可能的值:
- 0 — 在
FINAL之前应用分区裁剪 (26.3 之前的行为,更快,但一般情况下不安全) 。 - 1 — 将分区裁剪延后到
FINAL之后 (默认,确保正确性) 。
describe_compact_output
方言
discard_query_data
distinct_overflow_mode
throw:抛出异常 (默认) 。break:停止执行查询并返回部分结果,就像源数据已耗尽一样。
do_not_merge_across_partitions_select_final
dynamic_throw_on_type_mismatch
true(默认) — 抛出异常。false— 对这些行返回NULL。
enforce_strict_identifier_format
engine_url_skip_empty_files
- 0 — 如果空文件与所请求的格式不兼容,
SELECT会抛出异常。 - 1 — 对于空文件,
SELECT返回空结果。
exact_rows_before_limit
except_default_mode
exclude_materialize_skip_indexes_on_insert
execute_exists_as_scalar_subquery
0。
explain_query_plan_default
EXPLAIN PLAN 使用的默认输出格式。
可能的值:
pretty(自 26.7 起为默认值) —actions、compact和pretty默认均为true,生成紧凑、美观且带有 action 注释的计划。legacy— 26.7 之前的输出。
EXPLAIN 语句中显式指定 actions、compact 或 pretty 选项 (例如,EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) 始终会覆盖此设置。
带有 json = 1 或 distributed = 1 的 EXPLAIN PLAN 无论此设置如何,都会保留 legacy (26.7 之前) 的默认值,除非显式设置了 actions、compact 或 pretty。pretty 输出无法表示 JSON 结果或按分片划分的分布式查询计划,因此这些模式只有以 legacy 形式呈现时才能正确显示。
extract_key_value_pairs_max_pairs_per_row
extract_kvp_max_pairs_per_row
extractKeyValuePairs 函数可生成的键值对的最大数量。用于防止占用过多内存。
extremes
fallback_to_stale_replicas_for_distributed_queries
SELECT 时。
默认值为 1 (已启用) 。
file_like_engine_default_partition_strategy
filesystem_prefetches_limit
filesystem_prefetches_max_memory_usage
final
- 0 - 已禁用
- 1 - 已启用
finalize_projection_parts_synchronously
flatten_nested
- 1 — Nested 列会被展平为单独的数组。
- 0 — Nested 列保持为单个元组数组。
0,则可以使用任意层级的嵌套。
示例
查询:
fsync_metadata
.sql 文件时是否启用 fsync。默认启用。
如果 server 中有数百万个持续创建和删除的小表,禁用此项是合理的。
functions_h3_default_if_invalid
geo_distance_returns_float64_on_float64_arguments
geoDistance、greatCircleDistance 和 greatCircleAngle 这三个函数的四个参数均为 Float64,则返回 Float64,并在内部计算中使用双精度。在此前的 ClickHouse 版本中,这些函数始终返回 Float32。
geotoh3_argument_order
geoToH3 在设置为 lon_lat 时接受 (lon, lat),在设置为 lat_lon 时接受 (lat, lon)。
glob_expansion_max_elements
h3togeo_lon_lat_result_order
h3ToGeo 返回 (lon, lat);否则返回 (lat, lon)。
handshake_timeout_ms
hedged_connection_timeout_ms
highlight_max_matches_per_row
- 正整数。
hnsw_candidate_list_size_for_search
hsts_max_age
idle_connection_timeout
- 正整数 (0 表示立即关闭,即 0 秒后关闭) 。
inject_random_order_for_select_without_order_by
interactive_delay
intersect_default_mode
least_greatest_legacy_null_behavior
least 和 greatest 的任一参数为 NULL 时,将返回 NULL。
legacy_column_name_of_tuple_literal
limit
- 0 — 行数不受限制。
- 正整数。
load_marks_asynchronously
1。
lock_acquire_timeout
DEADLOCK_AVOIDED。
Possible values:
- 正整数 (单位:秒) 。
- 0 — 不设置锁超时。
low_priority_query_wait_time_ms
priority) ,低优先级查询会等待高优先级查询完成。此设置指定等待时长。
make_distributed_plan
merge_table_max_tables_to_look_for_schema_inference
Merge 表,或使用 merge 表函数时,会将 schema 推断为匹配表的并集,数量不超过指定值。
如果表的数量更多,则只会基于前面指定数量的表来推断 schema。
mongodb_throw_on_unsupported_query
allow_experimental_analyzer=0 时,此选项不适用。
multiple_joins_try_to_keep_original_names
normalize_function_names
offset
- 0 — 不跳过任何行。
- 正整数。
paimon_target_snapshot_id
parallelize_output_from_storages
partial_result_on_first_cancel
per_part_index_stats
poll_interval
polyglot_dialect
postgresql_fault_injection_probability
predicate_statistics_sample_rate
system.predicate_statistics_log。设置为 N > 0 时,将按查询 ID 对约 1/N 的查询进行采样。0 表示禁用。
prefetch_buffer_size
print_pretty_type_names
DESCRIBE 查询和 toTypeName() 函数中,以带缩进的美观格式输出深层嵌套的类型名称。
示例:
priority
push_external_roles_in_interserver_queries
query_metric_log_interval
collect_interval_milliseconds 值;如果未设置,则默认使用 1000。
要禁用单个查询的收集,请将 query_metric_log_interval 设置为 0。
默认值:-1
queue_max_wait_ms
rabbitmq_max_wait_ms
readonly
readonly 设置外的其他设置。
recursive_cte_max_steps_in_type_inference
getLeastSupertype,直到结果收敛。设为 0 可禁用类型拓宽,仅使用非递归部分的类型。
regexp_max_matches_per_row
- 正整数。
reject_expensive_hyperscan_regexps
remerge_sort_lowered_memory_bytes_ratio
remote_read_min_bytes_for_seek
rename_files_after_processing
- 类型: String
- 默认值: 空字符串
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
replication_wait_for_inactive_replica_timeout
ALTER、OPTIMIZE 或 TRUNCATE 查询的时间 (以秒为单位) 。
可能的值:
0— 不等待。- 负整数 — 无限期等待。
- 正整数 — 要等待的秒数。
reserve_memory
workload 的值进行。
如果该工作负载没有足够的可用内存,查询将无法启动,并会保持在待处理状态,直到能够满足预留要求。
值为 0 表示不预留内存。
仅当创建了 MEMORY RESERVATION 资源时,此设置才会生效。
在 RESTORE 时,将表引擎从 ReplicatedMergeTree 替换为 SharedMergeTree。
Cloud 默认值:1。
result_overflow_mode
throw:抛出异常 (默认) 。break:停止执行查询并返回部分结果,就像 源数据已经耗尽一样。
Break 只会在
块级别中断执行。这意味着返回的行数会大于
max_result_rows,且是 max_block_size
的倍数,并且取决于 max_threads。
示例
Query
Result
rows_before_aggregation
secondary_indices_enable_bulk_filtering
select_sequential_consistency
此设置在 SharedMergeTree 和 ReplicatedMergeTree 中的行为不同。有关
select_sequential_consistency 在 SharedMergeTree 中的行为的更多信息,请参阅 SharedMergeTree 一致性。SELECT 查询启用或禁用顺序一致性。要求禁用 insert_quorum_parallel (默认情况下启用) 。
Possible values:
- 0 — 禁用。
- 1 — 启用。
insert_quorum 执行的 INSERT 查询数据的副本上执行 SELECT 查询。如果客户端访问的是不完整的副本,ClickHouse 将抛出异常。SELECT 查询不会包含尚未写入到法定数量副本中的数据。
启用 insert_quorum_parallel (默认值) 时,select_sequential_consistency 将不起作用。这是因为并行 INSERT 查询可能会写入不同的法定数量副本集合,因此无法保证某一个副本已接收到所有写入。
See also:
session_timezone
timeZone() 和 serverTimeZone() 获取会话时区和 server 时区。
可能的值:
system.time_zones中的任意时区名称,例如Europe/Berlin、UTC或Zulu
- 第一个
SELECT查询中,未显式指定 time zone 的toDateTime()会遵循session_timezone设置和全局 time zone。 - 在第二个查询中,日期时间是从 String 解析而来,并继承现有列
d的类型和 time zone。因此,session_timezone设置和全局 time zone 都不会生效。
set_overflow_mode
throw:抛出异常 (默认值) 。break:停止执行查询并返回部分结果,就像 源数据已经耗尽一样。
single_join_prefer_left_table
skip_redundant_aliases_in_udf
- 1 — 在 UDFs 中跳过 (替换) 这些别名。
- 0 — 在 UDFs 中不跳过 (替换) 这些别名。
sleep_after_receiving_query_ms
snappy_mode
file 和 url) 中,snappy 压缩所使用的传输格式。HTTP Content-Encoding: snappy 始终使用 framing 格式,并会忽略此设置。
请注意,单次调用 snappy::Compress 生成的原始 snappy 块格式 (例如由 SnappyBasicReadBuffer 处理的 Prometheus 远程协议载荷) 属于另一种特定于协议的传输格式,不受此设置控制。
可能的值:
basic— Hadoop snappy 块格式。兼容 Hadoop 读写的文件。支持读取和写入。framed— Snappy framing 格式,即 Google 定义的标准流式格式。支持读取和写入。
sort_overflow_mode
throw:抛出异常。break:停止执行查询并返回部分结果。
splitby_max_substrings_includes_remaining_string
max_substrings > 0 的 splitBy*() 函数是否会将剩余字符串包含在结果数组的最后一个元素中。
可能的值:
0- 剩余字符串不会包含在结果数组的最后一个元素中。1- 剩余字符串会包含在结果数组的最后一个元素中。这是 Spark 的split()函数和 Python 的string.split()方法的行为。
stop_refreshable_materialized_views_on_startup
SYSTEM START VIEWS 或 SYSTEM START VIEW <name> 启动它们。此设置也适用于新创建的视图。对不可刷新的 materialized view 无效。
tcp_keep_alive_timeout
temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds
throw_if_no_data_to_insert
ClickHouse 客户端 或 gRPC 接口 执行的 INSERT。
timeout_before_checking_execution_speed
min_execution_speed) 。
transfer_overflow_mode
throw:抛出异常 (默认) 。break:停止执行查询并返回部分结果,仿佛 源数据已经耗尽。
transform_null_in
NULL 值不能参与比较,因为 NULL 表示未定义的值。因此,比较 expr = NULL 必须始终返回 false。启用此设置后,对于 IN 运算符,NULL = NULL 会返回 true。
可能的值:
- 0 —
IN运算符中对NULL值的比较返回false。 - 1 —
IN运算符中对NULL值的比较返回true。
null_in 表为例:
traverse_shadow_remote_data_paths
union_default_mode
SELECT 查询结果的模式。只有在使用 UNION 且未显式指定 UNION ALL 或 UNION DISTINCT 时,此设置才会生效。
可能的值:
'DISTINCT'— ClickHouse 在合并查询结果时会去除重复行。'ALL'— ClickHouse 在合并查询结果时会保留所有行,包括重复行。''— 与UNION一起使用时,ClickHouse 会引发异常。
unique_key_max_encoded_size
UNIQUE KEY 行的保序二进制编码的最大大小 (以字节为单位) 。
unknown_packet_in_send_data
variant_throw_on_type_mismatch
true(默认) — 抛出异常。false— 改为对这些行返回NULL。