docs/en/administration/management/FE_parameters/stats_storage.md
import FEConfigMethod from '../../../_assets/commonMarkdown/FE_config_method.mdx'
import AdminSetFrontendNote from '../../../_assets/commonMarkdown/FE_config_note.mdx'
import StaticFEConfigNote from '../../../_assets/commonMarkdown/StaticFE_config_note.mdx'
<FEConfigMethod />After your FE is started, you can run the ADMIN SHOW FRONTEND CONFIG command on your MySQL client to check the parameter configurations. If you want to query the configuration of a specific parameter, run the following command:
ADMIN SHOW FRONTEND CONFIG [LIKE "pattern"];
For detailed description of the returned fields, see ADMIN SHOW CONFIG.
:::note You must have administrator privileges to run cluster administration-related commands. :::
You can configure or modify the settings of FE dynamic parameters using ADMIN SET FRONTEND CONFIG.
ADMIN SET FRONTEND CONFIG ("key" = "value");
This topic introduces the following types of FE configurations:
enable_collect_warehouse_metricstrue, the system will collect and export per-warehouse metrics. Enabling it adds warehouse-level metrics (slot/usage/availability) to the metric output and increases metric cardinality and collection overhead. Disable it to omit warehouse-specific metrics and reduce CPU/network and monitoring storage cost.enable_http_detail_metricsHTTP_WORKER_PENDING_TASKS_NUM gauge). Enabling this causes the server to iterate over Netty worker executors and call pendingTasks() on each NioEventLoop to sum pending task counts; when disabled the gauge returns 0 to avoid that cost. This extra collection can be CPU- and latency-sensitive — enable only for debugging or detailed investigation.proc_profile_collect_time_sproc_profile_cpu_enable or proc_profile_mem_enable is set to true, AsyncProfiler is started, the collector thread sleeps for this duration, then the profiler is stopped and the profile is written. Larger values increase sample coverage and file size but prolong profiler runtime and delay subsequent collections; smaller values reduce overhead but may produce insufficient samples. Ensure this value aligns with retention settings such as proc_profile_file_retained_days and proc_profile_file_retained_size_bytes.alter_table_timeout_secondcapacity_used_percent_high_waterBackendLoadStatistic.calcSore uses capacity_used_percent_high_water to set LoadScore.capacityCoefficient: if a backend's used percent less than 0.5 the coefficient equal to 0.5; if used percent > capacity_used_percent_high_water the coefficient = 1.0; otherwise the coefficient transitions linearly with used percent via (2 * usedPercent - 0.5). When the coefficient is 1.0, the load score is driven entirely by capacity proportion; lower values increase the weight of replica count. Adjusting this value changes how aggressively the balancer penalizes backends with high disk utilization.catalog_trash_expire_secondcatalog_recycle_bin_erase_min_latency_mscatalog_recycle_bin_erase_max_operations_per_cyclecatalog_recycle_bin_erase_fail_retry_interval_mscheck_consistency_default_timeout_secondconsistency_check_cooldown_time_secondtablet.getLastCheckTime() is less than (currentTimeMillis - consistency_check_cooldown_time_second * 1000). The default value (24 * 3600) enforces roughly one check per tablet per day to reduce backend disk I/O. Lowering this value increases check frequency and resource usage; raising it reduces I/O at the cost of slower detection of inconsistencies. The value is applied globally when filtering cooldowned tablets from an index's tablet list.consistency_check_end_timeconsistency_check_start_time to decide when to schedule and add consistency-check jobs. When consistency_check_start_time is greater than consistency_check_end_time, the window spans midnight (for example, default is consistency_check_start_time = "23" to consistency_check_end_time = "4"). When consistency_check_start_time is equal to consistency_check_end_time, the checker never runs. Parsing failure will cause FE startup to log an error and exit, so provide a valid hour string.consistency_check_start_timeconsistency_check_end_time to decide when to schedule and add consistency-check jobs. When consistency_check_start_time is greater than consistency_check_end_time, the window spans midnight (for example, default is consistency_check_start_time = "23" to consistency_check_end_time = "4"). When consistency_check_start_time is equal to consistency_check_end_time, the checker never runs. Parsing failure will cause FE startup to log an error and exit, so provide a valid hour string.consistency_tablet_meta_check_interval_msTabletInvertedIndex and LocalMetastore. The daemon in runAfterCatalogReady triggers checkTabletMetaConsistency when current time - lastTabletMetaCheckTime exceeds this value. When an invalid tablet is first detected, its toBeCleanedTime is set to now + (consistency_tablet_meta_check_interval_ms / 2) so actual deletion is delayed until a subsequent scan. Increase this value to reduce scan frequency and load (slower cleanup); decrease it to detect and remove stale tablets faster (higher overhead).default_replication_numreplication_num=x in the CREATE TABLE DDL.enable_auto_tablet_distributionTRUE, you don't need to specify the number of buckets when you create a table or add a partition. StarRocks automatically determines the number of buckets.FALSE, you need to manually specify the number of buckets when you create a table or add a partition. If you do not specify the bucket count when adding a new partition to a table, the new partition inherits the bucket count set at the creation of the table. However, you can also manually specify the number of buckets for the new partition.enable_experimental_rowstoreenable_fast_schema_evolutionTRUE and FALSE (default). Enabling Fast Schema Evolution can increase the speed of schema changes and reduce resource usage when columns are added or dropped.NOTE
- StarRocks shared-data clusters supports this parameter from v3.3.0.
- If you need to configure the Fast Schema Evolution for a specific table, such as disabling Fast Schema Evolution for a specific table, you can set the table property
fast_schema_evolutionat table creation.
enable_online_optimize_tableenable_online_optimize_table is true and the target table meets compatibility checks (no partition/keys/sort specification, distribution is not RandomDistributionDesc, storage type is not COLUMN_WITH_ROW, replicated storage enabled, and the table is not a cloud-native table or materialized view), the planner creates an OnlineOptimizeJobV2 to perform optimization without blocking writes. If false or any compatibility condition fails, StarRocks falls back to OptimizeJobV2, which may block write operations during optimization.enable_strict_storage_medium_checkTRUE, the FE checks the storage medium of BEs when users create tables and returns an error if the storage medium of the BE is different from the storage_medium parameter specified in the CREATE TABLE statement. For example, the storage medium specified in the CREATE TABLE statement is SSD but the actual storage medium of BEs is HDD. As a result, the table creation fails. If this parameter is FALSE, the FE does not check the storage medium of BEs when users create a table.max_bucket_number_per_partitionmax_column_number_per_tablemax_dynamic_partition_numsystemtask_runs_max_history_number computes expected partitions (end offset + history partition number) and throws a DDL error if that total exceeds max_dynamic_partition_num. Raise this value only when you expect legitimately large partition ranges; increasing it allows more partitions to be created but can increase metadata size, scheduling work, and operational complexity.max_partition_number_per_tablemax_task_consecutive_fail_countTaskSource.MV.equals(task.getSource()) and max_task_consecutive_fail_count are greater than 0, if a task's consecutive failure counter reaches or exceeds max_task_consecutive_fail_count, the task is suspended via the TaskManager and, for materialized-view tasks, the materialized view is inactivated. An exception is thrown indicating suspension and how to reactivate (for example, ALTER MATERIALIZED VIEW <mv_name> ACTIVE). Set this item to 0 or a negative value to disable automatic suspension.partition_recycle_retention_period_secsrecover_with_empty_tabletFALSE, which means lost or corrupted tablet replicas are not replaced with empty ones, and the query fails.storage_usage_hard_limit_percentstorage_flood_stage_usage_percentstorage_usage_hard_limit_reserve_bytes, Load and Restore jobs are rejected. You need to set this item together with the BE configuration item storage_flood_stage_usage_percent to allow the configurations to take effect.storage_usage_hard_limit_reserve_bytesstorage_flood_stage_left_capacity_bytesstorage_usage_hard_limit_percent, Load and Restore jobs are rejected. You need to set this item together with the BE configuration item storage_flood_stage_left_capacity_bytes to allow the configurations to take effect.storage_usage_soft_limit_percentstorage_high_watermark_usage_percentstorage_usage_soft_limit_reserve_bytes, tablets cannot be cloned into this directory.storage_usage_soft_limit_reserve_bytesstorage_min_left_capacity_bytesstorage_usage_soft_limit_percent, tablets cannot be cloned into this directory.tablet_checker_lock_time_per_cycle_mstablet_create_timeout_secondtablet_delete_timeout_secondtablet_sched_balance_load_disk_safe_thresholdbalance_load_disk_safe_thresholdtablet_sched_balance_load_score_thresholdbalance_load_score_thresholdtablet_sched_be_down_tolerate_time_stablet_sched_disable_balancedisable_balanceTRUE indicates that tablet balancing is disabled. FALSE indicates that tablet balancing is enabled.tablet_sched_disable_colocate_balancedisable_colocate_balanceTRUE indicates replica balancing is disabled. FALSE indicates replica balancing is enabled.tablet_sched_max_balancing_tabletsmax_balancing_tabletstablet_sched_max_clone_task_timeout_secmax_clone_task_timeout_sectablet_sched_max_not_being_scheduled_interval_mstablet_sched_max_scheduling_tabletsmax_scheduling_tabletstablet_sched_min_clone_task_timeout_secmin_clone_task_timeout_sectablet_sched_num_based_balance_threshold_ratiotablet_sched_num_based_balance_threshold_ratio * tablet_sched_balance_load_score_threshold. If there are tablets in the cluster that are constantly balancing from A to B and B to A, reduce this value. If you want the tablet distribution to be more balanced, increase this value.tablet_sched_repair_delay_factor_secondtablet_repair_delay_factor_secondtablet_sched_slot_num_per_pathschedule_slot_num_per_path4 to 8.tablet_sched_storage_cooldown_secondstorage_cooldown_second-1 specifies that automatic cooling is disabled. If you want to enable automatic cooling, set this parameter to a value greater than -1.tablet_stat_update_interval_secondenable_range_distributiontablet_reshard_max_parallel_tabletstablet_reshard_target_sizetablet_reshard_max_split_counttablet_reshard_history_job_max_keep_msenable_tablet_pre_split_for_insert_from_filesINSERT INTO ... SELECT FROM FILES() loads. On by default as of v4.1.0. Set to false to disable cluster-wide. The session variable enable_tablet_pre_split must also be true for pre-split to run.enable_tablet_pre_split_for_broker_loadfalse to disable cluster-wide. The session variable enable_tablet_pre_split must also be true for pre-split to run.tablet_pre_split_pre_submit_timeout_secondsPENDING for at most this long during sampling, so keep it below the load's own timeout.tablet_pre_split_post_submit_wait_secondsFINISHED. Both INSERT-from-FILES and Broker Load synchronously wait and on expiry proceed without abort — the load then plans against the currently visible tablet layout (still the original layout if the daemon hasn't transitioned, or partially / fully post-split if the daemon raced past the wait); the tablet_pre_split_post_submit_hard_cap counter records the timeout. The strict runPreSplit wrapper used by tests aborts the calling load via PreSplitPostSubmitTimeoutException. For Broker Load the wait runs after the broker pending task resolves file statuses but before beginTxn opens T_load — it occupies a pending_load_task_scheduler thread for at most this many seconds per table, so size max_broker_load_job_concurrency accordingly when many concurrent Broker Loads target a pre-splittable layout. Operator note: the Broker Load remains PENDING in SHOW LOAD during the wait and is still subject to its own timeoutSecond — set this well below the smallest Broker Load timeout in normal use.tablet_pre_split_sample_byte_limittablet_pre_split_meta_tier_overlap_thresholdtablet_pre_split_max_partitions_per_loadTo disable the feature safely before a downgrade or during a production rollback:
enable_tablet_pre_split_for_insert_from_files = false and enable_tablet_pre_split_for_broker_load = false. New loads will skip pre-split immediately.SHOW TABLET RESHARD JOB; the rollback is complete once no RUNNING or PENDING rows remain.The multi-partition path extends Sample-Based Tablet Pre-Split to loads that target many partitions in one statement. Two operational caveats apply:
BrokerLoadJob.createLoadingTask after task.prepare() has built the load's sink plan against the catalog as it existed at that moment. For Broker Load, pre-created partitions and the post-reshard tablet layout are therefore only visible to subsequent loads on the same table — the triggering Broker Load itself runs against the original layout and uses BE runtime auto-create for any partitions it touches. INSERT-from-FILES (where the hook fires before StatementPlanner.plan()) is unaffected and benefits in the same load.ALTER TABLE ADD PARTITION, which also leaves a partition behind on subsequent failure. Operators who care can drop the empty partitions manually with ALTER TABLE ... DROP PARTITION; in practice empty partitions are cheap and the next retry of the load will reuse them.Set enable_execute_script_on_frontend = false in production. Sample-Based Tablet Pre-Split exposes no SQL surface that depends on FE-side script execution; the production code paths sample through the connector + planner directly. Leaving enable_execute_script_on_frontend = true widens the FE attack surface without enabling any pre-split functionality, so the safe default for production clusters is to keep it off.