跳到主要内容
版本：Latest-4.1

FE 配置 - 统计报告和存储

FE 参数分为动态参数和静态参数。

  • 动态参数可通过 SQL 命令进行在线配置和调整，方便快捷。需要注意通过 SQL 命令所做的动态设置在重启 FE 后会失效。如果想让设置长期生效，建议同时修改 fe.conf 文件。

  • 静态参数必须在 FE 配置文件 fe.conf 中进行配置和调整。调整完成后，需要重启 FE 使变更生效。

参数是否为动态参数可通过 ADMIN SHOW CONFIG 返回结果中的 IsMutable 列查看。TRUE 表示动态参数。

静态和动态参数均可通过 fe.conf 文件进行修改。

查看 FE 配置项​

FE 启动后，您可以在 MySQL 客户端运行 ADMIN SHOW FRONTEND CONFIG 命令查看参数配置。如果要查询特定参数的配置，请运行以下命令：

ADMIN SHOW FRONTEND CONFIG [LIKE "pattern"];

有关返回字段的详细说明，请参阅 ADMIN SHOW CONFIG。

备注

您必须具有管理员权限才能运行集群管理相关命令。

配置 FE 参数​

配置 FE 动态参数​

您可以使用 ADMIN SET FRONTEND CONFIG 命令配置或修改 FE 动态参数。

ADMIN SET FRONTEND CONFIG ("key" = "value");
备注

动态设置的配置项，在 FE 重启之后会恢复成 fe.conf 文件中的配置或者默认值。如果需要让配置长期生效，建议设置完之后同时修改 fe.conf 文件，防止重启后修改失效。

配置 FE 静态参数​

备注

FE 静态参数不支持在线修改，您需要在 fe.conf 中修改并重启 FE 以使修改生效。

当前主题包含以下类型的 FE 配置：

统计报告​

enable_collect_warehouse_metrics​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 当此项设置为 true 时，系统将收集并导出每个仓库的指标。启用它会将仓库级别的指标（槽位/使用率/可用性）添加到指标输出中，并增加指标基数和收集开销。禁用它可省略仓库特定指标，并减少 CPU/网络和监控存储成本。
  • 引入版本: v3.5.0

enable_http_detail_metrics​

  • 默认值: false
  • 类型: boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 当为 true 时，HTTP 服务器计算并暴露详细的 HTTP worker 指标（特别是 HTTP_WORKER_PENDING_TASKS_NUM gauge）。启用此功能会导致服务器迭代 Netty worker 执行器并调用每个 NioEventLoop 上的 pendingTasks() 以汇总待处理任务计数；禁用时，gauge 返回 0 以避免此成本。这种额外的收集可能会耗费 CPU 和延迟 — 仅在调试或详细调查时启用。
  • 引入版本: v3.2.3

proc_profile_collect_time_s​

  • 默认值: 120
  • 类型: Int
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 单次进程 profile 收集的持续时间（秒）。当 proc_profile_cpu_enable 或 proc_profile_mem_enable 设置为 true 时，AsyncProfiler 启动，收集器线程休眠此持续时间，然后 profiler 停止并写入 profile。较大的值会增加样本覆盖率和文件大小，但会延长 profiler 运行时并延迟后续收集；较小的值会减少开销，但可能会产生不足的样本。确保此值与 proc_profile_file_retained_days 和 proc_profile_file_retained_size_bytes 等保留设置对齐。
  • 引入版本: v3.2.12

enable_dict_thrash_guard​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否启用全局字典抖动守卫（thrash guard）。对于"滚动"低基数列——其瞬时不同值数量始终低于字典阈值，但取值集合持续轮换（例如按天分区、每天导入新值的列）——不会触发基数黑名单，但每次导入都会引入当前全局字典中缺失的值并使其失效。每次失效都会触发一次全表字典重采集，浪费 IO，并在存算分离集群中严重争用 segment 元数据缓存锁。启用该守卫后，StarRocks 会统计每个列的字典在 dict_thrash_guard_window_sec 时间窗口内的失效次数；当某列达到 dict_thrash_guard_threshold 次失效时，StarRocks 会禁止采集该列的全局字典。该禁用立即生效，并作为表的 no_dict_columns 属性持久化，因此能在 FE 重启和 Leader 切换后保留。如需重新启用某列的字典采集，执行 ALTER TABLE ... ENABLE DICTIONARY (column)。
  • 引入版本: v4.2.0

dict_thrash_guard_window_sec​

  • 默认值: 60
  • 类型: Int
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 全局字典抖动守卫统计某列字典失效次数所用的时间窗口长度（秒）。仅当 enable_dict_thrash_guard 为 true 时生效。
  • 引入版本: v4.2.0

dict_thrash_guard_threshold​

  • 默认值: 5
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 在 dict_thrash_guard_window_sec 时间窗口内，触发全局字典抖动守卫禁止采集某列全局字典的失效次数阈值。设置为 0 可在保持守卫启用的同时禁用次数检查（不会自动禁用任何列）。仅当 enable_dict_thrash_guard 为 true 时生效。
  • 引入版本: v4.2.0

enable_external_predicate_columns_collection​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否在查询优化过程中记录外部表（非原生表）的谓词列使用情况（WHERE/JOIN/GROUP BY 中用到的列）。StarRocks 利用这些使用信息缩小宽外部表 ANALYZE 时需要收集统计信息的列范围。禁用后不再记录外部表的谓词列，ANALYZE 会回退为收集所有列的统计信息。
  • 引入版本: v4.2.0

statistic_external_predicate_columns_ttl_hours​

  • 默认值: 168
  • 类型: Long
  • 单位: 小时
  • 是否可变: Yes
  • 描述: 记录的外部表谓词列使用信息的存活时间（TTL）。last_used 时间早于该值的记录会被周期性的 vacuum 任务清除。设置为负值（例如 -1）可禁用 vacuum。默认值为一周，因为外部表 ANALYZE 的执行频率远低于内表，如果 TTL 太短（如内表默认的 24 小时），会导致两次收集之间使用信息被提前清除。
  • 引入版本: v4.2.0

statistic_external_predicate_columns_cache_ttl_sec​

  • 默认值: 300
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 用于响应外部表谓词列查询（例如自动 ANALYZE 选列时）的内存缓存的 TTL。值越小，新记录的使用信息越快可见，但会增加对底层存储表的查询压力；值越大则降低该压力，但会增加数据的陈旧程度。
  • 引入版本: v4.2.0

enable_temporary_table_statistic_collect​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 采集作业是否为临时表收集统计信息。该项作用于根据采集作业定义构建的收集任务，即自动采集作业以及通过 CREATE ANALYZE 创建的作业。设置为 false 时，构建这些作业时会跳过临时表，仅对非临时表进行采集。单次执行的 ANALYZE TABLE 语句不受该项影响，仍会为临时表收集统计信息。当生命周期很短的临时表带来的采集开销超过其统计信息的价值时，可将该项设置为 false。
  • 引入版本: v3.4.0

存储​

allow_implicit_key_column_in_agg_add_column​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 在聚合表上执行 ALTER TABLE ... ADD COLUMN 时，如果新列既未指定聚合函数，也未指定 KEY 关键字，是否允许将该列创建为 Key 列。此类语句存在歧义，并且创建 Key 列会改变表的聚合键并重写已有数据。设置为 true 时，该列会被创建为 Key 列，与早期版本的行为一致。设置为 false 时，该语句会被拒绝，报错信息会同时说明两种写法。该参数可动态修改，但除非使用 WITH PERSISTENT 设置，否则重启后不会保留。
  • 引入版本: v4.1.5

alter_table_timeout_second​

  • 默认值: 86400
  • 类型: Int
  • 单位: 秒
  • 是否可变: Yes
  • 描述: schema 变更操作 (ALTER TABLE) 的超时时长。
  • 引入版本: -

capacity_used_percent_high_water​

  • 默认值: 0.75
  • 类型: double
  • 单位: 分数 (0.0–1.0)
  • 是否可变: Yes
  • 描述: 计算后端负载分数时使用的磁盘容量使用百分比（总容量的百分比）的高水位阈值。BackendLoadStatistic.calcSore 使用 capacity_used_percent_high_water 设置 LoadScore.capacityCoefficient：如果后端的使用百分比小于 0.5，则系数等于 0.5；如果使用百分比 > capacity_used_percent_high_water，则系数 = 1.0；否则，系数通过 (2 * usedPercent - 0.5) 随使用百分比线性变化。当系数为 1.0 时，负载分数完全由容量比例决定；较低的值会增加副本计数的权重。调整此值会改变平衡器惩罚磁盘利用率高的后端的积极程度。
  • 引入版本: v3.2.0

catalog_trash_expire_second​

  • 默认值: 86400
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 数据库、表或分区删除后，元数据可保留的最长时间。如果此持续时间过期，数据将被删除，并且无法通过 RECOVER 命令恢复。
  • 引入版本: -

catalog_recycle_bin_erase_min_latency_ms​

  • 默认值: 600000
  • 类型: Long
  • 单位: 毫秒
  • 是否可变: Yes
  • 描述: 数据库、表或分区被删除后，擦除元数据前的最小延迟时间（毫秒）。用于避免擦除日志先于删除日志写入。
  • 引入版本: -

catalog_recycle_bin_erase_max_operations_per_cycle​

  • 默认值: 500
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 每个周期内从回收站中实际删除数据库、表或分区的最大擦除操作数。擦除操作会持有锁，因此单批次不宜过大。
  • 引入版本: -

catalog_recycle_bin_erase_fail_retry_interval_ms​

  • 默认值: 60000
  • 类型: Long
  • 单位: 毫秒
  • 是否可变: Yes
  • 描述: 回收站擦除操作失败后的重试间隔时间（毫秒）。
  • 引入版本: -

check_consistency_default_timeout_second​

  • 默认值: 600
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 副本一致性检查的超时时长。您可以根据 tablet 的大小设置此参数。
  • 引入版本: -

consistency_check_cooldown_time_second​

  • 默认值: 24 * 3600
  • 类型: Int
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 控制同一 tablet 两次一致性检查之间的最小间隔（以秒为单位）。在 tablet 选择期间，只有当 tablet.getLastCheckTime() 小于 (currentTimeMillis - consistency_check_cooldown_time_second * 1000) 时，tablet 才被视为符合条件。默认值 (24 * 3600) 强制每个 tablet 大约每天检查一次，以减少后端磁盘 I/O。降低此值会增加检查频率和资源使用；提高此值会以更慢地检测不一致为代价减少 I/O。该值在从索引的 tablet 列表中过滤冷却的 tablet 时全局应用。
  • 引入版本: v3.5.5

consistency_check_end_time​

  • 默认值: "4"
  • 类型: String
  • 单位: 一天中的小时 (0-23)
  • 是否可变: No
  • 描述: 指定 ConsistencyChecker 工作窗口的结束小时（一天中的小时）。该值使用 SimpleDateFormat("HH") 在系统时区中解析，并接受 0-23（一位或两位数）。StarRocks 将其与 consistency_check_start_time 一起使用，以决定何时调度和添加一致性检查作业。当 consistency_check_start_time 大于 consistency_check_end_time 时，窗口跨越午夜（例如，默认 consistency_check_start_time = "23" 到 consistency_check_end_time = "4"）。当 consistency_check_start_time 等于 consistency_check_end_time 时，检查器从不运行。解析失败将导致 FE 启动记录错误并退出，因此请提供有效的小时字符串。
  • 引入版本: v3.2.0

consistency_check_start_time​

  • 默认值: "23"
  • 类型: String
  • 单位: 一天中的小时 (00-23)
  • 是否可变: No
  • 描述: 指定 ConsistencyChecker 工作窗口的开始小时（一天中的小时）。该值使用 SimpleDateFormat("HH") 在系统时区中解析，并接受 0-23（一位或两位数）。StarRocks 将其与 consistency_check_end_time 一起使用，以决定何时调度和添加一致性检查作业。当 consistency_check_start_time 大于 consistency_check_end_time 时，窗口跨越午夜（例如，默认 consistency_check_start_time = "23" 到 consistency_check_end_time = "4"）。当 consistency_check_start_time 等于 consistency_check_end_time 时，检查器从不运行。解析失败将导致 FE 启动记录错误并退出，因此请提供有效的小时字符串。
  • 引入版本: v3.2.0

consistency_tablet_meta_check_interval_ms​

  • 默认值: 2 * 3600 * 1000
  • 类型: Int
  • 单位: 毫秒
  • 是否可变: Yes
  • 描述: ConsistencyChecker 用于在 TabletInvertedIndex 和 LocalMetastore 之间运行完整 tablet 元数据一致性扫描的间隔。runAfterCatalogReady 中的守护程序在 current time - lastTabletMetaCheckTime 超过此值时触发 checkTabletMetaConsistency。当首次检测到无效 tablet 时，其 toBeCleanedTime 设置为 now + (consistency_tablet_meta_check_interval_ms / 2)，因此实际删除会延迟到后续扫描。增加此值可减少扫描频率和负载（清理较慢）；减少此值可更快检测和删除陈旧 tablet（开销较高）。
  • 引入版本: v3.2.0

default_replication_num​

  • 默认值: 3
  • 类型: Short
  • 单位: -
  • 是否可变: Yes
  • 描述: 设置在 StarRocks 中创建表时每个数据分区的默认副本数。此设置可以在创建表时通过在 CREATE TABLE DDL 中指定 replication_num=x 来覆盖。
  • 引入版本: -

enable_auto_tablet_distribution​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否自动设置 bucket 数量。
    • 如果此参数设置为 TRUE，您在创建表或添加分区时无需指定 bucket 数量。StarRocks 会自动确定 bucket 数量。
    • 如果此参数设置为 FALSE，您在创建表或添加分区时需要手动指定 bucket 数量。如果您在向表添加新分区时不指定 bucket 数量，新分区将继承表创建时设置的 bucket 数量。但是，您也可以手动为新分区指定 bucket 数量。
  • 引入版本: v2.5.7

enable_experimental_rowstore​

  • 默认值: false
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否启用混合行存和列存功能。
  • 引入版本: v3.2.3

enable_fast_schema_evolution​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否为 StarRocks 集群中的所有表启用 Fast Schema Evolution。有效值为 TRUE 和 FALSE（默认）。启用 Fast Schema Evolution 可以提高 schema 变更的速度，并在添加或删除列时减少资源使用。
  • 引入版本: v3.2.0

NOTE

  • StarRocks 存算分离集群从 v3.3.0 开始支持此参数。
  • 如果您需要为特定表配置 Fast Schema Evolution，例如禁用特定表的 Fast Schema Evolution，您可以在表创建时设置表属性 fast_schema_evolution。

enable_online_optimize_table​

  • 默认值: false
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 控制 StarRocks 在创建优化作业时是否使用非阻塞在线优化路径。当 enable_online_optimize_table 为 true 且目标表满足兼容性检查（无分区/键/排序规范，分布不是 RandomDistributionDesc，存储类型不是 COLUMN_WITH_ROW，已启用复制存储，且该表不是云原生表或物化视图）时，规划器会创建一个 OnlineOptimizeJobV2 以在不阻塞写入的情况下执行优化。如果为 false 或任何兼容性条件失败，StarRocks 将回退到 OptimizeJobV2，这可能会在优化期间阻塞写入操作。
  • 引入版本: v3.3.3, v3.4.0, v3.5.0

enable_strict_storage_medium_check​

  • 默认值: false
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: FE 在用户创建表时是否严格检查 BE 的存储介质。如果此参数设置为 TRUE，FE 会在用户创建表时检查 BE 的存储介质，如果 BE 的存储介质与 CREATE TABLE 语句中指定的 storage_medium 参数不同，则返回错误。例如，CREATE TABLE 语句中指定的存储介质是 SSD，但 BE 的实际存储介质是 HDD。因此，表创建失败。如果此参数为 FALSE，FE 在用户创建表时不会检查 BE 的存储介质。
  • 引入版本: -

max_bucket_number_per_partition​

  • 默认值: 1024
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 一个分区中可以创建的最大 bucket 数量。
  • 引入版本: v3.3.2

max_column_number_per_table​

  • 默认值: 10000
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 一个表中可以创建的最大列数。
  • 引入版本: v3.3.2

max_dynamic_partition_num​

  • 默认值: 500
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 限制分析或创建动态分区表时可一次性创建的最大分区数。在动态分区属性验证期间，systemtask_runs_max_history_number 计算预期分区（结束偏移量 + 历史分区号），如果总数超过 max_dynamic_partition_num，则抛出 DDL 错误。仅当您预期合法的大分区范围时才增加此值；增加它允许创建更多分区，但会增加元数据大小、调度工作和操作复杂性。
  • 引入版本: v3.2.0

max_partition_number_per_table​

  • 默认值: 100000
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 一个表中可以创建的最大分区数。
  • 引入版本: v3.3.2

max_task_consecutive_fail_count​

  • 默认值: 10
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 任务在调度器自动暂停它之前可能连续失败的最大次数。当 TaskSource.MV.equals(task.getSource()) 且 max_task_consecutive_fail_count 大于 0 时，如果任务的连续失败计数达到或超过 max_task_consecutive_fail_count，任务将通过 TaskManager 暂停，并且对于物化视图任务，物化视图将失效。抛出异常，指示暂停以及如何重新激活（例如，ALTER MATERIALIZED VIEW <mv_name> ACTIVE）。将此项设置为 0 或负值以禁用自动暂停。
  • 引入版本: -

partition_recycle_retention_period_secs​

  • 默认值: 1800
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: INSERT OVERWRITE 或物化视图刷新操作删除的分区的元数据保留时间。请注意，此类元数据无法通过执行 RECOVER 恢复。
  • 引入版本: v3.5.9

recover_with_empty_tablet​

  • 默认值: false
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否用空的 tablet 替换丢失或损坏的 tablet 副本。如果 tablet 副本丢失或损坏，对此 tablet 或其他健康 tablet 的数据查询可能会失败。用空的 tablet 替换丢失或损坏的 tablet 副本可确保查询仍能执行。但是，由于数据丢失，结果可能不正确。默认值为 FALSE，这意味着丢失或损坏的 tablet 副本不会被空的副本替换，并且查询失败。
  • 引入版本: -

storage_usage_hard_limit_percent​

  • 默认值: 95
  • 别名: storage_flood_stage_usage_percent
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: BE 目录中存储使用率的硬限制（百分比）。如果 BE 存储目录的存储使用率（百分比）超过此值，并且剩余存储空间小于 storage_usage_hard_limit_reserve_bytes，则加载和恢复作业将被拒绝。您需要将此项与 BE 配置项 storage_flood_stage_usage_percent 一起设置，以使配置生效。
  • 引入版本: -

storage_usage_hard_limit_reserve_bytes​

  • 默认值: 100 * 1024 * 1024 * 1024
  • 别名: storage_flood_stage_left_capacity_bytes
  • 类型: Long
  • 单位: 字节
  • 是否可变: Yes
  • 描述: BE 目录中剩余存储空间的硬限制。如果 BE 存储目录中剩余存储空间小于此值，并且存储使用率（百分比）超过 storage_usage_hard_limit_percent，则加载和恢复作业将被拒绝。您需要将此项与 BE 配置项 storage_flood_stage_left_capacity_bytes 一起设置，以使配置生效。
  • 引入版本: -

storage_usage_soft_limit_percent​

  • 默认值: 90
  • 别名: storage_high_watermark_usage_percent
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: BE 目录中存储使用率的软限制（百分比）。如果 BE 存储目录的存储使用率（百分比）超过此值，并且剩余存储空间小于 storage_usage_soft_limit_reserve_bytes，则 tablet 无法克隆到此目录。
  • 引入版本: -

storage_usage_soft_limit_reserve_bytes​

  • 默认值: 200 * 1024 * 1024 * 1024
  • 别名: storage_min_left_capacity_bytes
  • 类型: Long
  • 单位: 字节
  • 是否可变: Yes
  • 描述: BE 目录中剩余存储空间的软限制。如果 BE 存储目录中剩余存储空间小于此值，并且存储使用率（百分比）超过 storage_usage_soft_limit_percent，则 tablet 无法克隆到此目录。
  • 引入版本: -

tablet_checker_lock_time_per_cycle_ms​

  • 默认值: 1000
  • 类型: Int
  • 单位: 毫秒
  • 是否可变: Yes
  • 描述: tablet 检查器在释放并重新获取表锁之前，每个周期最大锁持有时间。小于 100 的值将被视为 100。
  • 引入版本: v3.5.9, v4.0.2

tablet_create_timeout_second​

  • 默认值: 10
  • 类型: Int
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 创建 tablet 的超时时长。从 v3.1 开始，默认值从 1 更改为 10。
  • 引入版本: -

tablet_delete_timeout_second​

  • 默认值: 2
  • 类型: Int
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 删除 tablet 的超时时长。
  • 引入版本: -

tablet_sched_balance_load_disk_safe_threshold​

  • 默认值: 0.5
  • 别名: balance_load_disk_safe_threshold
  • 类型: Double
  • 单位: -
  • 是否可变: Yes
  • 描述: 用于判断 BE 磁盘使用率是否平衡的百分比阈值。如果所有 BE 的磁盘使用率都低于此值，则认为平衡。如果磁盘使用率大于此值，并且最高和最低 BE 磁盘使用率之间的差异大于 10%，则认为磁盘使用率不平衡，并触发 tablet 重新平衡。
  • 引入版本: -

tablet_sched_balance_load_score_threshold​

  • 默认值: 0.1
  • 别名: balance_load_score_threshold
  • 类型: Double
  • 单位: -
  • 是否可变: Yes
  • 描述: 用于判断 BE 负载是否平衡的百分比阈值。如果 BE 的负载低于所有 BE 的平均负载，并且差异大于此值，则此 BE 处于低负载状态。相反，如果 BE 的负载高于平均负载，并且差异大于此值，则此 BE 处于高负载状态。
  • 引入版本: -

tablet_sched_be_down_tolerate_time_s​

  • 默认值: 900
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 调度器允许 BE 节点保持非活动状态的最大持续时间。达到时间阈值后，该 BE 节点上的 tablet 将迁移到其他活动 BE 节点。
  • 引入版本: v2.5.7

tablet_sched_disable_balance​

  • 默认值: false
  • 别名: disable_balance
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否禁用 tablet 平衡。TRUE 表示禁用 tablet 平衡。FALSE 表示启用 tablet 平衡。
  • 引入版本: -

tablet_sched_disable_colocate_balance​

  • 默认值: false
  • 别名: disable_colocate_balance
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否禁用 Colocate 表的副本平衡。TRUE 表示禁用副本平衡。FALSE 表示启用副本平衡。
  • 引入版本: -

tablet_sched_max_balancing_tablets​

  • 默认值: 500
  • 别名: max_balancing_tablets
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 可同时平衡的最大 tablet 数量。如果超过此值，将跳过 tablet 重新平衡。
  • 引入版本: -

tablet_sched_max_clone_task_timeout_sec​

  • 默认值: 2 * 60 * 60
  • 别名: max_clone_task_timeout_sec
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 克隆 tablet 的最大超时时长。
  • 引入版本: -

tablet_sched_max_not_being_scheduled_interval_ms​

  • 默认值: 15 * 60 * 1000
  • 类型: Long
  • 单位: 毫秒
  • 是否可变: Yes
  • 描述: 当 tablet 克隆任务正在调度时，如果 tablet 在此参数指定的时间内未被调度，StarRocks 会给予其更高的优先级，以便尽快调度。
  • 引入版本: -

tablet_sched_max_scheduling_tablets​

  • 默认值: 10000
  • 别名: max_scheduling_tablets
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 可同时调度的最大 tablet 数量。如果超过此值，将跳过 tablet 平衡和修复检查。
  • 引入版本: -

tablet_sched_min_clone_task_timeout_sec​

  • 默认值: 3 * 60
  • 别名: min_clone_task_timeout_sec
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 克隆 tablet 的最小超时时长。
  • 引入版本: -

tablet_sched_num_based_balance_threshold_ratio​

  • 默认值: 0.5
  • 别名: -
  • 类型: Double
  • 单位: -
  • 是否可变: Yes
  • 描述: 基于数量的平衡可能会破坏磁盘大小平衡，但磁盘之间的最大差距不能超过 tablet_sched_num_based_balance_threshold_ratio * tablet_sched_balance_load_score_threshold。如果集群中有 tablet 不断从 A 平衡到 B，又从 B 平衡到 A，请减小此值。如果您希望 tablet 分布更平衡，请增加此值。
  • 引入版本: - 3.1

tablet_sched_repair_delay_factor_second​

  • 默认值: 60
  • 别名: tablet_repair_delay_factor_second
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 副本修复的间隔，单位为秒。
  • 引入版本: -

tablet_sched_slot_num_per_path​

  • 默认值: 8
  • 别名: schedule_slot_num_per_path
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 单个 BE 存储目录中可并发运行的 tablet 相关任务的最大数量。从 v2.5 开始，此参数的默认值从 4 更改为 8。
  • 引入版本: -

tablet_sched_storage_cooldown_second​

  • 默认值: -1
  • 别名: storage_cooldown_second
  • 类型: Long
  • 单位: 秒
  • 是否可变: Yes
  • 描述: 从表创建时间开始的自动冷却延迟。默认值 -1 表示禁用自动冷却。如果需要启用自动冷却，请将此参数设置为大于 -1 的值。
  • 引入版本: -

tablet_stat_update_interval_second​

  • 默认值: 300
  • 类型: Int
  • 单位: 秒
  • 是否可变: No
  • 描述: FE 从每个 BE 获取 tablet 统计信息的时间间隔。
  • 引入版本: -

enable_range_distribution​

  • 默认值: false
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否为建表启用 Range-based Distribution 语意。
  • 引入版本: v4.1.0

tablet_reshard_max_parallel_tablets​

  • 默认值: 10240
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 可并行拆分或合并的 Tablet 最大数量。
  • 引入版本: v4.1.0

tablet_reshard_target_size​

  • 默认值: 10737418240 (10 GB)
  • 类型: Int
  • 单位: Bytes
  • 是否可变: Yes
  • 描述: 执行 SPLIT 或 MERGE 操作后，Tablet 的目标大小。
  • 引入版本: v4.1.0

tablet_reshard_max_split_count​

  • 默认值: 1024
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 旧 Tablet 最多可分割成多少个新 Tablet。
  • 引入版本: v4.1.0

tablet_reshard_min_split_size​

  • 默认值: 2147483648 (2 GB)
  • 类型: Long
  • 单位: Bytes
  • 是否可变: Yes
  • 描述: Tablet 预分裂（pre-split）产生的 Tablet 的最小大小。该参数用于约束预分裂时按计算节点数对齐的行为，避免在节点较多的集群上将数据量较小的导入分裂成大量过小的 Tablet。其值不应大于 tablet_reshard_target_size。
  • 引入版本: v4.1.0

tablet_reshard_history_job_max_keep_ms​

  • 默认值: 259200000 (72 hours)
  • 类型: Int
  • 单位: Milliseconds
  • 是否可变: Yes
  • 描述: SPLIT/MERGE 批处理作业历史的最大保留时间。
  • 引入版本: v4.1.0

tablet_reshard_colocate_checker_membership_batch_size​

  • 默认值: 1000
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 存算分离集群下，Range Colocate 检查器在单次 getShardInfo 成员关系读取批量 RPC 中发送给 StarOS 的最大 Tablet 数量。小于 1 的值按 1 处理。
  • 引入版本: v4.1.3

tablet_reshard_colocate_checker_convergence_batch_size​

  • 默认值: 64
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: Range Colocate 检查器在单次 queryShardGroupStable 放置收敛批量 RPC 中发送给 StarOS 的最大 PACK Shard Group 数量。每个 Group 的稳定性检查在服务端计算，因此较小的批量可以限制单次 RPC 的延迟，完整结果通过多次调用累积得到。小于 1 的值按 1 处理。
  • 引入版本: v4.1.3

tablet_reshard_colocate_checker_convergence_cache_ttl_ms​

  • 默认值: 1000
  • 类型: Long
  • 单位: Milliseconds
  • 是否可变: Yes
  • 描述: Range Colocate 检查器放置收敛负缓存的 TTL。在该时间窗口内，StarOS 上次报告为尚未收敛的 PACK Shard Group 不会被重新查询，从而在该 Group 仍在迁移期间降低每轮 queryShardGroupStable 的负载。仅缓存未收敛的结果，因此过期条目最多只会将该 Group 转为稳定状态的时间延迟一个时间窗口，而不会导致提前转为稳定。小于或等于 0 的值将禁用该缓存。
  • 引入版本: v4.1.3

enable_tablet_pre_split_for_insert_from_files​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否为 INSERT INTO ... SELECT FROM FILES() 导入启用基于采样的 Tablet 预分裂（Sample-Based Tablet Pre-Split）。v4.1.0 起 GA 默认开启。如需在集群范围关闭，设置为 false。会话变量 enable_tablet_pre_split 也必须为 true 时预分裂才会运行。
  • 引入版本: v4.1.0

enable_tablet_pre_split_for_broker_load​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否为 Broker Load 启用基于采样的 Tablet 预分裂。v4.1.0 起 GA 默认开启。如需在集群范围关闭，设置为 false。会话变量 enable_tablet_pre_split 也必须为 true 时预分裂才会运行。
  • 引入版本: v4.1.0

enable_tablet_pre_split_for_insert_from_table​

  • 默认值: true
  • 类型: Boolean
  • 单位: -
  • 是否可变: Yes
  • 描述: 是否为源表是内部 OLAP 表或外部 Iceberg 表的 INSERT INTO ... SELECT FROM <table> 导入启用基于采样的 Tablet 预分裂。该功能支持自动 Range 分区目标，包括显式指定的正式分区或临时分区，以及 static 和 dynamic 两种 INSERT OVERWRITE。v4.1.0 起 GA 默认开启。如需在集群范围关闭，设置为 false。会话变量 enable_tablet_pre_split 也必须为 true 时预分裂才会运行。如需回滚，将其设为 false，新的 INSERT-from-table 导入将立即跳过预分裂。
  • 引入版本: v4.1.0

tablet_pre_split_pre_submit_timeout_seconds​

  • 默认值: 300
  • 类型: Long
  • 单位: Seconds
  • 是否可变: Yes
  • 描述: 基于采样的 Tablet 预分裂的「提交前阶段」墙钟时间预算（采样 + 规划边界 + 构建 reshard 作业）。超时后协调器跳过预分裂，导入沿用原始单 Tablet 路径继续执行。默认 300 秒：数据层采样器在大数据集／慢对象存储上可能耗时数十秒（测试中一个 ~40GB 多文件 Parquet 导入采样耗时约 78 秒），且该预算主要影响大导入 —— 而大导入恰恰是预分裂最受益的场景；小导入无论如何都在一秒内完成采样。采样期间导入最多停留 PENDING 此时长，因此应将其设置为小于导入自身的超时时间。
  • 引入版本: v4.1.0

tablet_pre_split_post_submit_wait_seconds​

  • 默认值: 300
  • 类型: Long
  • 单位: Seconds
  • 是否可变: Yes
  • 描述: 基于采样的 Tablet 预分裂协调器等待已提交 reshard 作业到达 FINISHED 的最长时间。INSERT-from-FILES 与 Broker Load 均同步等待，超时后 不中止地继续执行 —— 导入随后按当时可见的 Tablet 布局做计划（守护线程还未推进则仍为原单 tablet 布局；若守护线程在我们放弃等待之后才完成则可能已部分／完全分裂）；tablet_pre_split_post_submit_hard_cap 计数器记录超时事件。测试使用的严格 runPreSplit 包装路径在超时后抛出 PreSplitPostSubmitTimeoutException 中止调用方的导入。Broker Load 路径上，等待发生在 broker pending task 解析完文件列表之后、beginTxn 打开 T_load 之前 —— 每个表最多占用一个 pending_load_task_scheduler 线程达此秒数，当大量并发 Broker Load 命中可预分裂的目标表时，请相应调整 max_broker_load_job_concurrency。运维提示： 等待期间该 Broker Load 在 SHOW LOAD 中仍显示为 PENDING，且仍受 Load 自身 timeoutSecond 约束 —— 应将该值设置为远小于常规 Broker Load 超时时间的最小值。
  • 引入版本: v4.1.0

tablet_pre_split_sample_byte_limit​

  • 默认值: 16777216 (16 MiB)
  • 类型: Long
  • 单位: Bytes
  • 是否可变: Yes
  • 描述: 基于采样的 Tablet 预分裂 data-tier 储水池采样器在 FE 端累积缓冲的软字节上限。累积值超过该上限后采样器停止读取。首行始终被接纳，超大单行仍会产生非空样本。
  • 引入版本: v4.1.0

tablet_pre_split_meta_tier_overlap_threshold​

  • 默认值: 0.3
  • 类型: Double
  • 单位: -
  • 是否可变: Yes
  • 描述: 基于采样的 Tablet 预分裂 meta tier（Parquet/ORC row-group 元数据）计算边界时容忍的最大重叠率。超过该阈值时按最小值排序的累计行数将不再单调，meta tier 会回退到 data tier（行采样）。
  • 引入版本: v4.1.0

tablet_pre_split_max_partitions_per_load​

  • 默认值: 32
  • 类型: Int
  • 单位: -
  • 是否可变: Yes
  • 描述: 单次基于采样的 Tablet 预分裂调用处理的预测目标分区数上限。超出该上限的预测分区（样本数最少的那部分）会被丢弃，回退到 BE 运行时自动建分区且不做预分裂。用于约束病态多分区导入下钩子的耗时。设为 0 或负值可关闭该上限。
  • 引入版本: v4.1.0

tablet_pre_split_target_size​

  • 默认值: 0
  • 类型: Long
  • 单位: Bytes
  • 是否可变: Yes
  • 描述: 基于采样的 Tablet 预分裂计算分裂数量时使用的目标 Tablet 大小。默认值 0 表示沿用 tablet_reshard_target_size。调小该值可以让单次导入获得更高的写并行度，同时不会缩小集群中其他 Tablet：后台 Tablet 分裂/合并守护线程仍然按 tablet_reshard_target_size 判定，会在导入结束后把这些较小的 Tablet 重新合并回去。该配置对写入全新 Range 分布分区的导入最为关键（例如 INSERT OVERWRITE 的替换分区），这类分区初始只有一个覆盖全域的 Tablet，否则只能由单个 BE 节点写入。

回滚基于采样的 Tablet 预分裂​

降级或线上回滚前安全关闭该特性的步骤：

  1. 将三个预分裂开关同时设为 false：enable_tablet_pre_split_for_insert_from_files、enable_tablet_pre_split_for_broker_load 和 enable_tablet_pre_split_for_insert_from_table。新导入将立即跳过预分裂。
  2. 等待预分裂创建的在途 reshard 作业排空。用 SHOW TABLET RESHARD JOB 监控；当没有 RUNNING 或 PENDING 行后回滚完成。
  3. 继续降级流程。底层基础设施（External-Boundaries Tablet Split）与预分裂特性开关解耦，无论开关如何都可用。

多分区基于采样的 Tablet 预分裂行为说明（P2-a）​

多分区路径将基于采样的 Tablet 预分裂扩展到单条语句命中多个分区的导入场景。两条运维注意事项：

  • Broker Load 触发载入不对称。 多分区预分裂钩子在 BrokerLoadJob.createLoadingTask 中触发，晚于 task.prepare() 构建该次导入的 sink plan（plan 基于当时的 catalog 状态）。因此 Broker Load 路径下，预建分区和分裂后的 tablet 布局只对后续针对同一张表的导入可见 —— 触发本次预分裂的 Broker Load 自身仍按原布局运行，命中的分区走 BE 运行时自动建分区。INSERT-from-FILES 钩子在 StatementPlanner.plan() 之前触发，因此触发本次预分裂的 INSERT 本身就能受益。
  • 后续 INSERT 失败时的空分区残留。 当预建成功，但触发本次预建的 INSERT 因不相关原因失败（FILES schema 不匹配、BE 崩溃、导入超时等），空的预建分区会留在 catalog 中。这与 ALTER TABLE ADD PARTITION 在后续失败时的语义一致 —— ALTER 同样不会回滚已建分区。介意残留的运维可以用 ALTER TABLE ... DROP PARTITION 手动删除；实际上空分区代价很低，下次重试导入时会复用。

生产部署建议​

生产集群应将 enable_execute_script_on_frontend = false。基于采样的 Tablet 预分裂没有任何 SQL 入口依赖 FE 端脚本执行——生产路径通过连接器 + 规划器直接采样。把 enable_execute_script_on_frontend = true 留在打开状态只会扩大 FE 攻击面，并不带来任何预分裂功能；生产集群的安全默认值是关闭。

Rocky the happy otterStarRocks Assistant

AI generated answers are based on docs and other sources. Please test answers in non-production environments.