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

BE 配置项 - 存算分离、数据湖和其他

· 52CE 我爱测

仅在**所有目标 CN** 均支持此能力后启用。规范化的复制事务会记录目标 Schema;若发布前目标 Schema 发生变化,发布将失败。关闭该配置只阻止新的准入,不改变已记录事务的回放行为。旧版 CN 无法安全回放这些事务日志;降级前必须完成或中止待处理的规范化事务,不能认为关闭配置就可以安全降级。

BE 配置项 - 存算分离、数据湖和其他

查看 BE 配置项

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

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

配置 BE 参数


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

存算分离

cloud_native_pk_index_rebuild_files_threshold

  • 默认值:50
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:云原生主键索引在恢复(Rebuild)时允许重建的最大 Segment 文件数。若需要重建的文件数超过该阈值,StarRocks 会立即将内存中的 MemTable 刷盘,以减少需要重放的 Segment 数量。设置为 0 则禁用此提前刷盘策略。
  • 引入版本:-

cloud_native_pk_index_rebuild_rows_threshold

  • 默认值:10000000
  • 类型:Long
  • 单位:行
  • 是否动态:是
  • 描述:云原生主键索引在恢复(Rebuild)时允许重建的最大行数。若需要重建的行数超过该阈值,StarRocks 会立即将内存中的 MemTable 刷盘,以降低索引重建开销。设置为 0 则禁用此提前刷盘策略。与 cloud_native_pk_index_rebuild_files_threshold 配合使用,任一阈值超出均会触发刷盘。此行数包含 Segment 行数以及 del 文件中记录的 tombstone(删除)行数,因此产生少量大型 del 文件的删除密集型负载也会计入该阈值;旧版本写入、未记录行数的 del 文件按 0 计。
  • 引入版本:-

download_buffer_size

  • 默认值:4194304
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:下载快照文件时每条传输流使用的内存缓冲区大小(fs::copy 的单次读写块大小)。值越大吞吐越高但每个并发下载占用更多内存。
  • 引入版本:v3.2.13

graceful_exit_wait_for_frontend_heartbeat

  • 默认值:false
  • 类型: Boolean
  • 单位:-
  • 是否动态:是
  • 描述: 确定是否在完成优雅退出前等待至少一个指示SHUTDOWN状态的FE心跳响应。启用后,优雅关闭进程将持续运行直至通过心跳RPC返回给FE SHUTDOWN状态变化,确保FE在两次常规心跳探测间隔期间有足够时间感知终止状态。
  • 引入版本:v3.4.5

lake_compaction_hold_input_segments

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中,Compaction 任务是否在其 Rowset 实例上持有输入 Segment 对象直至任务结束,使 Vertical Compaction 的各列组趟直接复用这些对象,而不再依赖元数据缓存重新加载。关闭持有时,一旦元数据缓存装不下全部输入 Segment(lake_segment_metadata_cache_limit_percent 较小,或节点上 Tablet 较多),每一趟都会重新加载并解析全部输入 Segment;该开销为 CPU 密集且与列数成正比,可能使宽表 Compaction 慢一个数量级,或因反复超出内存限制而失败。持有期间,任务不再把输入 Segment 和 Delete Vector 填入共享元数据缓存,因为输入数据在 Compaction 完成后即被删除,缓存它们只会挤掉其他 Tablet 的条目。内存代价为每个运行中任务持有一套输入 Segment 元数据,计入该 Compaction 任务的内存跟踪并随任务释放。设为 false 可恢复旧行为,即 Compaction 通过共享元数据缓存复用 Segment 并向其填充输入。
  • 引入版本:v4.2

lake_compaction_stream_buffer_size_bytes

  • 默认值:1048576
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群 Compaction 任务在远程 FS 读 I/O 阶段的 Buffer 大小。默认值为 1MB。您可以适当增大该配置项取值以加速 Compaction 任务。
  • 引入版本:v3.2.3

lake_dump_tablet_metadata_per_request_memory_limit_bytes

  • 默认值:268435456
  • 类型:Long
  • 单位:Bytes
  • 是否动态:是
  • 描述:CN 同步处理单个 /api/cloudnative/dump_tablet_metadata 请求时的受跟踪内存预算。该预算使用标准 MemTracker 统计粒度,并非精确到字节的硬上限。该限制覆盖元数据检查、敏感字段脱敏和 JSON 序列化,但不包含 CN 元数据缓存中已存在的元数据,也不包含异步 HTTP 输出缓冲区。每个请求使用其被接纳时读取到的配置值。如果该值小于或等于 0,新请求将以 fail-closed 方式被拒绝。
  • 引入版本:v4.2

lake_dump_tablet_metadata_per_request_json_size_limit_bytes

  • 默认值:33554432
  • 类型:Long
  • 单位:Bytes
  • 是否动态:是
  • 描述:单个 /api/cloudnative/dump_tablet_metadata 请求完整 JSON 响应的最大字节数。响应交给 HTTP 输出缓冲区之前会检查该限制。每个请求使用其被接纳时读取到的配置值。如果该值小于或等于 0,新请求将以 fail-closed 方式被拒绝。
  • 引入版本:v4.2

lake_dump_tablet_metadata_max_concurrency

  • 默认值:1
  • 类型:Int
  • 单位:请求
  • 是否动态:是
  • 描述:单个 CN 上可同时接纳的 /api/cloudnative/dump_tablet_metadata 请求数上限。请求在其 HTTP request 被释放之前一直占用一个并发名额。调大配置会立即影响新请求;调小配置不会取消已接纳的请求,在活跃请求数降到新上限以下之前会拒绝新请求。如果该值小于或等于 0,新请求将以 fail-closed 方式被拒绝。
  • 引入版本:v4.2

lake_enable_del_file_crc_check

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,在事务 Publish 或主键索引重建过程中读取主键表删除文件(.del)时,是否根据其元数据中记录的 CRC32C 进行校验。校验不通过时,该操作会返回文件损坏错误并失败,而不是删除错误的主键。在该校验和引入之前写入的删除文件不带校验和,会被始终接受,因此该配置项不会影响旧版本写入的数据。该配置项不控制校验和的写入,仅控制读取时是否校验。
  • 引入版本:v4.2

lake_enable_pk_preserve_txn_delete_order

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否在单个导入事务内保留主键表 UPSERT 与 DELETE 的先后顺序。当同一个导入事务中同一个 key 先 DELETE 后再 UPSERT 时,开启该配置后以最后写入的 UPSERT 为准(与存算一体集群行为一致)。默认开启。出于降级安全考虑,在回滚到(或与其混部)不支持该修复的 BE 版本之前,请先将其设为 false:开启后,导入可能会持久化新版本格式的元数据,若 BE 回滚到不支持该修复的版本会被错误解析,可能产生主键重复。关闭时,DELETE 回退到旧有行为(在事务内所有 UPSERT 之后生效)。
  • 引入版本:v4.1.4

lake_enable_protobuf_file_checksum

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否在写入存算分离集群的 Tablet 元数据和事务日志文件时附加 Adler-32 校验和,以便在读取时检测这些文件是否损坏。无论该配置项如何设置,读取端在文件包含校验和时都会自动识别并校验;该配置项仅控制写入格式。仅当集群仍可能降级到不支持该校验和格式的版本时,才将该配置项设置为 false。在滚动升级或降级期间,旧版本的 BE 或 CN 使用旧的读取逻辑,无法解析新格式写入的文件。
  • 引入版本:v4.2

lake_replication_enable_light_schema_change

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:允许存算分离集群复制包含兼容轻量加删列历史的活跃 Rowset 快照。源端与目标端的当前 Schema 必须在逻辑上匹配。新增列必须是具有默认值或可空语义的普通标量值列;不支持 Key 列、排序列、类型、生成列、嵌套列 UID、外部索引、捆绑文件及共享/范围 Tablet 的变更。关闭时,包含历史 Schema 活跃 Rowset 的快照会被拒绝。已验证删除的列会从 Segment footer 元数据中移除,不重写其数据页。每个复制任务启动时读取并固定该配置值。
  • 引入版本:-

仅在所有目标 CN 均支持此能力后启用。规范化的复制事务会记录目标 Schema;若发布前目标 Schema 发生变化,发布将失败。关闭该配置只阻止新的准入,不改变已记录事务的回放行为。旧版 CN 无法安全回放这些事务日志;降级前必须完成或中止待处理的规范化事务,不能认为关闭配置就可以安全降级。

lake_enable_publish_partial_meta

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中开启 File Bundling 的表在导入发布(Publish)时,是否保留聚合节点可能未收到的 Tablet 发布结果。某个 Tablet 的 Publish 在请求到达后超过 Publish RPC 超时时间加 3 秒才完成,或者本次 Publish 是重试,就会把结果保存在本节点的 Data Cache 中,不写入对象存储。之后该节点上的重试会直接读取这份结果,不再重新执行事务,因此慢分区每次重试时,已完成的 Tablet 不会被重做。这些缓存条目和其他 Data Cache 数据一样按需淘汰。仅在开启 Data Cache 时生效。所有 BE 和 CN 节点应设置相同的值。
  • 引入版本:v4.2

lake_pk_compaction_max_input_rowsets

  • 默认值:500
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,主键表 Compaction 任务中允许的最大输入 Rowset 数量。该参数默认值自 v3.2.4 和 v3.1.10 版本开始从 5 变更为 1000,并自 v3.3.1 和 v3.2.9 版本开始变更为 500。存算分离集群中的主键表在开启 Sized-tiered Compaction 策略后 (即设置 enable_pk_size_tiered_compaction_strategy 为 true),无需通过限制每次 Compaction 的 Rowset 个数来降低写放大,因此调大该值。
  • 引入版本:v3.1.8, v3.2.3

lake_pk_compaction_max_rowsets_per_level

  • 默认值:20
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,主键表的某个大小层中待合并的 Rowset 达到该数量时,即使该层得分不是最高,也会被合并。Size-tiered Compaction 策略每轮只合并得分最高的一层。持续导入时,最新写入的小 Rowset 所在层每轮得分都最高,由较大 Rowset(之前 Compaction 的产物和中等批次的导入)组成的层会一直增长,导致查询需要读取的 Segment 增多,并在 Compaction 刚完成时表现为 Compaction Score 的尖峰。当某个未被选中的层中待合并的 Rowset 达到该数量,且这些 Rowset 能与已选中的 Rowset 在同一次 Compaction 任务中合并时,该层会并入该次 Compaction 任务。设置为 0 表示关闭该行为。
  • 引入版本:-

lake_pk_compaction_base_enable_delete_trigger

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,主键表 Tablet 的删除量达到 lake_pk_compaction_base_delete_ratio_threshold 或 lake_pk_compaction_base_delete_rows_threshold 时,是否自动从 Cumulative Compaction 切换到 Base Compaction。默认关闭,因为 lake_pk_compaction_base_delete_rows_threshold 是绝对行数:在已有数据持续被更新或删除的大表上,Tablet 每次 Base Compaction 之后很快又会达到该值,而每次 Base Compaction 最多重写 Tablet 中 update_compaction_ratio_threshold(默认 0.5)比例的数据。手动执行 ALTER TABLE ... COMPACT 时,无论该参数如何设置都会执行 Base Compaction。
  • 引入版本:v4.1.6, v26.2.1

lake_pk_compaction_base_delete_ratio_threshold

  • 默认值:0.5
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,将主键表 Tablet 从 Cumulative Compaction(Size-tiered 小文件合并)切换到 Base Compaction 的两个触发条件之一。Base Compaction 会重写带删除的 Rowset(删除行数多的优先),物理清除被删除的行并缩小其 Delete Vector。lake_pk_compaction_base_enable_delete_trigger 为 true 时,当 Tablet 的整体删除比例(各 Rowset 的 sum(num_dels) / sum(num_rows))达到该值、或其累计删除行数达到 lake_pk_compaction_base_delete_rows_threshold 时触发。手动执行 ALTER TABLE ... COMPACT 时,无论这些参数如何设置都会强制执行 Base Compaction。
  • 引入版本:v4.2

lake_pk_compaction_base_delete_rows_threshold

  • 默认值:10000000
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下主键表 Base Compaction 的两个触发条件之一(参见 lake_pk_compaction_base_delete_ratio_threshold)。lake_pk_compaction_base_enable_delete_trigger 为 true 时,当 Tablet 的累计删除行数(各 Rowset 的 sum(num_dels))达到该值时触发 Base Compaction。该绝对数量触发条件是对比例触发条件的补充:在高频更新/删除的表上,Delete Vector 会膨胀、空间被浪费,但整体删除比例可能因大量存活行的稀释而偏低,仅靠比例触发条件不会触发。调大该值可降低 Base Compaction 频率,调小则可更早回收 Delete Vector。
  • 引入版本:v4.2

enable_lake_pk_compaction_score_gate

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下主键表 Size-tiered Compaction「评分门控」的总开关。默认开启时,会跳过低价值的稀疏中间层 Compaction:当被选中的层的 Compaction 评分低于 lake_pk_compaction_min_level_score,且未触发下述任一豁免条件时,该层不会被 Compaction,从而避免为极小的文件数收益而重写大量基线数据。设置为 false 可一键关闭整个门控;此时每个被选中的层都会无条件执行 Compaction(即门控引入前的行为),下述阈值参数也将不再生效。
  • 引入版本:v4.2

lake_pk_compaction_min_level_score

  • 默认值:2.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:主键表 Compaction 评分门控的评分阈值(参见 enable_lake_pk_compaction_score_gate)。当 Size-tiered 选层器选中的层的总评分低于该值,且未触发任何豁免条件时,跳过本次 Compaction。每个 Rowset 的评分为 io_count * 1MB / read_bytes,并按层求和:包含大量小 Rowset 或重叠 Rowset 的层评分高(值得 Compaction),而少量大的非重叠 Rowset 评分低(近乎纯粹的基线重写)。设置为 0 可使门控失效,因为层的评分恒大于等于 0。
  • 引入版本:v4.2

lake_pk_compaction_min_benefit_cost_ratio

  • 默认值:0.005
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:主键表 Compaction 评分门控的一个豁免条件。指低于阈值的层仍被 Compaction 所需的最小收益/成本比(每重写 1 MB 节省的 Segment 数)。该收益还会计入删除向量(delvec)的清理压力(参见 lake_pk_compaction_delvec_benefit_weight)。设置为 0 可禁用该豁免,此时仅 lake_pk_compaction_min_level_score 生效。
  • 引入版本:v4.2

lake_pk_compaction_emergency_score

  • 默认值:50.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:主键表 Compaction 评分门控的一个豁免条件。当 Tablet 整体的读取压力评分(所有 Rowset 评分之和)达到该值时,即使被选中的层低于 lake_pk_compaction_min_level_score,也会执行 Compaction,从而避免读放大严重的热点 Tablet 长期得不到 Compaction。设置为 0 可禁用该豁免。
  • 引入版本:v4.2

lake_pk_compaction_delvec_benefit_weight

  • 默认值:12.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:在 lake_pk_compaction_min_benefit_cost_ratio 使用的收益/成本比中,将层的删除压力换算为等效 Segment 收益单位的权重,计算公式为 benefit = real_benefit_segments + delete_ratio * input_segments * weight。值越大,Compaction 越积极地清理删除向量;值越小,越倾向于降低写放大。设置为 0 可去除删除项的贡献,此时该比值仅反映 Segment 数收益。
  • 引入版本:v4.2

lake_pk_compaction_size_overflow_ratio

  • 默认值:2.0
  • 类型:Double
  • 单位:-
  • 是否动态:是
  • 描述:主键表 Compaction 评分门控的一个豁免条件。当低于阈值的层的总字节数超过 ratio * largest_rowset_bytes * size_tiered_level_multiple(即自然的下一层晋升目标的 ratio 倍)时,强制执行 Compaction,以约束长尾的中间层堆积。默认值 2.0 表示在强制合并前容忍达到自然晋升阈值的两倍。设置为 0 可禁用该豁免,即不设置大小上限。
  • 引入版本:v4.2

lake_pk_partial_update_use_segment_cache

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中主键表的 publish 在读取所需的基底 Segment 时,是否通过 Segment 元数据缓存读取,而不是每次都重新打开。该项同时覆盖行模式部分列更新和条件更新,二者都需要从相同的 Segment 重新读取旧值。打开一个 Segment 需要解析其 footer 并为表 Schema 的每一列创建一个列读取器,因此在宽表上,高频的部分列更新会在每次 publish 时对相同的基底 Segment 重复付出这份开销。通过缓存读取可以让后续的 publish 复用已经打开的 Segment。包含 JSON、ARRAY、MAP 或 STRUCT 列,或通过 zstd_compression_columns 启用列级压缩的列时,使用原有的打开路径,因为按顶层列数估算无法涵盖嵌套元数据或压缩字典。关闭字典写入后,这些表仍绕过缓存,因为已有 Segment 可能仍包含字典。仅当该 tablet 的基底 Segment 能够全部放入 Segment 元数据缓存(容量由 lake_segment_metadata_cache_limit_percent 决定),且每个 Segment 的估计大小不超过单个缓存分片的容量时才使用缓存;否则,填充缓存会以与写入相同的速度淘汰条目,因此会退回原有行为。之所以按整个 tablet 而非单次 publish 计算,是因为相继的多次 publish 读取的是其中不同的子集。将该项设置为 false 可始终重新打开 Segment。
  • 引入版本:v4.2

enable_lake_prepared_split_pre_refinement

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:Prepared Physical Split Lake 扫描(对应会话变量 enable_lake_prepared_physical_split_scan)在 Seed 逐页裁剪尚未完成时,是否额外下发一个覆盖未裁剪 Segment 范围的 Coarse-range morsel,让原本空闲的 Driver 提前开始工作,直到裁剪后的 Refined Rang 就绪。关闭它不会丢失数据(Coarse Range 始终是 Refined Range 从中相减的超集),只是用提前并行换取更少的冗余 Coarse 扫描。
  • 引入版本:v4.2

lake_prepared_split_max_splitted_scan_rows

  • 默认值:262144
  • 类型:Int
  • 单位:行
  • 是否动态:是
  • 描述:仅在开启 Prepared Physical Split Lake 扫描(参见会话变量 enable_lake_prepared_physical_split_scan)时生效的 splitted_scan_rows(每个 Split Morsel 扫描的行数)上限。实际上限为 min(tablet_internal_parallel_max_splitted_scan_rows, 本参数),因此只会将 Split Morsel 拆得更细(把大 Tablet 切成更多子范围 Morsel 以填充原本空闲的 Driver),不会更粗。仅在存算分离集群中生效。
  • 引入版本:v4.2

lake_put_txn_log_timeout_guard_ms

  • 默认值:-1
  • 类型:Int64
  • 单位:毫秒
  • 是否动态:是
  • 描述:存算分离集群下,向对象存储写入事务日志(put_txn_log 和 put_combined_txn_log 路径)的超时守护阈值。如果写入一条事务日志的耗时超过该值,StarRocks 会将慢线程的堆栈打印到 BE 日志,以便诊断对象存储写入慢的问题。默认关闭(小于或等于 0 表示关闭该守护);如需开启,可将其设置为正值,例如 4000(4 秒)。
  • 引入版本:-

lake_rows_mapper_read_parallelism

  • 默认值:32
  • 类型:Int
  • 单位:sub-chunk 个数
  • 是否动态:是
  • 描述:存算分离集群下,主键表轻量 Compaction 发布阶段,RowsMapperIterator 读取 .lcrm(lake compaction rows-mapper)文件时,允许同时 in-flight 的 sub-chunk 读取数量上限。每个 sub-chunk 大小由 lake_rows_mapper_sub_chunk_bytes 控制,且不跨 segment 边界。迭代器最多向 PK index 执行线程池提交该数量的并发读取请求,让远端读取与调用方的 per-segment 处理流水化进行。内存上限为 lake_rows_mapper_read_parallelism * lake_rows_mapper_sub_chunk_bytes。设为 1 可关闭流水化,回退到顺序读取。

lake_rows_mapper_sub_chunk_bytes

  • 默认值:4194304
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群下,主键表轻量 Compaction 发布阶段,RowsMapperIterator 流水化读取 .lcrm 文件时使用的 sub-chunk 粒度。每个输出 segment 被切分为 ceil(segment_bytes / lake_rows_mapper_sub_chunk_bytes) 个 sub-chunk,独立流水化。值越小,少而大的输出 segment 能获得越高的并发度,但代价是更多的范围读取和消费时一次额外的 memcpy。默认 4 MiB,与 starcache 磁盘层 block 大小对齐。

lake_segment_metadata_cache_limit_percent

  • 默认值:10
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中 Segment 元数据缓存的容量,以 BE 进程内存上限的百分比表示。该缓存存放已打开的 Segment(包括 Footer、索引和列读取器)、Delete Vector 以及 Tablet Schema。它与 Tablet 元数据缓存(参见 lake_tablet_metadata_cache_limit_percent)相互独立,加载再多的 Segment 也不会把 Tablet 元数据和事务日志挤出缓存。超出 0–100 的取值按 0 或 100 处理。设为 0 即关闭该缓存。该项与 lake_tablet_metadata_cache_limit_percent 共同取代原有的 lake_metadata_cache_limit。该值是缓存容量的上限,BE 进程内存紧张时缓存会缩到该值以下(参见 lake_tablet_metadata_cache_min_limit)。
  • 引入版本:-

lake_segment_metadata_cache_min_limit

  • 默认值:1073741824
  • 类型:Long
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,Segment 元数据缓存在内存紧张时让出内存(参见 lake_tablet_metadata_cache_min_limit),容量不会缩到该值以下。如果该值大于 lake_segment_metadata_cache_limit_percent 设定的容量,缓存保持该容量不变。
  • 引入版本:-

lake_shard_info_cache_ttl_sec

  • 默认值:60
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:存算分离集群下,BE 或 CN 保留不归自己持有的 tablet 的存储位置的时长。在此期间再次访问该 tablet,不必向 StarMgr 查询。节点保留两类存储位置。第一类是节点自己向 StarMgr 查询得到的:节点读写分配给其他节点的 tablet 的文件时需要查询,查询计入 starrocks_be_staros_shard_info_fallback_total,例如一次导入由多个节点同时写同一个 tablet,或者 Vacuum 读取一个分区内所有 tablet 的元数据;由这类位置直接应答的查询计入 staros_shard_info_fallback_cache_hits_total。第二类是持有 tablet 的节点交来的:向开启了 file_bundling 的表导入时,持有节点在回传事务日志时附带存储位置,负责该导入的协调节点据此写各分区的 combined txn log,无需查询;由这类位置直接应答的查询计入 lake_tablet_location_handoff_hits_total。持有 tablet 的节点会收到 StarMgr 推送的存储卷变更,而保留的存储位置要到过期后才会更新,因此该配置项同时限定了这类节点最多还会使用多久过时的存储卷配置,例如已轮换的访问凭证。保留的存储位置包含存储卷的访问凭证。设为 0 表示两类都关闭:既不交接也不保留,每次都向 StarMgr 查询。
  • 引入版本:-

lake_tablet_metadata_cache_limit_percent

  • 默认值:5
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中 Tablet 元数据缓存的容量,以 BE 进程内存上限的百分比表示。该缓存存放 Tablet 元数据和事务日志。它与 Segment 元数据缓存(参见 lake_segment_metadata_cache_limit_percent)相互独立,加载再多的 Segment 也不会把这些元数据挤出缓存。超出 0–100 的取值按 0 或 100 处理。设为 0 即关闭该缓存。该项与 lake_segment_metadata_cache_limit_percent 共同取代原有的 lake_metadata_cache_limit。该值是缓存容量的上限,BE 进程内存紧张时缓存会缩到该值以下(参见 lake_tablet_metadata_cache_min_limit)。
  • 引入版本:-

lake_tablet_metadata_cache_min_limit

  • 默认值:1073741824
  • 类型:Long
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,Tablet 元数据缓存容量的下限。BE 进程内存占用超过 memory_high_level 后,Tablet 元数据缓存和 Segment 元数据缓存把容量调到当前占用以下,淘汰最久未使用的条目。需要让出的内存,按两个缓存各自超出下限(该项和 lake_segment_metadata_cache_min_limit)的占用比例分摊。超出 memory_high_level 的部分在约 50 秒内逐步释放;如果占用还超过了 memory_urgent_level,超出 memory_urgent_level 的部分立即释放。占用回落到 memory_high_level 以下后,两个缓存的容量在约 200 秒内逐步恢复到 lake_tablet_metadata_cache_limit_percent 和 lake_segment_metadata_cache_limit_percent 设定的值。每 10 秒检查一次。如果该值大于 lake_tablet_metadata_cache_limit_percent 设定的容量,缓存保持该容量不变。
  • 引入版本:-

lake_vacuum_enable_task_timeout

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:Vacuum 任务是否遵循请求中携带的超时时间(VacuumRequest.timeout_ms),并在超时后自行终止。设为 false 时,无论 FE 调用方等待多久,Vacuum 任务都会一直运行至完成。

lake_vacuum_min_batch_delete_size

  • 默认值:200
  • 类型:Int64
  • 单位:文件数
  • 是否动态:是
  • 描述:存算分离集群下,Vacuum 单次 DeleteObjects 请求批量合并的过期文件数量。批量越大,单次调用摊销的 HTTP/认证/签名等固定开销越多,且对对象存储 prefix 级别的请求频次压力越小;代价是单次调用 latency 升高、出现瞬时错误需要 retry 时回放成本增大。AWS S3 用户可以进一步将该值调到协议上限 1000,因为 AWS S3 单 DeleteObjects 服务端耗时几乎与 batch size 无关。

loop_count_wait_fragments_finish

  • 默认值:2
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:BE/CN 退出时需要等待正在执行的查询完成的轮次,一轮次固定 10 秒。设置为 0 表示禁用轮询等待,立即退出。自 v3.4 起,该参数变为动态参数,且默认值由 0 变为 2。
  • 引入版本:v2.5

max_client_cache_size_per_host

  • 默认值:10
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:BE 范围内的客户端缓存为每个远程主机保留的最大缓存 client 实例数。提高此值可以减少重连和 stub 创建开销,但会增加内存和文件描述符使用;降低它则节省资源但可能增加连接 churn。该值在启动时读取,运行时无法更改。目前一个共享设置控制所有客户端缓存类型;将来可能会引入每种缓存的独立配置。
  • 引入版本:v3.2.0

paimon_native_parquet_cache_hole_size_limit

  • 默认值: 1048576
  • 类型: Long
  • 单位: Bytes
  • 是否动态配置: 是
  • 描述: Paimon native reader 将两个必需的 Parquet 读取范围合并为一次读取时允许的最大间隔。值越大,请求次数越少,但读放大越多。默认值与 StarRocks 原生 Parquet reader 使用的 io_coalesce_read_max_distance_size 一致;paimon-cpp 自身的默认值远小于此,会在对象存储上产生大量小请求。
  • 引入版本: -

primary_key_index_memory_high_percent

  • 默认值: 75
  • 类型: Int
  • 单位: -
  • 是否动态配置: 是
  • 描述: 存算分离集群中,后台线程定期回收主键索引缓存的目标,以缓存容量的百分比表示。缓存容量即更新相关内存的上限(参见 update_memory_limit_percent)。占用超过该比例时,按最近最少使用的顺序淘汰未在使用的主键索引,直至占用回落到该比例以内。正在使用的主键索引不会被淘汰。建议设置为小于 primary_key_index_memory_urgent_percent 的值。
  • 引入版本: -

primary_key_index_memory_middle_percent

  • 默认值: 50
  • 类型: Int
  • 单位: -
  • 是否动态配置: 是
  • 描述: 存算分离集群中主键表 Publish 因超出内存限制而失败时,主键索引缓存的回收目标,以缓存容量的百分比表示。此时系统会淘汰未在使用的主键索引,直至占用回落到该比例以内,为重试的 Publish 腾出内存。建议设置为小于 primary_key_index_memory_high_percent 的值。
  • 引入版本: -

primary_key_index_memory_urgent_percent

  • 默认值: 85
  • 类型: Int
  • 单位: -
  • 是否动态配置: 是
  • 描述: 存算分离集群中主键索引缓存的占用上限,以缓存容量的百分比表示。每次 Publish 结束后(因超出内存限制而失败的除外)都会检查一次:占用超过该比例时,按最近最少使用的顺序淘汰未在使用的主键索引,直至占用回落到该比例以内。缓存增长快于后台线程将其回收到 primary_key_index_memory_high_percent 的速度时,由该配置项兜底,因此应设置为大于该配置项的值。
  • 引入版本: -

s3_multipart_equal_part_size

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:向 S3 或兼容 S3 的对象存储进行分片上传(Multipart Upload)时,是否让除最后一个分片以外的所有分片大小完全一致。部分兼容 S3 的对象存储(如 Cloudflare R2)要求非末尾分片大小相同,否则会拒绝整次分片上传,并报错 InvalidPart: All non-trailing parts must have the same length。使用此类对象存储时需开启该参数。开启后,除最后一个分片外,每个分片都严格等于配置的分片大小:存算分离集群中的 starlet 上传按 starlet_fslib_s3_min_upload_part_size 切分,BE 其他带缓冲的 S3 上传按 experimental_s3_min_upload_part_size 切分。默认值 false 保持原有行为:缓冲数据一旦达到分片大小,就把整个缓冲区作为一个分片上传,因此各分片大小不一。Parquet、ORC、CSV 文件写入器写出的文件(例如 INSERT INTO FILES 导出的文件,以及 Hive、Iceberg Sink 写出的文件)边生成边上传分片,不受该参数影响。修改后仅对之后开始的上传生效。S3 单次分片上传最多允许 10000 个分片,因此按等大分片上传的对象不能超过分片大小的 10000 倍;以 starlet 默认的 5 MiB 分片计算,上限约为 48.8 GiB。如需写入更大的对象,请调大分片大小。
  • 引入版本:-

starlet_filesystem_instance_cache_capacity

  • 默认值:10000
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:starlet filesystem 实例的缓存容量。
  • 引入版本:v3.2.16, v3.3.11, v3.4.1

starlet_filesystem_instance_cache_ttl_sec

  • 默认值:86400
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:starlet filesystem 实例缓存的过期时间。
  • 引入版本:v3.3.15, 3.4.5

starlet_fslib_azure_storage_max_single_part_size

  • 默认值:104857600
  • 类型:Int64
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,写入 Azure Blob Storage 或 ADLS Gen2 的对象超过该大小时,使用分片上传(Multipart Upload)而非单次上传请求。Azure 的两种文件系统共用该参数。切换到分片上传之前,每个输出流最多在内存中缓存该大小的数据,因此调大该值会增加内存占用,且随并发输出流数量成倍增加。若调得过大以完全避开分片上传,一旦超过对象存储的单次请求上传上限,也可能导致上传直接失败,并返回该存储后端自身的错误。修改该参数对正在进行的上传立即生效。取值必须大于 0,非正数将被拒绝。合法取值会覆盖通过 BE 命令行传入的对应的 --fslib_* gflag;而在 BE 启动时被拒绝的取值不会生效,BE 保留此前生效的值并记录 WARNING 日志,此时该参数显示的值可能并非实际生效的值。
  • 引入版本:v4.1.5, v4.2

starlet_fslib_azure_storage_min_upload_part_size

  • 默认值:5242880
  • 类型:Int64
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,向 Azure Blob Storage 或 ADLS Gen2 进行分片上传时使用的块(Block)大小。Azure 的两种文件系统共用该参数。每次上传块之前,每个输出流最多在内存中缓存该大小的数据,因此调大该值会增加内存占用,且随并发输出流数量成倍增加。取值过小会增加请求数量,并可能超出存储服务的块数量限制。修改该参数对正在进行的上传立即生效。取值必须大于 0,非正数将被拒绝。合法取值会覆盖通过 BE 命令行传入的对应的 --fslib_* gflag;而在 BE 启动时被拒绝的取值不会生效,BE 保留此前生效的值并记录 WARNING 日志,此时该参数显示的值可能并非实际生效的值。
  • 引入版本:v4.1.5, v4.2

starlet_fslib_gcs_max_single_part_size

  • 默认值:104857600
  • 类型:Int64
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,写入 Google Cloud Storage 的对象超过该大小时,使用流式上传而非单次 Insert 请求。切换到流式上传之前,每个输出流最多在内存中缓存该大小的数据,因此调大该值会增加内存占用,且随并发输出流数量成倍增加。若调得过大以完全避开流式上传,一旦超过对象存储的单次请求上传上限,也可能导致上传直接失败,并返回该存储后端自身的错误。修改该参数对正在进行的上传立即生效。取值必须大于 0,非正数将被拒绝。合法取值会覆盖通过 BE 命令行传入的对应的 --fslib_* gflag;而在 BE 启动时被拒绝的取值不会生效,BE 保留此前生效的值并记录 WARNING 日志,此时该参数显示的值可能并非实际生效的值。
  • 引入版本:v4.1.5, v4.2

starlet_fslib_s3_max_single_part_size

  • 默认值:104857600
  • 类型:Int64
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,写入 S3 或兼容 S3 的对象存储的对象超过该大小时,使用分片上传(Multipart Upload)而非单次 PutObject 请求。切换到分片上传之前,每个输出流最多在内存中缓存该大小的数据,因此调大该值会增加内存占用,且随并发输出流数量成倍增加。若调得过大以完全避开分片上传,也可能导致上传直接失败:AWS S3 拒绝单次 PutObject 超过 5 GiB 的对象,其他兼容 S3 的对象存储限制可能不同。修改该参数对正在进行的上传立即生效。取值必须大于 0,非正数将被拒绝。合法取值会覆盖通过 BE 命令行传入的对应的 --fslib_* gflag;而在 BE 启动时被拒绝的取值不会生效,BE 保留此前生效的值并记录 WARNING 日志,此时该参数显示的值可能并非实际生效的值。该参数用于存算分离集群中的 starlet 上传,与 experimental_s3_* 系列参数无关。
  • 引入版本:v4.1.5, v4.2

starlet_fslib_s3_min_upload_part_size

  • 默认值:5242880
  • 类型:Int64
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离集群中,向 S3 或兼容 S3 的对象存储进行分片上传时使用的分片大小。每次上传分片之前,每个输出流最多在内存中缓存该大小的数据,因此调大该值会增加内存占用,且随并发输出流数量成倍增加。取值过小会增加请求数量,并可能超出 AWS S3 的 10000 个分片上限,或低于其 5 MB 的最小分片大小;其他兼容 S3 的对象存储限制不同。修改该参数对正在进行的上传立即生效。取值必须大于 0,非正数将被拒绝。合法取值会覆盖通过 BE 命令行传入的对应的 --fslib_* gflag;而在 BE 启动时被拒绝的取值不会生效,BE 保留此前生效的值并记录 WARNING 日志,此时该参数显示的值可能并非实际生效的值。该参数用于存算分离集群中的 starlet 上传,与 experimental_s3_* 系列参数无关。
  • 引入版本:v4.1.5, v4.2

starlet_port

  • 默认值:9070
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:BE 和 CN 的额外 Agent 服务端口。
  • 引入版本:-

starlet_star_cache_disk_size_percent

  • 默认值:80
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:存算分离集群中,Data Cache 最多可使用的磁盘容量百分比。仅在 datacache_unified_instance_enable 为 false 时生效。
  • 引入版本:v3.1

starlet_star_cache_skip_fresh_block_checksum_verification

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:存算分离集群中,对于由当前 CN 进程写入且此后未被淘汰的 Data Cache 磁盘 Block,后续请求首次访问时是否跳过整块 Checksum 校验读取。该校验会从磁盘重新读取整个 Block,以校验进程刚刚写入且仍在内存中跟踪的数据,因此每个新写入 Block 的首次访问都会多一次磁盘读取。将该项设置为 false 可在首次访问时校验每个 Block,仅当怀疑缓存磁盘存在静态数据损坏时才值得付出该开销。无论该项如何设置,从进程上一次运行继承下来的 Block 始终会被校验,因为当前进程并未见证其写入过程。该项仅在 Data Cache 初始化时读取一次。
  • 引入版本:v4.2.0

starlet_starmgr_client_compression_type

  • 默认值:none
  • 类型:String
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中,当前 CN 发送给 StarMgr 的 Worker 心跳所使用的压缩方式。该心跳会为 CN 上的每个 Tablet 携带一个条目,是集群中最大的周期性请求。有效值:none 和 zstd。zstd 在心跳线程中压缩负载,并占用同一个 RPC 超时预算,由 FE 负责解压。none 表示不压缩发送心跳。在切换任何 CN 之前,FE 必须具备解压能力,因为不支持该机制的 FE 会丢弃压缩后的心跳,所以请先升级 FE,再在 CN 上设置该项。无法识别的取值会被记录并回退为 none,而不会导致 CN 启动失败。
  • 引入版本:v4.2.0

starlet_use_star_cache

  • 默认值:false(v3.1)true(v3.2.3 起)
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群中是否使用 Data Cache。true 表示启用该功能,false 表示禁用。自 v3.2.3 起,默认值由 false 调整为 true。
  • 引入版本:v3.1

starlet_write_file_with_tag

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否将写入到对象存储的文件打上对象存储 Tag,方便自定义管理文件。
  • 引入版本:v3.5.3

table_schema_service_max_retries

  • 默认值:3
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:Table Schema Service 请求的最大重试次数。
  • 引入版本:v4.1

数据湖

datacache_block_buffer_enable

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否启用 Block Buffer 优化 Data Cache 效率。当启用 Block Buffer 时,系统会从 Data Cache 中读取完整的 Block 数据并缓存在临时 Buffer 中,从而减少频繁读取缓存带来的额外开销。
  • 引入版本:v3.2.0

datacache_disk_adjust_interval_seconds

  • 默认值:10
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:Data Cache 容量自动调整周期。每隔这段时间系统会进行一次缓存磁盘使用率检测,必要时触发相应扩缩容操作。
  • 引入版本:v3.3.0

datacache_disk_idle_seconds_for_expansion

  • 默认值:180
  • 类型:Int
  • 单位:秒
  • 是否动态:是
  • 描述:Data Cache 自动扩容最小等待时间。只有当磁盘使用率在 datacache_disk_low_level 以下持续时间超过该时长,才会触发自动扩容。
  • 引入版本:v3.3.0

datacache_disk_size

  • 默认值:100%
  • 类型:String
  • 单位:-
  • 是否动态:是
  • 描述:单个磁盘缓存数据量的上限,可设为比例上限(如 80%)或物理上限(如 2T, 500G 等)。假设系统使用了两块磁盘进行缓存,并设置 datacache_disk_size 参数值为 21474836480,即 20 GB,那么最多可缓存 40 GB 的磁盘数据。比例上限是相对于每个 storage_root_path 所在磁盘的容量。默认值为 100%。当 enable_datacache_disk_auto_adjust 为 true(默认)时,系统会根据磁盘使用率自动调整实际的磁盘缓存容量,该参数仅作为该容量的上限。设为 0 表示禁用磁盘缓存。
  • 引入版本:-

datacache_enable

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:否
  • 描述:是否启用 Data Cache。true 表示启用,false 表示不启用。自 v3.3 起,默认值变为 true。
  • 引入版本:-

datacache_eviction_policy

  • 默认值:slru
  • 类型:String
  • 单位:-
  • 是否动态:否
  • 描述:缓存淘汰策略。有效值:lru (least recently used) 和 slru (Segmented LRU)。
  • 引入版本:v3.4.0

datacache_inline_item_count_limit

  • 默认值:130172
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Data Cache 内联对象数量上限。当缓存的 Block 对象特别小时,Data Cache 会选择使用内联方式将 Block 数据和元数据一起缓存在内存中。
  • 引入版本:v3.4.0

datacache_mem_size

  • 默认值:0
  • 类型:String
  • 单位:-
  • 是否动态:是
  • 描述:内存缓存数据量的上限,可设为比例上限(如 10%)或物理上限(如 10G, 21474836480 等)。
  • 引入版本:-

datacache_min_disk_quota_for_adjustment

  • 默认值:10737418240
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:Data Cache 自动扩缩容时的最小有效容量。当需要调整的目标容量小于该值时,系统会直接将缓存空间调整为 0,以避免缓存空间过小导致频繁填充和淘汰带来负优化。
  • 引入版本:v3.3.0

datacache_unified_instance_enable

  • 默认值:true
  • 类型:Bool
  • 单位:-
  • 是否动态:否
  • 描述:存算分离集群中,是否使用统一的 data cache 实例管理 internal catalog 和 external catalog 的数据缓存。
  • 引入版本:v3.4.0

disk_high_level

  • 默认值:90
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:磁盘高水位(百分比)。当磁盘使用率高于该值时,系统自动淘汰 Data Cache 中的缓存数据。自 v3.4.0 起,该参数默认值由 80 变更为 90。该参数自 v4.0 起由 datacache_disk_high_level 更名为 disk_high_level。
  • 引入版本:v3.3.0

disk_low_level

  • 默认值:60
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:磁盘低水位(百分比)。当磁盘使用率在 datacache_disk_idle_seconds_for_expansion 指定的时间内持续低于该值,且用于缓存数据的空间已经写满时,系统将自动进行缓存扩容,增加缓存上限。该参数自 v4.0 起由 datacache_disk_low_level 更名为 disk_low_level。
  • 引入版本:v3.3.0

disk_safe_level

  • 默认值:80
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:磁盘安全水位(百分比)。当 Data Cache 进行缓存自动扩缩容时,系统将尽可能以该阈值为磁盘使用率目标调整缓存容量。自 v3.4.0 起,该参数默认值由 70 变更为 80。该参数自 v4.0 起由 datacache_disk_safe_level 更名为 disk_safe_level。
  • 引入版本:v3.3.0

enable_connector_sink_spill

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否支持在外表写入时启用数据 Spill。启用该功能能够避免当内存不足时写入外表导致生成大量小文件问题。当前仅支持向 Iceberg 表写入数据时启用 Spill 功能。
  • 引入版本:v4.0.0

enable_datacache_disk_auto_adjust

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:Data Cache 磁盘容量自动调整开关,启用后会根据当前磁盘使用率动态调整缓存容量。该参数自 v4.0 起由 datacache_auto_adjust_enable 更名为 enable_datacache_disk_auto_adjust。
  • 引入版本:v3.3.0

external_table_clear_corrupted_cache_data

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否允许自动清理外表文件(例如 Hive 表、Iceberg 表)损坏的数据缓存。扫描文件时,如果从数据缓存读到的内容解析失败,系统会删除本次读到的缓存块,下次读取该文件时从远端存储重新读取。对于 Parquet 文件,如果出错前还未返回任何行,系统会先绕过数据缓存重新读取该文件,读取成功后才删除缓存块。该参数不影响存算分离集群的内表,内表由 lake_clear_corrupted_cache_data 控制。
  • 引入版本:-

jdbc_connection_idle_timeout_ms

  • 默认值:600000
  • 类型:Int
  • 单位:毫秒
  • 是否动态:否
  • 描述:JDBC 空闲连接超时时间。如果 JDBC 连接池内的连接空闲时间超过此值,连接池会关闭超过 jdbc_minimum_idle_connections 配置项中指定数量的空闲连接。如果某个连接池在此时间内没有被任何查询使用,BE 会关闭整个连接池(包括 jdbc_minimum_idle_connections 保留的连接),并在下一次查询时重新创建。这样可以释放已删除或已修改的 JDBC Catalog 和资源所对应的连接池。
  • 引入版本:-

jdbc_connection_pool_size

  • 默认值:8
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:JDBC 连接池大小。每个 BE 节点上访问 jdbc_url 相同的外表时会共用同一个连接池。
  • 引入版本:-

jdbc_minimum_idle_connections

  • 默认值:1
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:JDBC 连接池中最少的空闲连接数量。
  • 引入版本:-

jdbc_connection_max_lifetime_ms

  • 默认值:300000
  • 类型:Long
  • 单位:毫秒
  • 是否动态:否
  • 描述:JDBC 连接池中连接的最大生命周期。连接在此超时前会被回收,以防止出现陈旧连接。允许的最小值为 30000 (30 秒)。
  • 引入版本:-

jdbc_connection_keepalive_time_ms

  • 默认值:30000
  • 类型:Long
  • 单位:毫秒
  • 是否动态:否
  • 描述:空闲 JDBC 连接的保活间隔。空闲连接会在此间隔进行测试,以主动检测陈旧连接。设置为 0 可禁用保活探测。启用时,必须 >= 30000 且小于 jdbc_connection_max_lifetime_ms。无效的启用值将被静默禁用(重置为 0)。
  • 引入版本:-

lake_clear_corrupted_cache_data

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否允许自动清理损坏的数据缓存。
  • 引入版本:v3.4

lake_pk_index_sst_verify_checksum

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,读取云原生主键索引 sstable(点查与 Compaction 归并)时是否校验数据块 Checksum。开启后,损坏的字节(通常来自损坏的本地缓存副本)会确定性地报 Corruption 错误并触发损坏缓存清理,而不是被错误解析或静默返回错误的索引值。注意:自动清理损坏缓存还需同时开启 lake_clear_corrupted_cache_data。
  • 引入版本:v4.1

lake_clear_corrupted_cache_meta

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否允许自动清理损坏的元数据缓存。作用范围包括 Tablet 元数据文件和事务日志(txn log)文件的本地缓存。读取此类文件时如果遇到数据损坏错误,系统会清除对应的缓存副本,并从远端存储重新读取一次。
  • 引入版本:v3.3

lake_enable_horizontal_compaction_fill_data_cache

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否允许 Horizontal Compaction 任务将读取的输入数据缓存到本地磁盘上。true 表示启用,false 表示不启用。Horizontal Compaction 对每个输入 Segment 只读取一次,且输入 Rowset 在任务结束后即被替换,因此缓存这部分数据主要会挤占本地缓存中的查询热数据。设置为 true 可恢复此前始终缓存的行为。
  • 引入版本:v4.2

lake_enable_vertical_compaction_fill_data_cache

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:存算分离集群下,是否允许 Vertical Compaction 任务在执行时缓存数据到本地磁盘上。true 表示启用,false 表示不启用。
  • 引入版本:v3.1.7, v3.2.3

lake_replication_read_buffer_size

  • 默认值:16777216
  • 类型:Long
  • 单位:Bytes
  • 是否动态:是
  • 描述:存算分离跨集群复制(lake replication)下载 segment 文件时使用的读缓冲区大小。该值决定每次读取远程文件的分配大小,实际使用时取此设置与 1 MB 的较大值。较大的值减少读取调用次数,可提高吞吐,但增加每个并发下载的内存占用;较小的值降低内存使用但增加 I/O 调用次数。请根据网络带宽、存储 I/O 特性和并行复制线程数量进行调优。
  • 引入版本:v4.1.2

lake_replication_max_file_copy_retry

  • 默认值:3
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离跨集群复制(lake-to-lake replication)中非 segment 文件(.sst、.delvec、.del、.cols)拷贝的最大重试次数。每次尝试会校验已拷贝文件大小是否与源文件一致,以检测因对象存储瞬时问题导致的截断拷贝。如果在不稳定的存储上复制时频繁出现文件损坏,可增大此值。
  • 引入版本:v4.1.2

lake_replication_file_copy_threads

  • 默认值:16
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:存算分离跨集群复制(lake-to-lake replication)逐文件拷贝所使用的 CN 全局独立线程池大小。默认值用于限制并发拷贝任务及其读缓冲区,不随 CPU 核数增长。0 表示 cpu_cores * 4;负值表示 -value * cpu_cores。该线程池在启动时一次性创建,调整大小需重启 CN。
  • 引入版本:v4.1.2

lake_replication_max_parallel_files_per_tablet

  • 默认值:4
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离跨集群复制(lake-to-lake replication)中单个 tablet 同时拷贝文件的最大数量。所有 tablet 共用 CN 全局的 lake_replication_file_copy_threads 线程池,因此该配置可防止单个 tablet 独占线程池。配置值小于或等于 1 时,单个 tablet 内的文件串行拷贝。
  • 引入版本:v4.1.4

lake_replication_parallel_copy_min_file_count

  • 默认值:2
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:存算分离跨集群复制(lake-to-lake replication)中,启用单个 tablet 内文件并行拷贝所需的最小文件数。设置为 0 时关闭独立文件拷贝线程池,由调用复制任务直接执行文件拷贝。
  • 引入版本:v4.1.2

lake_service_max_concurrency

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:在存算分离集群中,RPC 请求的最大并发数。当达到此阈值时,新请求会被拒绝。将此项设置为 0 表示对并发不做限制。
  • 引入版本:-

query_max_memory_limit_percent

  • 默认值:90
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Query Pool 能够使用的最大内存上限。以 Process 内存上限的百分比来表示。
  • 引入版本:v3.1.0

rocksdb_max_write_buffer_memory_bytes

  • 默认值:1073741824
  • 类型:Int64
  • 单位:-
  • 是否动态:否
  • 描述:rocksdb中write buffer内存的最大上限。
  • 引入版本:v3.5.0

rocksdb_write_buffer_memory_percent

  • 默认值:5
  • 类型:Int64
  • 单位:-
  • 是否动态:否
  • 描述:rocksdb中write buffer可以使用的内存占比。默认值是百分之5,最终取值不会小于64MB,也不会大于1GB。
  • 引入版本:v3.5.0

其他

default_mv_resource_group_concurrency_limit

  • 默认值:0
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:物化视图刷新任务在单个 BE 上的并发上限。默认为 0,即不做并发数限制。已弃用:自 v3.4 起,FE 持久化 default_mv_wg 并下发给 BE,该参数不再生效。请使用 ALTER RESOURCE GROUP default_mv_wg WITH (...) 调整。
  • 引入版本:-

default_mv_resource_group_cpu_limit

  • 默认值:1
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:物化视图刷新任务占用单个 BE 的 CPU 核数上限。已弃用:自 v3.4 起,FE 持久化 default_mv_wg 并下发给 BE,该参数不再生效。请使用 ALTER RESOURCE GROUP default_mv_wg WITH (...) 调整。
  • 引入版本:-

default_mv_resource_group_memory_limit

  • 默认值:0.8
  • 类型:Double
  • 单位:
  • 是否动态:否
  • 描述:物化视图刷新任务占用单个 BE 内存上限,默认 80%。已弃用:自 v3.4 起,FE 持久化 default_mv_wg 并下发给 BE,该参数不再生效。请使用 ALTER RESOURCE GROUP default_mv_wg WITH (...) 调整。
  • 引入版本:v3.1

default_mv_resource_group_spill_mem_limit_threshold

  • 默认值:0.8
  • 类型:Double
  • 单位:
  • 是否动态:否
  • 描述:物化视图刷新任务触发落盘的内存占用阈值,默认80%。已弃用:自 v3.4 起,FE 持久化 default_mv_wg 并下发给 BE,该参数不再生效。请使用 ALTER RESOURCE GROUP default_mv_wg WITH (...) 调整。
  • 引入版本:v3.1

enable_resolve_hostname_to_ip_in_load_error_url

  • 默认值:false
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:error_urls Debug 过程中,是否允许 Operator 根据环境需求选择使用 FE 心跳的原始主机名,或强制解析为 IP 地址。
    • true:将主机名解析为 IP 地址。
    • false(默认):在错误 URL 中保留原始主机名。
  • 引入版本:v4.0.1

enable_retry_apply

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:启用后,被分类为可重试的 Tablet apply 失败(例如暂时的内存限制错误)会被重新调度以重试,而不是立即将 tablet 标记为错误。TabletUpdates 中的重试路径使用 retry_apply_interval_second 乘以当前失败计数并限制到 600s 的最大值来安排下一次尝试,因此随着连续失败,退避会增长。明确不可重试的错误(例如 corruption)会绕过重试并导致 apply 过程立即进入错误状态。重试会持续直到达到总体超时/终止条件,之后 apply 将进入错误状态。关闭此项会禁用对失败 apply 任务的自动重新调度,使失败的 apply 在没有重试的情况下直接转为错误状态。
  • 引入版本:v3.2.9

enable_token_check

  • 默认值:true
  • 类型:Boolean
  • 单位:-
  • 是否动态:是
  • 描述:是否开启 Token 检验。true 表示开启,false 表示不开启。
  • 引入版本:-

es_http_timeout_ms

  • 默认值:5000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:否
  • 描述:访问 Elasticsearch 的 HTTP 超时时长(毫秒)。在建立连接和发送请求时使用,超时会导致请求失败。
  • 引入版本:-

es_index_max_result_window

  • 默认值:10000
  • 类型:Int
  • 单位:-
  • 是否动态:否
  • 描述:Elasticsearch 索引的 max_result_window 限制,用于控制 Scroll/分页的最大返回窗口;超出将被 ES 拒绝。需要与 ES 端设置匹配。
  • 引入版本:-

es_scroll_keepalive

  • 默认值:5m
  • 类型:String
  • 单位:Minutes (string with suffix, e.g. "5m")
  • 是否动态:否
  • 描述:发送给 Elasticsearch 的 scroll 搜索上下文的 keep-alive 时长。该值在构建初始 scroll URL (?scroll=<value>) 以及发送后续 scroll 请求(通过 ESScrollQueryBuilder)时按字面使用(例如 "5m")。此设置控制 ES 端在垃圾回收前保留搜索上下文的时间;设置更长会让 scroll 上下文存活更久,但会延长 ES 集群的资源占用。该值在启动时由 ES scan reader 读取,运行时不可更改。
  • 引入版本:v3.2.0

load_replica_status_check_interval_ms_on_failure

  • 默认值:2000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:是
  • 描述:当上一次检查的 RPC 失败时,从副本向主副本检查其状态的时间间隔。
  • 引入版本:v3.5.1

load_replica_status_check_interval_ms_on_success

  • 默认值:15000
  • 类型:Int
  • 单位:Milliseconds
  • 是否动态:是
  • 描述:当上一次检查的 RPC 成功时,从副本向主副本检查其状态的时间间隔。
  • 引入版本:v3.5.1

max_length_for_bitmap_function

  • 默认值:1000000
  • 类型:Int
  • 单位:Bytes
  • 是否动态:否
  • 描述:bitmap 函数输入值的最大长度。
  • 引入版本:-

max_length_for_to_base64

  • 默认值:200000
  • 类型:Int
  • 单位:Bytes
  • 是否动态:否
  • 描述:to_base64() 函数输入值的最大长度。
  • 引入版本:-

memory_high_level

  • 默认值:75
  • 类型:Long
  • 单位:Percent
  • 是否动态:是
  • 描述:以进程内存上限的百分比表示的高水位内存阈值。当总内存消耗上升超过该百分比时,BE 开始逐步释放内存(目前通过驱逐 data cache 和 update cache,以及缩小存算分离的元数据缓存)以缓解压力。监控器使用此值来计算 memory_high = mem_limit * memory_high_level / 100,并且如果消耗大于 memory_high,则在 GC advisor 的指导下执行受控驱逐;如果消耗超过 memory_urgent_level(一个单独的配置),则会进行更激进的即时回收。此值还用于在超过阈值时禁用某些高内存消耗的操作(例如 primary-key preload)。必须满足与 memory_urgent_level 的校验关系(memory_urgent_level > memory_high_level,memory_high_level >= 1,memory_urgent_level <= 100)。
  • 引入版本:v3.2.0

memory_urgent_level

  • 默认值:90
  • 类型:Int
  • 单位:Percent
  • 是否动态:否
  • 描述:内存紧急阈值(占进程内存上限的百分比)。当消耗超过该值时会触发更激进的即时回收;需满足 memory_urgent_level > memory_high_level 且不超过 100。
  • 引入版本:-

report_exec_rpc_request_retry_num

  • 默认值:10
  • 类型:Int
  • 单位:-
  • 是否动态:是
  • 描述:用于向 FE 汇报执行状态的 RPC 请求的重试次数。默认值为 10,意味着如果该 RPC 请求失败(仅限于 fragment instance 的 finish RPC),将最多重试 10 次。该请求对于导入任务(load job)非常重要,如果某个 fragment instance 的完成状态报告失败,整个导入任务将会一直挂起,直到超时。
  • 引入版本:-

sleep_one_second

  • 默认值:1
  • 类型:Int
  • 单位:秒
  • 是否动态:否
  • 描述:BE Agent Worker 线程的全局短睡眠间隔,当 Master 地址/心跳尚不可用或需要短时间重试/退避时作为一秒的暂停。多个 Report Worker Pool(例如 ReportDiskStateTaskWorkerPool、ReportOlapTableTaskWorkerPool、ReportWorkgroupTaskWorkerPool)引用此值,以避免忙等(busy-waiting)并在重试时降低 CPU 消耗。增大此值会降低重试频率并减慢对 Master 可用性的响应;减小会提高轮询频率并增加 CPU 使用。请在权衡响应性与资源使用后调整该项。
  • 引入版本:v3.2.0

small_file_dir

  • 默认值:${STARROCKS_HOME}/lib/small_file/
  • 类型:String
  • 单位:-
  • 是否动态:否
  • 描述:保存文件管理器下载的文件的目录。
  • 引入版本:-

upload_buffer_size

  • 默认值:4194304
  • 类型:Int
  • 单位:Bytes
  • 是否动态:是
  • 描述:上传快照文件到远端存储时的缓冲区大小(fs::copy 读写块大小)。值越大传输吞吐越高但每个并发上传占用更多内存;可与 upload_worker_count 一起调优。
  • 引入版本:v3.2.13

user_function_dir

  • 默认值:${STARROCKS_HOME}/lib/udf
  • 类型:String
  • 单位:-
  • 是否动态:否
  • 描述:UDF 存放的路径。
  • 引入版本:-

web_log_bytes

  • 默认值:1048576 (1 MB)
  • 类型:long
  • 单位:Bytes
  • 是否动态:否
  • 描述:从 INFO 日志文件读取并在 BE 调试 Web Server 的日志页面上显示的最大字节数。该处理器使用此值计算一个 seek 偏移量(显示最后 N 字节),以避免读取或提供非常大的日志文件。如果日志文件小于该值则显示整个文件。注意:在当前实现中,用于读取并服务 INFO 日志的代码被注释掉了,处理器会报告无法打开 INFO 日志文件,因此除非启用日志服务代码,否则此参数可能无效。
  • 引入版本:v3.2.0

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

资料来源与适用范围

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

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

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