大网数据广告活动
数据库部署与 SQL 参考

BE 配置项 - 查询引擎和导入导出

· 52CE 我爱测

# BE 配置项 - 查询引擎和导入导出 ## 查看 BE 配置项 您可以通过以下命令查看 BE 配置项: ## 配置 BE 参数 --- 当前主题包含以下类型的 BE 配置: - 查询引擎 - 导入导出 ## 查询引擎 ### ai_function_request_timeout_ms - 默认值:600000 - 类型:Int - 单位:毫秒 - 有效值:非负整数 - 是否动态:是 - 描述:单个 AI task 的最长独立生命周

BE 配置项 - 查询引擎和导入导出

查看 BE 配置项

您可以通过以下命令查看 BE 配置项:

SELECT * FROM information_schema.be_configs [WHERE NAME LIKE "%<name_pattern>%"]

配置 BE 参数


当前主题包含以下类型的 BE 配置:

查询引擎

ai_function_request_timeout_ms

  • 默认值:600000
  • 类型:Int
  • 单位:毫秒
  • 有效值:非负整数
  • 是否动态:是
  • 描述:单个 AI task 的最长独立生命周期,覆盖准入、首次 HTTP attempt、所有重试与 backoff,以及 completion 分类。这些阶段共用一个绝对 request deadline,不会在每次 attempt 时重新计时。在每个异步边界,实际 deadline 取该不可变 request deadline 与 Query 当前 deadline 中较早者;Query 取消和 deadline 更新在 task 的整个生命周期内始终实时生效。0 表示禁用独立的 request 限制,仅使用实时 Query 生命周期。需要更快终止慢模型调用时可调小该值。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_connect_timeout_ms

  • 默认值:10000
  • 类型:Int
  • 单位:毫秒
  • 有效值:非负整数
  • 是否动态:是
  • 描述:AI HTTP attempt 建立连接所允许的最长时间。启用独立 request deadline 时,transport 还会以剩余 request 生命周期限制连接建立时间,且不会延长该 deadline。0 表示禁用独立的连接限制。如果两个独立限制都为 0,transport 不设置静态 connection 或 request timeout,但仍会实时检查 Query 取消和 deadline。调小可更快发现无法访问的模型 endpoint;连接建立较慢的网络可适当调大。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_max_response_bytes

  • 默认值:8388608
  • 类型:Int
  • 单位:字节
  • 有效值:正整数
  • 是否动态:是
  • 描述:单次 AI HTTP attempt 可接受的 response body 最大大小。超过限制的响应会在 Provider 解析前被拒绝,以限制 BE 内存消耗。仅在模型确实会返回更大响应时调高。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_max_input_file_bytes

  • 默认值:10485760
  • 类型:Int
  • 单位:字节
  • 有效值:正整数
  • 是否动态:是
  • 描述:传入 ai_complete 或 ai_embed 的每个 inline FILE 的原始字节数上限,在 AI 自身复制载荷和进行 Base64 编码前检查。默认值为 10 MiB。仅在所选提供商和模型支持更大输入时调高。该参数不控制扫描或 Chunk 物化;这些内存分配与 AI 载荷仍受查询内存跟踪约束。无效或超限的 inline 输入遵循 ai_function_on_error。新打开的 AI fragment/operator 将该值捕获到不可变运行时快照中;已打开的 fragment 继续使用原快照。修改无需重启 BE。
  • 引入版本:-

ai_function_worker_thread_num

  • 默认值:16
  • 类型:Int
  • 单位:线程
  • 有效值:正整数
  • 是否动态:是
  • 描述:处理 AI HTTP completion 和响应分类的 worker 数量。completion 处理出现积压时可调大;需要限制 CPU 和内存开销时可调小。该参数不会改变 BE 启动时确定的 AI completion queue 固定容量。运行时修改会实时调整 worker pool,无需重启 BE。
  • 引入版本:-

ai_function_sub_chunk_size

  • 默认值:64
  • 类型:Int
  • 单位:行
  • 有效值:正整数
  • 是否动态:是
  • 描述:AI 执行 sub-chunk 中分组的最大行数。较小的值提供更细的调度和取消粒度,但会增加调度开销;较大的值可减少调度开销,但每个任务会保留更多行。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_max_retries

  • 默认值:3
  • 类型:Int
  • 单位:次
  • 有效值:非负整数
  • 是否动态:是
  • 描述:当最近一次失败为可重试的传输或 Provider 错误时,允许的最大共享 retry ordinal,不包含首次 HTTP attempt。普通重试与 throttle 重试消耗同一个 retry ordinal;该上限不会与 throttle 上限相加。设置为 0 可禁用普通可重试错误后的重试。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_max_retries_on_throttle

  • 默认值:5
  • 类型:Int
  • 单位:次
  • 有效值:非负整数
  • 是否动态:是
  • 描述:当最近一次失败为 Provider 限流(例如 HTTP 429)时,允许的最大共享 retry ordinal,不包含首次 HTTP attempt。普通重试与 throttle 重试消耗同一个 retry ordinal,因此该参数是当前失败类型使用的不同上限,不是独立重试预算。设置为 0 可禁用限流后的重试。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_on_error

  • 默认值:ignore
  • 类型:String
  • 单位:-
  • 有效值:ignore、fail
  • 是否动态:是
  • 描述:控制 AI 函数的行级错误处理。ignore 对失败行返回 NULL 并继续查询;fail 会终止查询。新打开的 AI fragment/operator 会将该值作为一个完整 immutable runtime snapshot 的一部分捕获;已经打开的 fragment 继续使用原 snapshot。修改无需重启 BE。
  • 引入版本:-

ai_function_rate_limit_qps_chat

  • 默认值:128
  • 类型:Int
  • 单位:请求/秒
  • 有效值:正整数
  • 是否动态:是
  • 描述:每个 BE 中按 endpoint、credential 和 capability 分桶的 chat/text AI HTTP attempt 请求准入速率。为遵守 Provider 配额或降低出站负载可调小;仅在 Provider 与 BE 均有足够容量时调大。运行时修改会实时生效并唤醒等待中的准入请求,无需重启 BE。
  • 引入版本:-

ai_function_rate_limit_qps_embedding

  • 默认值:128
  • 类型:Int(32 位)
  • 单位:请求/秒
  • 有效值:正整数
  • 是否动态:是
  • 描述:每个 BE 中按端点、凭证和 capability 分桶的文本向量 HTTP attempt 准入速率。该限制独立于 ai_function_rate_limit_qps_chat,同时仍受进程级 ai_function_max_inflight 限制。可调小以遵守提供商配额或控制出站负载;仅在提供商和 BE 均有容量时调大。运行时修改实时生效,无需重启 BE。
  • 引入版本:-

ai_function_max_inflight

  • 默认值:512
  • 类型:Int
  • 单位:请求
  • 有效值:正整数
  • 是否动态:是
  • 描述:进程级可同时持有 in-flight 准入许可的 AI HTTP attempt 上限。调小可限制 HTTP 与 response memory 压力。该参数是全局准入限制,不是每 Query 配额。运行时修改会实时生效并唤醒等待中的准入请求,无需重启 BE;BE 启动时确定的 completion queue 固定容量不会改变。
  • 引入版本:-

agg_hash_map_prefetch_dist

  • 默认值:16
  • 类型:Int
  • 单位:行
  • 是否动态:是
  • 描述:聚合哈希表/哈希集探测循环的软件预取距离(以行数为单位)。在构建聚合哈希表时,该循环会预取当前处理行前方指定行数范围内的桶,从而在处理大型表时隐藏内存延迟。将其设置为 0 将禁用软件预取。该值每处理一个 Chunk 读取一次,因此更改将在下一个 Chunk 生效。默认值 16 是针对驻留 L3 缓存的表的经验设定;对于驻留 DRAM 的工作负载应提高该值,对于驻留缓存的工作负载则应降低该值。预取还受 agg_prefetch_l2_ratio 控制:无论该距离如何,只要哈希表仍能驻留 L2 缓存中,就不会发出预取请求。
  • 引入版本:-

agg_prefetch_l2_ratio

  • 默认值:1.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:根据 L2 驻留情况控制聚合哈希表的软件预取。仅当桶数组溢出 L2 时才会启用预取,即当 bucket_count * slot_bytes >= L2_size * agg_prefetch_l2_ratio 时,其中 L2 大小在运行时检测(若检测失败则回退为 1 MiB)。在此阈值以下,哈希表驻留于 L2 中,此时预取会导致净损耗。在每个核心运行多个驱动程序且竞争激烈的部署环境中,应降低该比率——此时每个哈希表实际占用的 L2 空间小于名义上的每核心大小;将其提高至 1.0 以上会延迟预取,直到哈希表远超 L2 容量。另请参阅 agg_hash_map_prefetch_dist。
  • 引入版本:-

arrow_io_thread_pool_size

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:Apache Arrow 进程级 I/O 线程池的线程数,Arrow 的异步 I/O 任务都在这个线程池中执行。设为 0 时沿用 Arrow 启动时自行确定的大小:环境变量 ARROW_IO_THREADS 为正整数时取该值,否则为 8。设为大于 0 的值时,该值优先于 ARROW_IO_THREADS。取值范围为 [0, 32768]。修改后立即生效,无需重启:调大时立即为排队中的任务启动新线程;调小时,多出的线程在完成手头的任务后退出。改回 0 即恢复为 Arrow 启动时确定的大小。如果配置文件中的值超出取值范围,BE 会打印告警日志,并保留 Arrow 自行确定的大小。
  • 引入版本:-

clear_udf_cache_when_start

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否在 BE 启动时清除所有本地缓存的用户函数库。启用后,BE 将在 UserFunctionCache 初始化时删除 UDF 目录下的 .jar/.py 文件,并在首次使用时重新下载,会增加网络流量和首次使用延迟。禁用(默认)时,BE 直接加载已有缓存文件。
  • 引入版本:v4.0.0

dictionary_speculate_min_chunk_size

  • 默认值:10000
  • 类型:Int
  • 单位:Rows
  • 是否动态:否
  • 描述:StringColumnWriter 和 DictColumnWriter 用于触发字典编码推测的最小行数(chunk 大小)。如果传入列(或累积缓冲区加上传入行)大小大于等于 dictionary_speculate_min_chunk_size,写入器将立即运行推测并设置一种编码(DICT、PLAIN 或 BIT_SHUFFLE),而不是继续缓冲更多行。对于字符串列,推测使用 dictionary_encoding_ratio 来决定字典编码是否有利;对于数值/非字符串列,使用 dictionary_encoding_ratio_for_non_string_column。此外,如果列的 byte_size 很大(大于等于 UINT32_MAX),会强制立即进行推测以避免 BinaryColumn<uint32_t> 溢出。
  • 引入版本:v3.2.0

disable_storage_page_cache

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否开启 PageCache。
    • 开启 PageCache 后,StarRocks 会缓存最近扫描过的数据,
    • 对于查询重复性高的场景,会大幅提升查询效率。
    • true 表示不开启。
    • 自 2.4 版本起,该参数默认值由 true 变更为 false。自 3.1 版本起,该参数由静态变为动态。
  • 引入版本:-

enable_bitmap_index_memory_page_cache

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否为 Bitmap index 开启 Memory Cache。使用 Bitmap index 加速点查时,可以考虑开启。
  • 引入版本:v3.1

enable_compaction_flat_json

  • 默认值:True
  • 类型:Bool
  • 单位:
  • 是否动态:是
  • 描述:控制是否为 Flat Json 数据进行 Compaction。
  • 引入版本:v3.3.3

enable_compaction_flat_json_mixed_inputs

  • 默认值:True
  • 类型:Bool
  • 单位:
  • 是否动态:是
  • 描述:当参与 Compaction 的 segment 中,JSON 列一部分以 Flat JSON 存储、一部分以完整 JSON 存储时,是否把完整 JSON 的 segment 按其他 segment 的 Flat JSON 布局读出,且所有子列都使用 JSON 类型。这样输出可以边读边写,不必把整个 segment 缓存在内存中。JSON 类型的子列会记录其值的类型和范围,之后的 Compaction 可以据此改用能精确保存所有值的类型。仅在 enable_compaction_flat_json 为 true 且表开启了 Flat JSON 时生效。
  • 引入版本:-

enable_compaction_flat_json_partial_paths

  • 默认值:True
  • 类型:Bool
  • 单位:
  • 是否动态:是
  • 描述:Flat JSON 的 Compaction 中,某个子列只在部分输入 segment 中存在时,如果包含它的行数足够多(json_flat_sparsity_factor),是否在输出中保留这个子列。不含该子列的 segment 从其剩余 JSON 中提供对应的值;若这样的 segment 可能在剩余 JSON 中存有该值,该子列使用 JSON 类型。关闭时,Compaction 只保留所有输入 segment 都有的子列,任一输入 segment 未拍平的 key 都存入剩余 JSON。仅在 enable_compaction_flat_json 为 true 时生效。
  • 引入版本:-

enable_default_value_column_zonemap_filter

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 取值范围:true、false
  • 是否动态:是
  • 描述:是否通过常量折叠对 segment 中物理缺失的列进行数据裁剪。通过 fast schema evolution(ALTER TABLE ... ADD COLUMN)新增的列不会写入已有的 segment,因此该列的每一行都是列默认值(或 NULL)。取值为 true 时,针对该列的谓词会直接对这个常量求值,若不可能命中则整个 segment 被跳过。取值为 false 时,这些 segment 会被完整读取,且每个批次都会重新按删除条件检查,即该选项引入之前的行为。如果新增过列的表出现查询结果异常,可将其设为 false 回滚。该选项与 enable_index_page_level_zonemap_filter 相互独立,后者无法覆盖 runtime filter 路径。
  • 引入版本:-

enable_json_flat

  • 默认值:false
  • 类型:Boolean
  • 单位:
  • 是否动态:是
  • 描述:是否开启 Flat JSON 特性。开启后新导入的 JSON 数据会自动打平,提升 JSON 数据查询性能。
  • 引入版本:v3.3.0

enable_lazy_dynamic_flat_json

  • 默认值:True
  • 类型:Bool
  • 单位:
  • 是否动态:是
  • 描述:当查询在读过程中未命中 Flat JSON Schema 时,是否启用 Lazy Dynamic Flat JSON。当此项设置为 true 时,StarRocks 将把 Flat JSON 操作推迟到计算流程,而不是读取流程。
  • 引入版本:v3.3.3

enable_ordinal_index_memory_page_cache

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否为 Ordinal index 开启 Memory Cache。Ordinal index 是行号到数据 page position 的映射,可以加速 Scan。
  • 引入版本:-

enable_spill_sort_events

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:为发生落盘的排序算子启用 pipeline 事件调度器,替代轮询自旋(poll-spinning)。
  • 引入版本:-

enable_string_prefix_zonemap

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否为字符串(CHAR/VARCHAR)列启用基于前缀的 Zonemap 索引。对于非键列,最小值/最大值会截断到由 string_prefix_zonemap_prefix_len 配置的前缀长度。
  • 引入版本:-

enable_zonemap_index_memory_page_cache

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否为 Zonemap index 开启 Memory Cache。使用 Zonemap index 加速 Scan 时,可以考虑开启。
  • 引入版本:-

exchange_sink_buffer_flush_threshold_bytes

  • 默认值:67108864
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:Exchange Sink 中每个 Driver 在 Shuffle 时用于缓存待发送数据的最大内存。Shuffle 时,Exchange Sink 会为每个目标 Pipeline Driver 保留一个未填满的 Chunk,Chunk 填满后才会发送。当这些 Chunk 的总大小超过该阈值时,会立即全部发送并清空;如果清空后仍占用超过阈值一半的内存,则会依次释放这些 Chunk,直到占用降至阈值的一半以下。设置为 0 或更小的值表示不限制。
  • 引入版本:-

exchg_node_buffer_size_bytes

  • 默认值:10485760
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:Exchange 算子中,单个查询在接收端的 Buffer 容量。这是一个软限制,如果数据的发送速度过快,接收端会触发反压来限制发送速度。
  • 引入版本:-

exec_state_report_max_threads

  • 默认值:2
  • 类型:Int
  • 单位:Threads
  • 是否动态:是
  • 描述:exec-state-report 线程池的最大线程数。该线程池由 ExecStateReporter 用于将普通优先级的执行状态报告(如 Fragment 完成状态、错误状态等)从 BE 异步地通过 RPC 上报给 FE。启动时实际使用的线程数为 max(1, exec_state_report_max_threads)。运行时修改此配置会触发对所有 Executor Set(共享和独占)中线程池调用 update_max_threads。该线程池的任务队列大小固定为 1000,当所有线程繁忙且队列已满时,新的上报任务将被静默丢弃。高优先级线程池由 priority_exec_state_report_max_threads 控制。若在高并发查询场景下观察到执行状态上报延迟或丢失,可适当增大此值。
  • 引入版本:v4.1.0, v4.0.8, v3.5.15

file_descriptor_cache_capacity

  • 默认值:16384
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:文件描述符缓存的容量。
  • 引入版本:-

flamegraph_tool_dir

  • 默认值:${STARROCKS_HOME}/bin/flamegraph
  • 类型:String
  • 单位:-
  • 是否动态:否
  • 描述:火焰图工具的目录,该目录应包含 pprof、stackcollapse-go.pl 和 flamegraph.pl 脚本,用于从性能分析数据生成火焰图。
  • 引入版本:-

fragment_pool_queue_size

  • 默认值:2048
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:单 BE 节点上能够处理的查询请求上限。
  • 引入版本:-

fragment_pool_thread_num_max

  • 默认值:4096
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:最大查询线程数。
  • 引入版本:-

fragment_pool_thread_num_min

  • 默认值:64
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:最小查询线程数。
  • 引入版本:-

hdfs_client_enable_hedged_read

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否开启 Hedged Read 功能。true 表示开启,false 表示不开启。
  • 引入版本:v3.0

hdfs_client_hedged_read_threadpool_size

  • 默认值:128
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:HDFS 客户端侧 Hedged Read 线程池的大小,即 HDFS 客户端侧允许有多少个线程用于服务 Hedged Read。该参数对应 HDFS 集群配置文件 hdfs-site.xml 中的 dfs.client.hedged.read.threadpool.size 参数。
  • 引入版本:v3.0

hdfs_client_hedged_read_threshold_millis

  • 默认值:2500
  • 类型:Int
  • 单位:毫秒
  • 是否动态:否
  • 描述:发起 Hedged Read 请求前需要等待多少毫秒。例如,假设该参数设置为 30,那么如果一个 Read 任务未能在 30 毫秒内返回结果,则 HDFS 客户端会立即发起一个 Hedged Read,从目标数据块的副本上读取数据。该参数对应 HDFS 集群配置文件 hdfs-site.xml 中的 dfs.client.hedged.read.threshold.millis 参数。
  • 引入版本:v3.0

iceberg_metadata_table_cache_capacity

  • 默认值:128
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:Iceberg 元数据表(例如 t$files、t$partitions)的 JNI 扫描器在单个 BE 或 CN 节点上保留的空闲的已反序列化 Iceberg 表的最大数量。同一个查询的所有扫描任务共享一份反序列化后的表,而不是每个任务各自反序列化一份,因此 JVM 堆内存占用与并发扫描任务数无关。60 秒未被使用的表会被释放。取值小于或等于 0 时,之后开始的扫描不再共享。
  • 引入版本:-

io_coalesce_adaptive_lazy_active

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:根据谓词选择度,自适应决定是否将谓词列 IO 和非谓词列 IO 进行合并。
  • 引入版本:v3.2

jit_lru_cache_size

  • 默认值:0
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:JIT 编译的 LRU 缓存大小。如果设置为大于 0,则表示实际的缓存大小。如果设置为小于或等于 0,系统将自适应设置缓存大小,使用的公式为 jit_lru_cache_size = min(mem_limit*0.01, 1GB) (节点的 mem_limit 必须大于或等于 16 GB)。
  • 引入版本:-

json_flat_column_max

  • 默认值:100
  • 类型:Int
  • 单位:
  • 是否动态:是
  • 描述:控制 Flat JSON 时,最多提取的子列数量。该参数仅在 enable_json_flat 为 true 时生效。
  • 引入版本:v3.3.0

json_flat_create_zonemap

  • 默认值:true
  • 类型:Boolean
  • 单位:
  • 是否动态:是
  • 描述:是否为打平后的 JSON 子列创建 Zonemap。仅当 enable_json_flat 为 true 时生效。
  • 引入版本:-

json_flat_null_factor

  • 默认值:0.3
  • 类型:Double
  • 单位:
  • 是否动态:是
  • 描述:控制 Flat JSON 时,提取列的 NULL 值占比阈值,高于该比例不对该列进行提取,默认为 0.3。该参数仅在 enable_json_flat 为 true 时生效。
  • 引入版本:v3.3.0

json_flat_sparsity_factor

  • 默认值:0.3
  • 类型:Double
  • 单位:
  • 是否动态:是
  • 描述:控制 Flat JSON 时,同名列的占比阈值,当同名列占比低于该值时不进行提取,默认为 0.9。该参数仅在 enable_json_flat 为 true 时生效。
  • 引入版本:v3.3.0

json_max_parse_nesting_depth

  • 默认值:1024
  • 类型:Int
  • 单位:
  • 是否动态:是
  • 描述:解析 JSON(例如 parse_json、CAST AS JSON 以及 JSON 列导入)时允许的最大对象/数组嵌套深度。解析器每层嵌套递归一次,若不加限制,超深文档会耗尽线程栈并导致 BE 崩溃。嵌套深度超过该值的输入会返回数据质量错误。正值表示生效的上限;设置为 0 或负数时保留内置默认值(1024),而非关闭该检查。
  • 引入版本:v4.2.0

lake_tablet_ignore_invalid_delete_predicate

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:控制是否忽略 tablet rowset 元数据中可能由逻辑删除在列名重命名后引入到重复键(duplicate key)表中的无效 delete predicates 的布尔值。
  • 引入版本:v4.0

late_materialization_ratio

  • 默认值:10
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:控制 SegmentIterator 延迟物化策略的整数比率,取值范围 [0-1000]。0 禁用延迟物化;1000 强制所有读取使用延迟物化;1–999 时根据谓词过滤率动态决策,值越大越倾向使用延迟物化。当 Segment 包含复杂 Metric 类型时,改用 metric_late_materialization_ratio。启用 lake_io_opts.cache_file_only 时延迟物化自动禁用。
  • 引入版本:v3.2.0

max_hdfs_file_handle

  • 默认值:1000
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:最多可以打开的 HDFS 文件描述符数量。
  • 引入版本:-

max_memory_sink_batch_count

  • 默认值:20
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:Scan Cache 的最大缓存批次数量。
  • 引入版本:-

max_pushdown_conditions_per_column

  • 默认值:1024
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:单列上允许下推的最大谓词数量,如果超出数量限制,谓词不会下推到存储层。
  • 引入版本:-

max_scan_key_num

  • 默认值:1024
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:查询最多拆分的 Scan Key 数目。
  • 引入版本:-

metric_late_materialization_ratio

  • 默认值:1000
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:当读取包含复杂 Metric 列时,控制延迟物化行访问策略的比率,取值范围 [0-1000]。0 禁用延迟物化;1000 强制所有适用读取使用延迟物化;1–999 时根据选择率动态决策。存在复杂 Metric 类型时,此参数优先于 late_materialization_ratio。cache_file_only I/O 模式下延迟物化始终禁用。
  • 引入版本:v3.2.0

min_file_descriptor_number

  • 默认值:60000
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:BE 进程中文件描述符的最小数量。
  • 引入版本:-

object_storage_client_cache_size

  • 默认值:8
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:每个客户端工厂缓存的对象存储客户端(S3 兼容及 Azure Blob)的最大数量。该值在每次创建客户端时读取,因此调低该值不会立即生效,而是随着后续创建过程中缓存客户端被逐出而逐步生效。小于 1 的值按 1 处理。
  • 引入版本:v4.1.4, v4.0.14

object_storage_connect_timeout_ms

  • 默认值:-1
  • 类型:Int
  • 单位:毫秒
  • 是否动态:否
  • 描述:对象存储 Socket 连接的超时时间。-1 表示使用 SDK 中的默认时间。
  • 引入版本:v3.0.9

enable_poco_client_for_aws_sdk

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否为 AWS SDK 使用 Poco HTTP 客户端。true 表示使用 Poco 替换 AWS SDK 默认的 curl HTTP 客户端;false 表示使用默认的 curl 客户端。
  • 引入版本:-

object_storage_request_timeout_ms

  • 默认值:10000
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:一次对象存储请求停滞多久后客户端放弃并重试。它不是请求的总时限:对 curl 客户端是低速时间,即传输速率低于 1 字节/秒可以持续的时长;对 Poco 客户端是 socket 的收发超时。只要传输仍在推进就不会被中断,无论持续多久。0 表示关闭该检查;负值表示沿用客户端自身的默认值,在 Poco 路径上是 60 秒。
  • 引入版本:v3.0.9

parquet_late_materialization_enable

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否使用延迟物化优化 Parquet 读性能。
  • 引入版本:-

parquet_page_index_enable

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否启用 Parquet 文件的 Bloom Filter 以提高性能。true 表示启用 Bloom Filter,false 表示禁用。还可以使用系统变量 enable_parquet_reader_bloom_filter 在 Session 级别上控制这一行为。Parquet 中的 Bloom Filter 是在每个行组的列级维护的。如果 Parquet 文件包含某些列的 Bloom Filter,查询就可以使用这些列上的谓词来有效地跳过行组。
  • 引入版本:v3.5

parquet_reader_bloom_filter_enable

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:控制是否启用 Parquet 文件的布隆过滤器以提升性能的布尔值。true 表示启用布隆过滤器,false 表示禁用。也可以通过会话级别的系统变量 enable_parquet_reader_bloom_filter 控制此行为。Parquet 中的布隆过滤器是按“每个 row group 的列级别”维护的。如果 Parquet 文件为某些列维护了布隆过滤器,则对这些列的谓词可以高效地跳过不相关的 row group。
  • 引入版本:v3.5

parquet_runtime_filter_push_down_enable

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:控制是否在 Parquet Reader 内部对已解码的数据行求值 Join Runtime Filter 的布尔值,从而在物化 Lazy 列之前提前过滤掉不匹配的行。true 表示启用该行级下推,false 表示禁用,此时 Runtime Filter 仅用于 row group 及 page 统计信息裁剪,行级过滤改由下游的 Scan 算子完成。
  • 引入版本:-

path_gc_check_step

  • 默认值:1000
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述::单次连续 Scan 最大的文件数量。
  • 引入版本:-

path_gc_check_step_interval_ms

  • 默认值:10
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:多次连续 Scan 文件间隔时间。
  • 引入版本:-

path_scan_interval_second

  • 默认值:86400
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:GC 线程清理过期数据的间隔时间。
  • 引入版本:-

pipeline_connector_scan_thread_num_per_cpu

  • 默认值:8
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:BE 节点中每个 CPU 核心分配给 Pipeline Connector 的扫描线程数量。自 v3.1.7 起变为动态参数。
  • 引入版本:-

pipeline_enable_large_column_checker

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否在 Pipeline 执行框架中启用大列检测。启用后,如果中间列在 Pipeline 执行或 Spill 序列化过程中达到 Chunk 容量限制,查询将报容量超限错误。
  • 引入版本:v4.0.0

pipeline_poller_timeout_guard_ms

  • 默认值:-1
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:当该值大于 0 时,则在轮询器中,如果某个 Driver 的单次调度时间超过了 pipeline_poller_timeout_guard_ms 的时间,则会打印该 Driver 以及 Operator 信息。
  • 引入版本:-

pipeline_prepare_thread_pool_queue_size

  • 默认值:102400
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Pipeline 执行引擎在线程池中执行 PREPARE Fragment 的队列长度。
  • 引入版本:-

pipeline_prepare_thread_pool_thread_num

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Pipeline 执行引擎准备片段线程池中的线程数。0 表示等于系统 VCPU 数量。
  • 引入版本:-

priority_queue_remaining_tasks_increased_frequency

  • 默认值:512
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:BlockingPriorityQueue 为避免任务饥饿提升剩余任务优先级的频率阈值(按获取次数计数)。累计弹出次数超过该值就会整体提升队列元素优先级并重建堆;值越小提升越频繁,减少饥饿但增加 CPU 开销。
  • 引入版本:v3.2.0

pipeline_prepare_timeout_guard_ms

  • 默认值:-1
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:当该值大于 0 时,如果 PREPARE 过程中 Plan Fragment 超过 pipeline_prepare_timeout_guard_ms 的时间,则会打印 Plan Fragment 的堆栈跟踪。
  • 引入版本:-

pipeline_scan_thread_pool_queue_size

  • 默认值:102400
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Pipeline 执行引擎扫描线程池任务队列的最大队列长度。
  • 引入版本:-

case_when_selective_eval_ratio

  • 默认值:2
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:控制 searched CASE WHEN 的每个 THEN 分支是否只在该分支实际拥有的行上求值,而不是在整个 chunk 上求值一遍再逐行挑选。仅在 CASE 返回复合类型(ARRAY/MAP/STRUCT)或 VARIANT 时生效,因为只有这些类型单行物化的代价才足以抵消把分支输入行压实成子 chunk 的拷贝开销。只有当 owned_rows * case_when_selective_eval_ratio < chunk_rows,即该分支拥有的行数少于 chunk 的 1 / case_when_selective_eval_ratio 时才会压实;超过阈值的分支仍在整个 chunk 上求值,因为此时压实输入的拷贝开销会超过省下的求值开销。设置为 1 表示只要分支不独占整个 chunk 就压实。设置为 0 或负数表示完全关闭该优化、回到原有行为,包括它带来的行为变更:当没有任何行选中某个 THEN 或 ELSE 时,即使它会报错也不再被求值。
  • 引入版本:-

enable_lock_free_scan_task_queue

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:控制 ScanExecutor 是否使用 LockFreeWorkGroupScanTaskQueue 来调度 OLAP scan 和 connector scan 任务。开启后,扫描任务会通过“每个 workgroup 的无锁队列 + workgroup 级协调器”进行调度,相比原先基于互斥锁的 WorkGroupScanTaskQueue 可以降低竞争开销。排障或回滚时,可将该参数设置为 false 以切回旧的 scan task queue 实现。
  • 引入版本:v4.1.0

pk_index_parallel_get_threadpool_size

  • 默认值:1048576
  • 类型:Int
  • 单位:Tasks
  • 是否动态:是
  • 描述:设置用于 shared-data(cloud-native / lake)模式下 PK 索引并行获取操作的 "cloud_native_pk_index_get" 线程池的最大队列大小(待处理任务数量)。该池的实际线程数由 pk_index_parallel_get_threadpool_max_threads 控制;此设置仅限制可排队等待执行的任务数量。非常大的默认值(2^20)实际上使队列近似无界;降低此值可以防止排队任务导致的内存过度增长,但在队列已满时可能导致任务提交阻塞或失败。应根据工作负载并发性和内存约束与 pk_index_parallel_get_threadpool_max_threads 一起调优。
  • 引入版本:-

priority_exec_state_report_max_threads

  • 默认值:2
  • 类型:Int
  • 单位:Threads
  • 是否动态:是
  • 描述:高优先级 exec-state-report 线程池的最大线程数。该线程池由 ExecStateReporter 用于将高优先级执行状态报告(如紧急 Fragment 失败)从 BE 异步地通过 RPC 上报给 FE。与普通线程池不同,该线程池的任务队列无上限。启动时实际使用的线程数为 max(1, priority_exec_state_report_max_threads)。运行时修改此配置会触发对所有 Executor Set(共享和独占)中优先级线程池调用 update_max_threads。普通线程池由 exec_state_report_max_threads 控制。
  • 引入版本:v4.1.0, v4.0.8, v3.5.15

query_cache_capacity

  • 默认值:536870912
  • 类型:Int
  • 单位:Bytes
  • 是否动态:否
  • 描述:指定 Query Cache 的大小。默认为 512 MB。最小不低于 4 MB。如果当前的 BE 内存容量无法满足您期望的 Query Cache 大小,可以增加 BE 的内存容量,然后再设置合理的 Query Cache 大小。每个 BE 都有自己私有的 Query Cache 存储空间,BE 只 Populate 或 Probe 自己本地的 Query Cache 存储空间。
  • 引入版本:-

query_pool_spill_mem_limit_threshold

  • 默认值:1.0
  • 类型:Double
  • 单位:-
  • 是否动态:否
  • 描述:如果开启自动落盘功能, 当所有查询使用的内存超过 query_pool memory limit * query_pool_spill_mem_limit_threshold 时,系统触发中间结果落盘。
  • 引入版本:3.2.7

query_scratch_dirs

  • 默认值:${STARROCKS_HOME}
  • 类型:string
  • 单位:-
  • 是否动态:否
  • 描述:用于查询执行在发生中间数据溢写(例如外部排序、哈希连接和其他算子)时的可写 scratch 目录的逗号分隔列表。指定一个或多个以 ; 分隔的路径(例如 /mnt/ssd1/tmp;/mnt/ssd2/tmp)。这些目录应当对 BE 进程可访问且可写,并具有足够的可用空间;StarRocks 会在它们之间选择以分散溢写 I/O。更改此项需要重启才能生效。如果目录丢失、不可写或已满,溢写可能失败或导致查询性能下降。
  • 引入版本:v3.2.0

result_buffer_cancelled_interval_time

  • 默认值:300
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:BufferControlBlock 释放数据的等待时间。
  • 引入版本:-

runtime_filter_worker_thread_num

  • 默认值:4
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:每个 BE 上用于合并和投递 Global Runtime Filter 的线程数。同一个 Runtime Filter 的所有事件由同一个线程处理,不同的 Runtime Filter 分散到各个线程。取值小于或等于 1 时只使用一个线程。
  • 引入版本:-

scan_context_gc_interval_min

  • 默认值:5
  • 类型:Int
  • 单位:Minutes
  • 是否动态:是
  • 描述:Scan Context 的清理间隔。
  • 引入版本:-

scan_credential_refresh_rpc_timeout_ms

  • 默认值:10000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:是
  • 描述:当为扫描下发的凭证(Iceberg REST Catalog 的 vended credentials)即将过期时,扫描向其 Coordinator FE 请求续期凭证的 RPC 超时时间。该 RPC 不重试:失败或超时后,扫描继续使用当前凭证,并在一分钟后再次请求。取值小于或等于 0 时,之后开始的扫描不再续期,始终使用下发时的凭证。
  • 引入版本:-

scanner_row_num

  • 默认值:16384
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:每个扫描线程单次执行最多返回的数据行数。
  • 引入版本:-

scanner_thread_pool_queue_size

  • 默认值:102400
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:存储引擎支持的扫描任务数。
  • 引入版本:-

scanner_thread_pool_thread_num

  • 默认值:48
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存储引擎并发扫描磁盘的线程数,统一管理在线程池中。
  • 引入版本:-

max_hdfs_scanner_num

  • 默认值:50
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:限制 ConnectorScanNode 可同时运行的远端扫描器(HDFS/对象存储等)数量上限。启动时会用此值裁剪估算并发,运行时调度 pending scanner 也会受其限制,用于控制线程、内存和文件句柄压力。
  • 引入版本:v3.2.0

spill_max_dir_bytes_ratio

  • 默认值:0.5
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:落盘目录(spill_local_storage_dir)与存储路径(storage_root_path)位于同一块磁盘时,中间结果落盘最多可占用的磁盘容量比例。默认值 0.5 表示落盘最多使用该磁盘容量的 50%。落盘目录位于独立磁盘时不受此限制。该参数仅在 BE 启动时读取,修改后需重启 BE 才能生效。
  • 引入版本:v3.2.0

string_prefix_zonemap_prefix_len

  • 默认值:16
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:启用 enable_string_prefix_zonemap 时用于字符串 Zonemap 最小值/最大值的前缀长度。
  • 引入版本:-

jvm_call_thread_pool_size

  • 默认值:4
  • 类型:Int
  • 单位:Threads
  • 是否动态:否
  • 描述:设置 JVM 调用 PriorityThreadPool 的大小,用于必须在 pthread 上执行的内部 JNI 工作,例如 HDFS/libhdfs close 和 stat 操作以及 JNI 全局引用清理。该线程池独立于 udf_thread_pool_size,避免通用 JVM 工作与 Java UDF 执行竞争。
  • 引入版本:-

udf_thread_pool_size

  • 默认值:1
  • 类型:Int
  • 单位:Threads
  • 是否动态:否
  • 描述:设置 JavaEnv 持有的 Java UDF 调用 PriorityThreadPool 的大小(用于执行 Java UDF 相关任务)。该值既作为线程池的线程数,也在构造线程池时作为队列容量(PriorityThreadPool("udf", thread_num, queue_size))。增大该值可以允许更多并发的 Java UDF 执行;保持较小可避免过度的 CPU 和内存争用。
  • 引入版本:v3.2.0

update_memory_limit_percent

  • 默认值:60
  • 类型:Int
  • 单位:Percent
  • 是否动态:是
  • 描述:BE 进程内存中为更新相关内存和缓存保留的比例。在启动期间,RuntimeEnv 将更新的 MemTracker 计算为 process_mem_limit * clamp(update_memory_limit_percent, 0, 100) / 100。UpdateManager 也使用该百分比来确定其 primary-index/index-cache 的容量(index cache capacity = RuntimeEnv::process_mem_limit * update_memory_limit_percent / 100)。运行时修改该值后,会重新计算更新 MemTracker 的上限、primary index cache 的容量,以及由其派生的 update state、compaction state 和 primary index block cache 的上限。调小该值时,未被使用的 primary index cache 条目会被立即淘汰,但正在使用的内存要等正在执行的导入和 compaction 结束后才会释放。增加此值会为更新/primary-index 路径分配更多内存(减少其他内存池可用内存);减少它会降低更新内存和缓存容量。值会被限定在 0–100 范围内。
  • 引入版本:v3.2.0

enable_vector_index_block_cache

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否按倒排列表 Block 缓存 IVFPQ 索引。开启后,StarRocks 仅加载并缓存查询需要的 IVFPQ Block;关闭后缓存整个 IVFPQ 索引文件。该配置不改变 HNSW 的缓存方式。
  • 引入版本:-

config_vector_index_build_concurrency

  • 默认值:8
  • 类型:Int
  • 单位:线程
  • 是否动态:是
  • 描述:每个向量索引构建任务使用的 OpenMP 线程数。StarRocks 会将实际值限制为至少 1。该配置还会与 vector_index_build_max_cpu_ratio 一起决定异步向量索引构建线程池的大小。
  • 引入版本:-

config_vector_index_default_build_threshold

  • 默认值:10000
  • 类型:Int
  • 单位:行
  • 是否动态:是
  • 描述:构建向量索引所需的默认 Segment 最小行数。索引属性 index_build_threshold 可以覆盖该值。对于 IVFPQ,有效阈值至少为 nlist,以确保索引训练有足够的数据。
  • 引入版本:-

vector_index_build_max_cpu_ratio

  • 默认值:0.5
  • 类型:Double
  • 单位:比例
  • 是否动态:是
  • 描述:异步向量索引构建可使用的 BE/CN CPU 核数目标比例。构建 CPU 预算为 max(2, floor(cpu_cores * value)),构建线程池大小由该预算和 config_vector_index_build_concurrency 共同决定。由于最小预算为 2,小规格机器或较小的比例可能使实际值超过配置比例。
  • 引入版本:-

enable_vector_adaptive_search

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:HNSW 向量索引自适应 ef_search 缩放的总开关。开启时,BE 会根据 segment 行数为每个 segment 调整有效 ef_search,从而在 compaction 合并大 segment 后无需手动调参即可保持召回率。设置为 false 时关闭自适应缩放,按用户指定的 ef_search 原值执行。
  • 引入版本:-

vector_query_cache_capacity

  • 默认值:20%
  • 类型:String
  • 单位:字节,支持单位后缀(K/M/G/T)或 BE mem_limit 的百分比(%)
  • 是否动态:是
  • 描述:SR 端向量索引缓存的总容量,在同一个 LRU 中同时管理 HNSW 整索引条目和 IVF-PQ 每个 list 的 block 条目(当 enable_vector_index_block_cache=true 时)。BE 启动时和每次通过 HTTP /api/update_config 更新时均生效。接受绝对字节(如 4294967296)、带单位数值(4G、512M)或相对于 BE 进程内存限额的百分比(如 20%)。v4.2.0 行为变更: 旧版本只接受绝对字节数(默认 512MB);升级时如不显式覆盖该配置,cache 大小将变为 BE 内存的 20%。
  • 引入版本:v3.4.0

enable_vector_index_cache_on_build

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:构建向量索引时,是否把刚构建出的索引一并写入由 vector_query_cache_capacity 控制的向量索引缓存。默认关闭:该缓存是按查询工作集容量规划的,如果允许导入和 Compaction 把新构建的索引不断写入缓存,会淘汰正在被查询使用的条目,换来的却是一批可能永远不会被查询的索引。查询路径仍会在首次读取索引时按需填充缓存。仅当索引构建与查询在同一节点上执行、且新写入的数据会被立即查询时,才建议开启该项,以省去首次从索引文件回读的开销。修改后对之后启动的索引构建生效。
  • 引入版本:v4.2.0

vector_index_cache_expire_sec

  • 默认值:900
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:未使用的向量索引缓存条目在过期前可保持空闲的时间。最后一个缓存 handle 释放时开始计时;缓存命中后,在对应 handle 再次释放时刷新计时。正在被查询 pin 住的条目不会被删除。IVF-PQ 的 list block 随其所属的索引条目一起释放,不维护独立 TTL。小于或等于 0 时关闭过期淘汰。运行时修改仅作用于之后释放的 handle,不会重写现有条目的过期时间。
  • 引入版本:v4.2.0

enable_vector_index_cache_async_load_on_miss

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:顶层向量索引缓存未命中时,是否让当前查询回退到暴力检索,同时在后台将索引加载到缓存中。同一索引的并发 miss 共享一个后台加载任务,并在索引就绪前继续使用暴力检索。设置为 false 时,缓存未命中会同步加载索引。仅当预期冷加载延迟高于暴力检索成本,并且缓存容量足以容纳查询工作集时,才建议开启。运行时修改对之后初始化的向量索引 reader 生效。
  • 引入版本:v4.2.0

vector_index_cache_async_load_threads

  • 默认值:8
  • 类型:Int
  • 单位:线程
  • 是否动态:否
  • 描述:向量索引缓存后台加载线程池的最大 worker 数。worker 按需创建,并在空闲 60 秒后退出。小于或等于 0 的值会被调整为 1。该配置在 StorageEnv 初始化时读取,修改后需要重启 BE/CN 才能生效。
  • 引入版本:v4.2.0

vector_index_cache_loading_wait_timeout_ms

  • 默认值:5000
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:每个同步缓存调用方等待正在进行的向量索引加载完成的最长时间。等待超时后,该调用方会收到缓存未命中,使查询路径可以回退到暴力检索。已经开始的加载不会被取消,而是继续在后台执行。后续每个调用方都会按配置值重新开始自己的等待。小于或等于 0 时不等待。运行时修改对之后开始的等待生效。
  • 引入版本:v4.2.0

vector_adaptive_ef_alpha

  • 默认值:1.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:自适应 ef_search 的增长斜率。缩放系数为 1 + alpha * log2(segment_rows / vector_adaptive_ef_baseline_rows)。值越大召回提升越多但 CPU 开销越高;值越小则相反。仅在 enable_vector_adaptive_search=true 且 segment_rows > vector_adaptive_ef_baseline_rows 时生效。
  • 引入版本:-

vector_adaptive_ef_baseline_rows

  • 默认值:300000
  • 类型:Int
  • 单位:Rows
  • 是否动态:是
  • 描述:自适应 ef_search 不进行缩放的 segment 行数基线。低于该阈值的 segment 使用用户指定的 ef_search;高于该阈值的 segment 会得到放大的有效 ef_search,用以补偿较大 HNSW 图的搜索深度。仅在 enable_vector_adaptive_search=true 时生效。
  • 引入版本:-

vector_adaptive_ef_cap

  • 默认值:8.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:自适应 ef_search 倍率上限。即使 segment 极大也将放大倍率限制在该上限内,避免 CPU 与延迟在极端情况下失控。仅在 enable_vector_adaptive_search=true 时生效。
  • 引入版本:-

vector_index_brute_selectivity_threshold

  • 默认值:0.01
  • 类型:Double
  • 单位:比例
  • 是否动态:是
  • 描述:带残余标量过滤条件的向量查询从过滤式 HNSW 遍历切换为精确计算的选择率阈值。如果匹配行数不超过 Segment 总行数的该比例,StarRocks 会直接对过滤后的候选项计算距离。设置为 0 可禁用该比例判断;候选数量不大于查询 k 时的独立短路仍然生效。
  • 引入版本:-

enable_vector_index_topk_underfill_fallback

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否通过精确暴力计算避免 top-k 向量检索返回结果不足。设置为 true 时,如果谓词或运行时过滤器在 Segment 级 ANN 检索之后执行,StarRocks 会直接改走精确计算;如果带预过滤条件的 ANN 检索返回行数小于 min(k, 匹配候选数),StarRocks 会对匹配候选项进行精确重算。设置为 false 时,即使部分谓词或运行时过滤器只能在 ANN 候选生成后执行,StarRocks 仍保留 ANN 物理执行路径,并且不会触发基于结果数量的精确重算,因此最终结果可能少于 k 行。基于结果数量的回退仅作用于 top-k 检索,不作用于范围检索,因为范围检索返回较少结果可能表示没有更多候选项满足指定半径。
  • 引入版本:-

vector_index_build_flush_threshold_rows

  • 默认值:262144
  • 类型:Int
  • 单位:行
  • 是否动态:是
  • 描述:每个向量索引构建器的暂存 Buffer 在将数据加入内存索引前最多保留的行数。该配置可以限制构建 HNSW Flat 索引时的暂存 Buffer 内存,但不限制训练后索引本身的大小。设置为 0 可禁用中间 Flush,并缓存整个 Segment。
  • 引入版本:-

vector_chunk_size

  • 默认值:4096
  • 类型:Int
  • 单位:Rows
  • 是否动态:否
  • 描述:向量化执行中每个 Chunk(批次)的行数,贯穿执行引擎和存储层。影响算子吞吐量、内存占用、Spill/Sort 缓冲区大小及 I/O 启发式策略。增大可提升宽表/CPU 密集型场景的效率,但会提高峰值内存并增加小结果集查询的延迟。除非分析显示批大小是瓶颈,否则建议保持默认值。
  • 引入版本:v3.2.0

导入导出

clear_transaction_task_worker_count

  • 默认值:1
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:清理事务的线程数。
  • 引入版本:-

column_mode_partial_update_insert_batch_size

  • 默认值:4096
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:列模式部分更新中处理插入行时的批次大小。如果设置为 0 或负数,将会被限制为 1 以避免无限循环。该参数控制每次批量处理新插入行的数量,较大的值可以提高写入性能但会占用更多内存。
  • 引入版本:v3.5.10, v4.0.2

partial_update_memory_limit_per_worker

  • 默认值:2147483648
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:部分更新(partial update)每个工作线程的内存上限,用于限制单个 worker 在处理 partial update 时的内存占用。

enable_load_spill_parallel_merge

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否启用单个 Tablet 内部的并行 Spill Merge。启用后可以提高导入过程中 Spill Merge 的性能。
  • 引入版本:-

enable_parallel_memtable_finalize

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否在存算分离(Lake)表导入数据时启用并行 MemTable Finalize。启用后,MemTable 的 Finalize 操作(排序/聚合)将从写入线程移至 Flush 线程执行,使写入线程可以继续向新的 MemTable 插入数据,同时前一个 MemTable 正在并行进行 Finalize 和 Flush。这可以通过重叠 CPU 密集型的 Finalize 操作与 I/O 密集型的 Flush 操作来显著提高导入吞吐量。注意:当需要填充自增列时,此优化会自动禁用,因为自增 ID 的分配必须在 MemTable 提交 Flush 之前完成。
  • 引入版本:-

allow_list_object_for_random_bucketing_on_cache_miss

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:控制 random bucketing 大小检查在 Lake metadata 缓存未命中时是否允许回退到对象存储 LIST。true 表示回退到 LIST 元数据文件计算 base size(历史行为、估算更准确);false 表示跳过 LIST,直接使用 base_size = 0,可减少 LIST object 请求,但因大小估算精度下降,可能使 immutable 标记稍晚触发。
  • 引入版本:4.1.0, 4.0.7, 3.5.15

enable_stream_load_verbose_log

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否在日志中记录 Stream Load 的 HTTP 请求和响应信息。true 表示启用,false 表示不启用。
  • 引入版本:v2.5.17, v3.0.9, v3.1.6, v3.2.1

flush_thread_num_per_store

  • 默认值:2
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:每个 Store 用以 Flush MemTable 的线程数。
  • 引入版本:-

lake_flush_thread_num_per_store

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:在存算分离集群中,每个 Store 用以 Flush MemTable 的线程数。当该参数被设置为 0 时,系统使用 CPU 核数的两倍。 当该参数被设置为小于 0 时,系统使用该参数的绝对值与 CPU 核数的乘积。
  • 引入版本:3.1.12, 3.2.7

load_data_reserve_hours

  • 默认值:4
  • 类型:Int
  • 单位:Hours
  • 是否动态:否
  • 描述:小批量导入生成的文件保留的时长。
  • 引入版本:-

load_error_log_reserve_hours

  • 默认值:48
  • 类型:Int
  • 单位:Hours
  • 是否动态:是
  • 描述:导入数据信息保留的时长。
  • 引入版本:-

load_sink_close_thread_pool_num_max

  • 默认值:64
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:执行导入 Sink 最终关闭(Close)操作的线程数上限。存算分离集群下,该操作会向对象存储写入合并事务日志;放在这个线程池中执行,可以避免慢写入阻塞 Pipeline 的 Poller 线程和执行线程。线程全部繁忙时,后续的关闭操作在线程池队列中排队。队列长度不受限制,不会丢弃任何关闭操作。取值必须大于 0。支持运行时修改,无需重启 BE 或 CN。降低上限不会中断正在执行的关闭操作。初始化时会预启动一个线程并在空闲时保留;其余线程空闲 500 ms 后可退出。
  • 引入版本:-

enable_put_combinded_txn_log_parallel

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否并行写入导入的合并事务日志。导入 Sink 关闭时,会为本次导入涉及的每个分区向对象存储写入一份合并事务日志。设置为 true 时,这些写入在专用线程池中并发执行(线程数上限由 put_combined_txn_log_thread_pool_num_max 控制,默认为 64);设置为 false 时,逐个分区依次写入。两种方式下,导入都会等待所有写入完成,任一写入失败则导入失败。
  • 引入版本:-

put_combined_txn_log_thread_pool_num_max

  • 默认值:64
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,向对象存储写入合并事务日志的线程池的线程数上限。enable_put_combinded_txn_log_parallel 设置为 true 时,一次导入涉及的各分区的合并事务日志在该线程池中并发写入。线程全部繁忙时,后续写入在线程池队列中排队,队列长度不受限制。支持运行时修改,无需重启 BE 或 CN。取值小于或等于 0 时按 1 处理。降低上限不会中断正在执行的写入。线程空闲 500 ms 后退出。
  • 引入版本:-

enable_rejected_record_sync

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:拒绝记录同步守护线程的特性开关。启用后,BE 常驻的 RejectedRecordSyncDaemon 会扫描 RejectedRecordWriter 产生的分片级 JSON Lines 文件,并通过 merge-commit Stream Load 批量回写到 _statistics_.rejected_records 系统表。在分阶段上线期间默认关闭:升级到含该守护线程的版本后,只有在运维显式开启后集群才会开始向新系统表写入数据。
  • 引入版本:-

rejected_record_sync_interval_sec

  • 默认值:30
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:RejectedRecordSyncDaemon 的扫描周期。未找到新文件的 tick 为 no-op。减小该值可降低拒绝行在 _statistics_.rejected_records 中可查询的延迟,增大该值可减轻文件系统压力。
  • 引入版本:-

rejected_record_sync_max_batch_rows

  • 默认值:10000
  • 类型:Int
  • 单位:行
  • 是否动态:是
  • 描述:单次 merge-commit Stream Load 批次的行数上限。在守护线程拼装文件内容的过程中按行强制执行,因此一个超大单文件也会被拆分;超出上限的回写量会在连续 tick 间拆分。该上限用于限制 Stream Load 事务规模,避免一次过大的 flush 反压影响无关的 load。
  • 引入版本:-

rejected_record_sync_max_batch_bytes

  • 默认值:33554432(32 MiB)
  • 类型:Int64
  • 单位:字节
  • 是否动态:是
  • 描述:守护线程每次 POST 拼装的 Stream Load payload 字节上限。与 rejected_record_sync_max_batch_rows 同时生效,确保即使列很宽或 error_message 很长的 load 也不会在内存里组装出 GB 级 payload。当上限在文件中途被触发时,守护线程会提交当前批次并开启新的 payload;该文件保留到其全部行都已发送为止。建议不超过 FE 的 streaming_load_max_mb,以避免 FE 侧拒收。
  • 引入版本:-

rejected_record_sync_max_backoff_sec

  • 默认值:600
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:当 post_to_stream_load 持续失败时 tick 间隔的上限。守护线程每次失败后将休眠时间翻倍(rejected_record_sync_interval_sec << 连续失败次数),直到达到该上限;一次成功后立即回到基础间隔。避免长时间 FE 宕机时每 rejected_record_sync_interval_sec 秒都产生一条 WARN 日志 + 一次 _sync_failures 计数。Uninitialized 状态("master FE 尚未就绪")不计入失败连续数。
  • 引入版本:-

rejected_record_local_retention_hours

  • 默认值:24
  • 类型:Int
  • 单位:小时
  • 是否动态:是
  • 描述:本地 JSON Lines 文件被守护线程回收前的最长保留时间。作为兜底上限:同步失败通常每个 tick 都会重试,但在 FE 不可达、系统表被删除、鉴权异常等配置异常场景下,该配置可防止文件无限堆积占满存储路径。
  • 引入版本:-

rejected_record_sync_post_timeout_sec

  • 默认值:60
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:守护线程向 FE 发起 Stream Load PUT 请求时的单次超时时间。merge-commit 批次可能因为多个 BE 并发请求被合并到同一事务而在 FE 提交队列短暂等待,因此该值故意设置得比默认查询超时更宽松。
  • 引入版本:-

load_process_max_memory_limit_bytes

  • 默认值:107374182400
  • 类型:Int
  • 单位:Bytes
  • 是否动态:否
  • 描述:单节点上所有的导入线程占据的内存上限。
  • 引入版本:-

load_spill_memory_usage_per_merge

  • 默认值:1073741824
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:Spill Merge 期间每次 Merge 操作的最大内存使用量。默认为 1GB (1073741824 字节)。该参数用于控制导入过程中 Spill Merge 时单个 Merge 任务的内存占用,避免内存使用过高。
  • 引入版本:-

max_consumer_num_per_group

  • 默认值:3
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:Routine load 中,每个 Consumer Group 内最大的 Consumer 数量。
  • 引入版本:-

max_pulsar_consumer_num_per_group

  • 默认值:1
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Pulsar Routine Load 每个 Consumer Group 允许的最大 Consumer 数量上限。
  • 引入版本:-

max_runnings_transactions_per_txn_map

  • 默认值:100
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:每个分区内部同时运行的最大事务数量。
  • 引入版本:-

number_tablet_writer_threads

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:导入用的 tablet writer 线程数, 用于 Stream Load、Broker Load、Insert 等。当参数设置为小于等于 0 时,系统使用 CPU 核数的二分之一,最小为 16。当参数设置为大于 0 时,系统使用该值。自 v3.1.7 起变为动态参数。
  • 引入版本:-

push_worker_count_high_priority

  • 默认值:3
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:导入线程数,用于处理 HIGH 优先级任务。
  • 引入版本:-

push_worker_count_normal_priority

  • 默认值:3
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:导入线程数,用于处理 NORMAL 优先级任务。
  • 引入版本:-

streaming_load_max_batch_size_mb

  • 默认值:100
  • 类型:Int
  • 单位:MB
  • 是否动态:是
  • 描述:流式导入单个 JSON 文件大小的上限。
  • 引入版本:-

streaming_load_max_mb

  • 默认值:102400
  • 类型:Int
  • 单位:MB
  • 是否动态:是
  • 描述:流式导入单个文件大小的上限。自 3.0 版本起,默认值由 10240 变为 102400。
  • 引入版本:-

streaming_load_rpc_max_alive_time_sec

  • 默认值:1200
  • 类型:Int
  • 单位:秒
  • 是否动态:否
  • 描述:Stream Load 的 RPC 超时时长。
  • 引入版本:-

transaction_publish_version_thread_pool_num_min

  • 默认值:0
  • 类型:Int
  • 单位:Threads
  • 是否动态:是
  • 描述:Publish Version 线程池的最小线程数,空闲时可收缩到该值。0 表示不设固定下限。
  • 引入版本:-

transaction_publish_version_thread_pool_idle_time_ms

  • 默认值:60000
  • 类型:Int
  • 单位:毫秒
  • 是否动态:否
  • 描述:线程被 Publish Version 线程池回收前的 Idle 时间。
  • 引入版本:-

transaction_publish_version_worker_count

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:生效版本的最大线程数。当该参数被设置为小于或等于 0 时,系统默认使用当前节点的 CPU 核数,以避免因使用固定值而导致在导入并行较高时线程资源不足。自 2.5 版本起,默认值由 8 变更为 0。
  • 引入版本:-

use_mmap_allocate_chunk

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否使用匿名 mmap 方式分配 chunk(MAP_ANONYMOUS | MAP_PRIVATE)。开启会产生大量 VM 映射,需提高 vm.max_map_count 并设置较大的 chunk_reserved_bytes_limit,否则可能因频繁映射/解除映射造成性能问题。
  • 引入版本:v3.2.0

write_buffer_size

  • 默认值:104857600
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:MemTable 在内存中的 Buffer 大小,超过这个限制会触发 Flush。
  • 引入版本:-

broker_write_timeout_seconds

  • 默认值:30
  • 类型:Int
  • 单位:Seconds
  • 是否动态:否
  • 描述:后端与 Broker 交互的写/IO RPC 超时时长(秒),内部会换算为毫秒并作为默认超时传给 BrokerFileSystem、BrokerServiceConnection 等。网络或 Broker 较慢、大文件传输时可适当调大。
  • 引入版本:v3.2.0

enable_load_diagnose

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:导入 RPC 超时时是否自动触发诊断(收集 profile/堆栈),诊断 RPC 行为由 load_diagnose_rpc_timeout_profile_threshold_ms、load_diagnose_rpc_timeout_stack_trace_threshold_ms 和 load_diagnose_send_rpc_timeout_ms 控制。可能带来额外 RPC 与开销,敏感场景可关闭。
  • 引入版本:v3.5.0

enable_load_segment_parallel

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否开启导入写入的分段并行处理。开启可提升吞吐,但会增加资源占用。
  • 引入版本:-

enable_load_channel_rpc_async

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:启用后,load-channel Open 类型的 RPC(例如 PTabletWriterOpen)的处理会从 BRPC worker 转移到一个专用的线程池:请求处理器会创建一个 ChannelOpenTask 并将其提交到内部 _async_rpc_pool,而不是内联执行 LoadChannelMgr::_open。这样可以减少 BRPC 线程内的工作量和阻塞,并允许通过 load_channel_rpc_thread_pool_num 和 load_channel_rpc_thread_pool_queue_size 调整并发。如果线程池提交失败(池已满或已关闭),该请求会被取消并返回错误状态。该线程池会在 LoadChannelMgr::close() 时关闭,因此在启用该功能时需要考虑容量和生命周期,以避免请求被拒绝或处理延迟。
  • 引入版本:v3.5.0

enable_load_chunk_all_null_encoding

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:该 BE 是否在导入的 tablet sink RPC(把数据按分桶路由到目标 tablet 所在 BE 的那一跳)上参与全 NULL 列的紧凑编码。开启后,接收端 BE 会在 tablet writer 的 open 响应中声明支持该编码;发送端 BE 看到声明后,对于整列都是 NULL 的列,只发送一个行数,而不再逐行发送 NULL 标记和偏移量。列数多、且大部分列没有数据的宽表收益最明显,这一跳的传输字节数和两端的序列化开销都会下降。只有收发两端都认可该编码时才会启用,因此混合版本集群和版本回退都会自动回落到原有格式。把发送端或接收端任意一侧的该配置设为 false,即可关闭经过该节点的导入的这项编码。该配置不支持动态修改:接收端要用它同时决定对外声明的能力和是否按发送端声明的方式解析数据,运行期改动会让这两个判断不一致。
  • 引入版本:v4.2.0

load_channel_rpc_thread_pool_num

  • 默认值:-1
  • 类型:Int
  • 单位:Threads
  • 是否动态:是
  • 描述:异步处理 load channel Open RPC 的线程池大小。过小可能导致提交失败,过大增加线程开销。
  • 引入版本:v3.5.0

load_channel_rpc_thread_pool_queue_size

  • 默认值:1024000
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:异步 load channel Open RPC 线程池的队列长度,队列满则请求会被拒绝。
  • 引入版本:v3.5.0

enable_streaming_load_thread_pool

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:控制是否将 streaming load 的 scanner 提交到专用的 streaming load 线程池。当启用且查询为带有 TLoadJobType::STREAM_LOAD 的 LOAD 时,ConnectorScanNode 会将 scanner 任务提交到 streaming_load_thread_pool(该池配置为 INT32_MAX 的线程数和队列大小,即实际上是无界的)。当禁用时,scanner 使用通用的 thread_pool 及其 PriorityThreadPool 提交逻辑(优先级计算、try_offer/offer 行为)。启用可以将 streaming-load 的工作与常规查询执行隔离以减少干扰;但由于专用池实际上是无界的,在重度 streaming-load 流量下启用可能会增加并发线程数和资源使用。此选项默认开启,通常无需修改。
  • 引入版本:v3.2.0

streaming_load_thread_pool_idle_time_ms

  • 默认值:2000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:否
  • 描述:streaming load 线程池中空闲线程的存活时间,超过则回收。
  • 引入版本:-

streaming_load_thread_pool_num_min

  • 默认值:0
  • 类型:Int
  • 单位:Threads
  • 是否动态:否
  • 描述:streaming load 线程池的最小线程数。空闲时可收缩到该值,0 表示不设固定下限。
  • 引入版本:-

es_http_timeout_ms

  • 默认值:5000
  • 类型:Int
  • 单位:毫秒
  • 是否动态:否
  • 描述:ESScanReader 在执行 Elasticsearch Scroll 请求时,ES 网络客户端的 HTTP 连接超时时间。在网络较慢或查询量较大时可适当调大,以避免过早超时;调小则可以更快感知 ES 节点无响应。与控制 Scroll 上下文存活时间的 es_scroll_keepalive 配合使用。
  • 引入版本:v3.2.0

es_index_max_result_window

  • 默认值:10000
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:限制 StarRocks 在单个批次中从 Elasticsearch 请求的最大文档数。StarRocks 在为 ES reader 构建 KEY_BATCH_SIZE 时将 ES 请求批大小设置为 min(es_index_max_result_window, chunk_size)。如果 ES 请求超过 Elasticsearch 索引设置 index.max_result_window,Elasticsearch 会返回 HTTP 400 (Bad Request)。在扫描大型索引时调整此值,或在 Elasticsearch 端增加 ES index.max_result_window 以允许更大的单次请求。
  • 引入版本:v3.2.0

ignore_load_tablet_failure

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:设置为 false 时,任何 Tablet Header 加载失败(非 NotFound 和非 AlreadyExist 的错误)均视为致命错误,BE 进程将调用 LOG(FATAL) 停止。设置为 true 时,BE 在启动时跳过加载失败的 Tablet,并继续加载其他 Tablet。注意:此参数不抑制 RocksDB 元数据扫描本身的致命错误,这类错误始终会导致进程退出。
  • 引入版本:v3.2.0

load_channel_abort_clean_up_delay_seconds

  • 默认值:600
  • 类型:Int
  • 单位:Seconds
  • 是否动态:是
  • 描述:控制 LoadChannelMgr 在将已中止的 load channel 的 load ID 从 _aborted_load_channels 中移除之前保留这些 load ID 的时长(以秒为单位)。当 load 作业被取消或失败时,load ID 会被记录下来以便立即拒绝任何迟到到达的 load RPC;一旦延迟到期,该条目将在周期性后台清理(最小清理间隔为 60 秒)时被清除。将延迟设置得过低会有在中止后仍接受零散 RPC 的风险,而设置得过高则可能比必要时间更长地保留状态并消耗资源。根据对迟到请求拒绝的正确性与中止 load 的资源保留之间的权衡进行调优。
  • 引入版本:v3.5.11, v4.0.4

load_diagnose_rpc_timeout_stack_trace_threshold_ms

  • 默认值:600000
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:用于决定何时为长时间运行的 load RPC 请求远程堆栈跟踪的阈值(毫秒)。当 load RPC 超时并返回超时错误且实际的 RPC 超时时间(_rpc_timeout_ms)超过此值时,OlapTableSink/NodeChannel 将在发往目标 BE 的 load_diagnose RPC 中包含 stack_trace=true,以便 BE 返回用于调试的堆栈跟踪。LocalTabletsChannel::SecondaryReplicasWaiter 也会在等待 secondary replicas 超过该间隔时触发从 primary 的尽力堆栈跟踪诊断。此行为依赖于 enable_load_diagnose 并使用 load_diagnose_send_rpc_timeout_ms 作为诊断 RPC 的超时;性能分析由 load_diagnose_rpc_timeout_profile_threshold_ms 单独控制。降低此值会更积极地请求堆栈跟踪。
  • 引入版本:v3.5.0

load_diagnose_rpc_timeout_profile_threshold_ms

  • 默认值:60000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:否
  • 描述:当 load RPC 超时且耗时超过该阈值时,在诊断 RPC 中收集 profile(performance profile)。依赖 enable_load_diagnose,诊断 RPC 超时由 load_diagnose_send_rpc_timeout_ms 控制。
  • 引入版本:v3.5.0

load_diagnose_send_rpc_timeout_ms

  • 默认值:2000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:否
  • 描述:诊断 RPC(收集 profile/堆栈)自身的超时时长。
  • 引入版本:v3.5.0

load_fp_brpc_timeout_ms

  • 默认值:-1
  • 类型:Int
  • 单位:毫秒
  • 是否动态:是
  • 描述:在触发 node_channel_set_brpc_timeout fail point 时,覆盖 OlapTableSink 所使用的每通道 brpc RPC 超时。如果设置为正值,NodeChannel 会将其内部 _rpc_timeout_ms 设置为该值(毫秒),使 open/add-chunk/cancel RPC 使用更短的超时,从而模拟产生 “[E1008]Reached timeout” 错误的 brpc 超时。默认值(-1)禁用覆盖。更改此值用于测试和故障注入;较小的值可能导致虚假超时并触发 load 诊断(参见 enable_load_diagnose、load_diagnose_rpc_timeout_profile_threshold_ms、load_diagnose_rpc_timeout_stack_trace_threshold_ms 和 load_diagnose_send_rpc_timeout_ms)。
  • 引入版本:v3.5.0

load_fp_tablets_channel_add_chunk_block_ms

  • 默认值:-1
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:否
  • 描述:导入 failpoint,“TabletsChannel::add_chunk” 人为阻塞的毫秒数,用于调试。
  • 引入版本:v3.4.3, v3.5.0

load_segment_thread_pool_num_max

  • 默认值:128
  • 类型:Int
  • 单位:Threads
  • 是否动态:否
  • 描述:导入 segment 处理线程池的最大线程数。调大提高并行度也会增加资源消耗。
  • 引入版本:-

load_segment_thread_pool_queue_size

  • 默认值:10240
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:导入 segment 线程池的队列长度,队列满时新的 segment 任务会被拒绝。
  • 引入版本:-

pull_load_task_dir

  • 默认值:${STARROCKS_HOME}/var/pull_load
  • 类型:string
  • 单位:-
  • 是否动态:否
  • 描述:BE 存储 “pull load” 任务的数据和工作文件(下载的源文件、任务状态、临时输出等)的文件系统路径。该目录必须对 BE 进程可写,并且具有足够的磁盘空间以容纳下载的内容。
  • 引入版本:v3.2.0

routine_load_pulsar_timeout_second

  • 默认值:10
  • 类型:Int
  • 单位:秒
  • 是否动态:否
  • 描述:BE 在请求未提供显式超时时使用的 Pulsar 相关 routine load 操作的默认超时(秒)。具体地,PInternalServiceImplBase::get_pulsar_info 将该值乘以 1000,形成以毫秒为单位的超时值,传递给用于获取 Pulsar 分区元数据和 backlog 的 routine load 任务执行器方法。增大该值可在 Pulsar 响应较慢时减少超时失败,但会延长故障检测时间;减小该值可在 broker 响应慢时更快失败。与用于 Kafka 的 routine_load_kafka_timeout_second 类似。
  • 引入版本:v3.2.0

routine_load_kafka_timeout_second

  • 默认值:10
  • 类型:Int
  • 单位:Seconds
  • 是否动态:否
  • 描述:Routine Load Kafka 操作的默认超时时长(未显式指定时使用)。
  • 引入版本:-

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。