参数列表--ByteHouse云数仓版-火山引擎

文档中心

导航

参数列表

最近更新时间：2025.11.04 11:14:10首次发布时间：2025.05.13 17:27:44

本文将介绍 ByteHouse 支持设置的查询参数和表参数。

背景信息

如下表格介绍了本文中使用的术语。

名称	介绍
worker	用户计算组的节点。
Dedup	删除重复数据（Deduplication），是唯一键引擎为保证数据唯一性，通过去重来实现目标结果。
Dedup task	去重任务，由 dedup worker 选出去重任务，被选中的数据块（data parts）会由 dedup 任务执行完成后可见。
Dedup worker	去重计算节点，用于选择和执行 dedup 任务的运行实例，默认选择账户级别的写计算组。
Staging area	数据暂存区，位于默认缓存或计算组本地地盘中；可来实现去重数据的攒批和批处理。
Staged part	暂存区的数据块，位于默认缓存或计算组本地盘中；存储在暂存区的 part 数据，对查询不可见。

查询参数

数据查询（SELECT）

参数名	参数类型	可选值	无配置默认值	参数说明
enable_point_lookup_profile	Bool	true/false	false	是否使用点查 profile，用于优化点查效率。
max_threads	UInt64	0 ≤ X ≤ CPU 核心数	0	查询单机并行度。
max_plan_segment_num	UInt64	0 ≤ X	500	允许的最大计划段数，0 表示无限制。
enable_intermediate_result_cache	Bool	true/false	false	是否启用中间结果缓存。
log_segment_profiles	Bool	true/false	false	是否启用 ByteHouse SQL 性能诊断功能。
max_execution_time	UInt64	1 ≤ X ≤ 50000	您可登录 ByteHouse 云数仓版控制台，通过租户管理 > 参数设置 > 计算组参数路径，在计算组模块查看参考值。	最大执行时间，单位秒。
max_query_cpu_seconds	UInt64	0 ≤ X ≤ 3000		限制查询段可以消耗的最大 CPU 资源量，单位秒。
max_memory_usage	UInt64	1000 ≤ X ≤ Pod 最大内存		单个查询的最大内存使用量，单位字节。
distributed_max_parallel_size	UInt64	0 ≤ X ≤ 计算组 worker 数目	0	非 Source PlanSegment 并发度，0 代表计算组全部节点的数目，如果并发高或者计算组 worker 数目大于 10 个以上，建议调小。
join_algorithm	JoinAlgorithm	'grace_hash' 'auto', 'hash', 'partial_merge', 'prefer_partial_merge', 'parallel_hash', 'auto'	auto	选择 Join 算法。
max_memory_usage_ratio	Float	0.01 ≤ X ≤ 0.99	无	单个查询的最大内存使用比例。

您可登录 ByteHouse 云数仓版控制台，通过租户管理 > 参数设置 > 计算组参数路径，在计算组模块查看参考值。

数据写入（INSERT）

参数名	参数类型	可选值	无配置默认值	参数说明
enable_unique_partial_update	Bool	true/false	true	是否使用部分列更新模式。需要配合表级同名参数来使用，当且仅当该参数和表级都开启时部分列更新模式生效。
partial_update_enable_row_level_defaults	Bool	true/false	true	当部分列更新时，未更新的列用行级默认值填充。
staging_area_wait_mode	StagingAreaWaitMode	no_wait/wait_txn_visible	no_wait	开启暂存区后，数据写入模式。`no_wait` 表示异步写入模式，`wait_txn_visible` 表示同步写入模式。
enable_staging_area_for_write	Bool	true/false	false	是否开启暂存区，可支持异步写入或者并发写入优化场景。
optimize_unique_table_write	Bool	true/false	false	针对唯一键表 `INSERT SELECT` 导入优化开关。建议仅在未开启暂存区且 `dedup_impl_version='dedup_in_txn_commit'` 的场景下开启。
max_insert_threads	UInt64	正整数	0	用于配置 Worker 节点执行 `INSERT SELECT` 请求时，写入操作对应的线程池大小。
min_insert_block_size_bytes	UInt64	正整数	1073710080	控制 `INSERT SELECT` 操作中，数据攒批 block 块的最小大小，单位为字节（byte）。
min_insert_block_size_rows	UInt64	正整数	1048545	控制 `INSERT SELECT` 操作中，数据攒批 block 块的最小行数。

表参数

参数名	参数类型	可选值	无配置默认值	参数说明
唯一键表去重相关
unique_table_dedup_threads	MaxThreads	不超过 core 数的整数值	8	每个 dedup 任务执行时会拆成不同去重粒度的子任务，该参数可配置执行这些子任务的线程池大小。
cloud_enable_staging_area	Bool	true/false	false	是否开启暂存区，可支持异步写入或者并发写入优化场景。
cloud_staging_area_wait_mode	StagingAreaWaitMode	no_wait/wait_txn_visible	no_wait	开启暂存区后，数据写入模式。`no_wait` 表示异步写入模式，`wait_txn_visible` 表示同步写入模式。
min_check_txn_staging_area_visible_interval	UInt64	整数	50	开启暂存区，且写入模式为 wait_txn_visible 时，轮询数据是否已经可见的最小检查间隔，单位为毫秒（ms）。
max_check_txn_staging_area_visible_interval	UInt64	整数	1000	开启暂存区，且写入模式为 wait_txn_visible 时，轮询数据是否已经可见的最大检查间隔，单位为毫秒（ms）。
max_dedup_worker_number	UInt64	整数	1	Dedup worker 的数量，建议和 cnch_vw_write 设置的计算组 pod 数保持一致。
pick_dedup_worker_by_mod	Bool	true/false	false	Dedup worker 的分布模式，配置为 true 时，将按计算组的节点总数取模，可以保证分布均匀；默认为 false 时，将按照 hash 值分布，不一定均匀。
max_staged_part_number_per_task	UInt64	整数	100	每个选出的 dedup task 最大的 staged part 数量。
max_staged_part_rows_per_task	UInt64	整数	15000000	每个选出的 dedup task 最大的 staged part 总行数。
dedup_impl_version	DedupImplVersion	dedup_in_write_suffix/ dedup_in_txn_commit	dedup_in_write_suffix	去重实现，`dedup_in_write_suffix` 在写入阶段结束时执行去重逻辑；`dedup_in_txn_commit` 在事务预提交阶段执行去重逻辑，为优化版本。
后台任务相关
enable_addition_bg_task	Bool	true/false	false	是否允许更多的 merge 任务同时运行。
max_partition_for_multi_select	UInt64	整数	10	merge 任务会先选分区（ partitions），再从分区中选范围（range），如果是分区很多通常需要将这个值调大。
max_addition_bg_task_num	UInt64	整数	32	限制最大并发的后台任务数量。
cnch_merge_enable_batch_select	Bool	true/false	true	batch_select 会每轮（round）选一大批范围，之后的轮次会直接提交（submit）这些范围，缩短 merge 操作的触发周期，从而让总任务量真正达到并发上限。
cnch_merge_max_total_rows_to_merge	UInt64	整数	50000000	单个 merged part 的最大行数。
部分列更新功能相关
enable_unique_partial_update	Bool	true/false	false	表是否开启部分列更新能力。
partial_update_max_process_parts	UInt64	整数	100	部分列更新执行任务时会按照该参数切分子任务。
partial_update_query_parts_thread_size	MaxThreads	不超过 core 数的整数值	8	部分列更新任务执行时读历史数据的线程池大小。
partial_update_replace_columns_thread_size	MaxThreads	不超过 core 数的整数值	8	部分列更新模式下，替换列阶段的线程池大小。
partial_update_replace_if_not_null	Bool	true/false	false	部分列更新模式下，只有当非 null 值时执行更新操作。