docs/en/administration/management/FE_parameters/user_query_loading.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_task_info_mask_credentialinformation_schema.tasks and information_schema.task_runs by applying SqlCredentialRedactor.redact to the DEFINITION column. In information_schema.task_runs the same redaction is applied whether the definition comes from the task run status or, when empty, from the task definition lookup. When false, raw task definitions are returned (may expose credentials). Masking is CPU/string-processing work and can be time-consuming when the number of tasks or task_runs is large; disable only if you need unredacted definitions and accept the security risk.privilege_max_role_depthprivilege_max_total_roles_per_userbrpc_send_plan_fragment_timeout_msBackendServiceClient.sendPlanFragmentAsync sets this value prior to calling the backend execPlanFragmentAsync. It governs how long BRPC will wait when borrowing an idle connection from the connection pool and while performing the send; if exceeded, the RPC will fail and may trigger the method's retry logic. Set this lower to fail fast under contention, or raise it to tolerate transient pool exhaustion or slow networks. Be cautious: very large values can delay failure detection and block request threads.connector_table_query_trigger_analyze_large_table_intervalconnector_table_query_trigger_analyze_max_pending_task_numconnector_table_query_trigger_analyze_max_running_task_numconnector_table_query_trigger_analyze_small_table_intervalconnector_table_query_trigger_analyze_small_table_rowsconnector_table_query_trigger_task_schedule_intervalconnector_table_query_trigger_analyze_schedule_interval introduced in v3.4.0. Here, the background tasks refer ANALYZE tasks in v3.4，and the collection task of low-cardinality columns' dictionary in versions later than v3.4.create_table_max_serial_replicasdefault_mv_partition_refresh_numberdefault_mv_refresh_immediatetrue, newly created materialized view will be refreshed immediately.dynamic_partition_check_interval_secondsdynamic_partition_enableenable_active_materialized_view_schema_strict_checkfalse, the activation of the materialized view is not affected if the length of the data types has changed in the base table.mv_fast_schema_change_modestrict (default) - only allow FSE when isSupportFastSchemaEvolutionInDanger is true and clear affected partition entries from the version map; force - allow FSE even when isSupportFastSchemaEvolutionInDanger is false and clear affected partition entries to trigger recomputation on refresh; force_no_clear - allow FSE even when isSupportFastSchemaEvolutionInDanger is false but do not clear partition entries.enable_auto_collect_array_ndvenable_backup_materialized_viewfalse, StarRocks will skip backing up asynchronous materialized views.enable_collect_full_statisticenable_colocate_mv_indextrue, tablet sink will speed up the write performance of synchronous materialized views.enable_decimal_v3enable_experimental_mvenable_local_replica_selectionFALSE, both local replicas and non-local replicas can be selected.enable_manual_collect_array_ndvenable_materialized_viewenable_materialized_view_external_table_precise_refreshtrue to enable an internal optimization for materialized view refresh when a base table is an external (non-cloud-native) table. When enabled, the materialized view refresh processor computes candidate partitions and refreshes only the affected base-table partitions instead of all partitions, reducing I/O and refresh cost. Set it to false to force full-partition refresh of external tables.enable_materialized_view_metrics_collectenable_materialized_view_spillenable_materialized_view_text_based_rewritetrue, the system builds the abstract syntax tree while creating an asynchronous materialized view.enable_mv_automatic_active_checkenable_mv_automatic_repairing_for_broken_base_tablestrue, StarRocks will attempt to automatically repair materialized view base-table metadata when a base external table is dropped and recreated or its table identifier changes. The repair flow can update the materialized view's base table information, collect partition-level repair information for external table partitions, and drive partition refresh decisions for async auto-refresh materialized views while honoring autoRefreshPartitionsLimit. Currently the automated repair supports Hive external tables; unsupported table types will cause the materialized view to be set inactive and a repair exception. Partition information collection is non-blocking and failures are logged.enable_predicate_columns_collectionenable_query_queue_v2BaseSlotManager.isEnableQueryQueueV2 and SlotTracker#createSlotSelectionStrategy) to choose SlotSelectionStrategyV2 instead of the legacy strategy. query_queue_v2_xxx configuration options and QueryQueueOptions take effect only when this flag is enabled. From v4.1 onwards, the default value is changed from false to true.enable_sql_blacklistenable_statistic_collectenable_statistic_collect_on_first_loadDefault: true
Type: Boolean
Unit: -
Is mutable: Yes
Description: Controls automatic statistics collection and maintenance triggered by data loading operations. This includes:
Decision Policy for Statistics Collection Type:
For INSERT OVERWRITE: deltaRatio = |targetRows - sourceRows| / (sourceRows + 1)
deltaRatio < statistic_sample_collect_ratio_threshold_of_first_load (Default: 0.1), statistics collection will not be performed. Only the existing statistics will be copied.targetRows > statistic_sample_collect_rows (Default: 200000), SAMPLE statistics collection is used.For First Load: deltaRatio = loadRows / (totalRows + 1)
deltaRatio < statistic_sample_collect_ratio_threshold_of_first_load (Default: 0.1), statistics collection will not be performed.loadRows > statistic_sample_collect_rows (Default: 200000), SAMPLE statistics collection is used.Synchronization Behavior:
semi_sync_collect_statistic_await_seconds).:::note Disabling this configuration will prevent all loading-triggered statistics operations, including statistics maintenance for INSERT OVERWRITE, which may result in tables lacking statistics. If new tables are frequently created and data is frequently loaded, enabling this feature will increase memory and CPU overhead. :::
Introduced in: v3.1
enable_statistic_collect_on_updateenable_statistic_collect_on_first_load. Disabling this configuration skips statistics collection for UPDATE statements while keeping load-triggered statistics collection behavior unchanged.enable_udfexpr_children_limithistogram_buckets_sizehistogram_max_sample_row_counthistogram_mcv_sizehistogram_sample_ratiohttp_slow_request_threshold_mslock_checker_enable_deadlock_checklock_checker_interval_second) and writes detailed stack information to the log, which may be CPU- and I/O-intensive. Enable this option only for troubleshooting live or reproducible deadlock issues; leaving it enabled in normal operation can increase overhead and log volume.low_cardinality_thresholdmaterialized_view_min_refresh_intervalEVENT_TRIGGERED refreshes.materialized_view_refresh_ascendingtrue, materialized view partition refresh will iterate partitions in ascending partition-key order (oldest to newest). When it is set to false (default), the system iterates in descending order (newest to oldest). StarRocks uses this item in both list- and range-partitioned materialized view refresh logic to choose which partitions to process when partition refresh limits apply and to compute the next start/end partition boundaries for subsequent TaskRun executions. Changing this item alters which partitions are refreshed first and how the next partition range is derived; for range-partitioned materialized views, the scheduler validates new start/end and will raise an error if a change would create a repeated boundary (dead-loop), so set this item with care.max_allowed_in_element_num_of_deletemax_create_table_timeout_secondmax_distribution_pruner_recursion_depthmax_partitions_in_one_batchmax_planner_scalar_rewrite_nummax_query_queue_history_slots_numbermax_query_queue_history_slots_number is set to a value > 0, BaseSlotTracker keeps up to that many most-recently released LogicalSlot entries in an in-memory queue, evicting the oldest when the limit is exceeded. Enabling this causes getSlots() to include these history entries (newest first), allows BaseSlotTracker to attempt registering slots with the ConnectContext for richer ExtraMessage data, and lets LogicalSlot.ConnectContextListener attach query finish metadata to history slots. When max_query_queue_history_slots_number <= 0 the history mechanism is disabled (no extra memory used). Use a reasonable value to balance observability and memory overhead.max_query_retry_timemax_running_rollup_job_num_per_tablemax_scalar_operator_flat_childrenmax_scalar_operator_optimize_depthmv_active_checker_interval_secondsactive_checker thread is enabled, the system will periodically detect and automatically reactivate materialized views that became Inactive due to schema changes or rebuilds of their base tables (or views). This parameter controls the scheduling interval of the checker thread, in seconds. The default value is system-defined.mv_rewrite_consider_data_layout_modeenabledisable: Never use data-layout criteria when choosing between candidate materialized views.enable: Use data-layout criteria only when the query is recognized as layout-sensitive.force: Always apply data-layout criteria when selecting the best materialized view.
Changing this item affects BestMvSelector behavior and can improve or broaden rewrite applicability depending on whether physical layout matters for plan correctness or performance.publish_version_interval_msquery_queue_slots_estimator_strategyenable_query_queue_v2 is true. Valid values: MBE (memory-based), PBE (parallelism-based), MAX (take max of MBE and PBE) and MIN (take min of MBE and PBE). MBE estimates slots from predicted memory or plan costs divided by the per-slot memory target and is capped by totalSlots. PBE derives slots from fragment parallelism (scan range counts or cardinality / rows-per-slot) and a CPU-cost based calculation (using CPU costs per slot), then bounds the result within [numSlots/2, numSlots]. MAX and MIN combine MBE and PBE by taking their maximum or minimum respectively. If the configured value is invalid, the default (MAX) is used.query_queue_v2_concurrency_levelquery_queue_v2_concurrency_level * number_of_BEs * cores_per_BE (derived from BackendResourceStat). In multi-warehouse mode the effective concurrency is scaled down to max(1, query_queue_v2_concurrency_level / 4). If the configured value is non-positive it is treated as 4. Changing this value increases or decreases totalSlots (and therefore concurrent query capacity) and affects per-slot resources: memBytesPerSlot is derived by dividing per-worker memory by (cores_per_worker * concurrency), and CPU accounting uses query_queue_v2_cpu_costs_per_slot. Set it proportional to cluster size; very large values may reduce per-slot memory and cause resource fragmentation.query_queue_v2_cpu_costs_per_slotplan_cpu_costs / query_queue_v2_cpu_costs_per_slot) and then clamps the result to the range [1, totalSlots] (totalSlots is derived from the query queue V2 V2 parameters). The V2 code normalizes non-positive settings to 1 (Math.max(1, value)), so a non-positive value effectively becomes 1. Increasing this value reduces slots allocated per query (favoring fewer, larger-slot queries); decreasing it increases slots per query. Tune together with query_queue_v2_num_rows_per_slot and concurrency settings to control parallelism vs. resource granularity.query_queue_v2_num_rows_per_slotestimated_slots = (cardinality of the Source Node) / query_queue_v2_num_rows_per_slot, then clamps the result to the range [1, totalSlots] and enforces a minimum of 1 if the computed value is non-positive. totalSlots is derived from available resources (roughly DOP * query_queue_v2_concurrency_level * number_of_workers/BE) and therefore depends on cluster/core counts. Increase this value to reduce slot count (each slot handles more rows) and lower scheduling overhead; decrease it to increase parallelism (more, smaller slots), up to the resource limit.query_queue_v2_schedule_strategySWRR (Smooth Weighted Round Robin) — the default, suitable for mixed/hybrid workloads that need fair weighted sharing — and SJF (Short Job First + Aging) — prioritizes short jobs while using aging to avoid starvation. The value is parsed with case-insensitive enum lookup; an unrecognized value is logged as an error and the default policy is used. This configuration only affects behavior when Query Queue V2 is enabled and interacts with V2 sizing settings such as query_queue_v2_concurrency_level.semi_sync_collect_statistic_await_secondsenable_statistic_collect_on_first_load.slow_query_analyze_thresholdstatistic_analyze_status_keep_secondstatistic_auto_analyze_end_time00:00:00 - 23:59:59.statistic_auto_analyze_start_time00:00:00 - 23:59:59.statistic_auto_collect_ratiostatistic_auto_collect_small_table_rowsstatistic_cache_columnsstatistic_cache_thread_pool_sizestatistic_collect_interval_secstatistic_max_full_collect_data_sizestatistic_sample_collect_rowsenable_statistic_collect_on_first_load and statistic_sample_collect_ratio_threshold_of_first_load.statistic_update_interval_sectask_check_interval_seconddoTaskBackgroundJob(); the value is multiplied by 1000 to set the daemon interval in milliseconds. Decreasing the value makes background maintenance (task cleanup, checks) run more frequently and react faster but increases CPU/IO overhead; increasing it reduces overhead but delays cleanup and detection of stale tasks. Tune this value to balance maintenance responsiveness and resource usage.task_min_schedule_interval_sERR_INVALID_PARAMETER if the period is smaller than task_min_schedule_interval_s. This prevents creating tasks that run too frequently and protects the scheduler from high-frequency tasks. If a schedule has no explicit start time, TaskAnalyzer sets the start time to the current epoch seconds.task_runs_timeout_secondquery_timeout or insert_timeout with a positive integer value, the runtime uses the larger value between that session timeout and task_runs_timeout_second. The effective timeout is then bounded to not exceed the configured task_runs_ttl_second and task_ttl_second. Set this item to limit how long a task run may execute. Very large values may be clipped by the task/task-run TTL settings.broker_load_default_timeout_seconddesired_max_waiting_jobsdisable_load_jobFALSE, indicating that loading is not disabled. TRUE indicates loading is disabled and the cluster is in read-only state.empty_load_as_errortrue: If no data is loaded, the system displays a failure message and returns an error "all partitions have no load data".false: If no data is loaded, the system displays a success message and returns OK, instead of an error.enable_file_bundlingtrue), the system automatically bundles the data files generated by loading, Compaction, or Publish operations, thereby reducing the API cost caused by high-frequency access to the external storage system. You can also control this behavior on the table level using the CREATE TABLE property file_bundling. For detailed instructions, see CREATE TABLE.enable_routine_load_lag_metricstrue will call the Kafka API to get the partition's latest offset.enable_sync_publishTRUE (default): The apply task is synchronously executed at the publish phase of a load transaction. It means that the load transaction is reported as successful only after the apply task is completed, and the loaded data can truly be queried. When a task loads a large volume of data at a time or loads data frequently, setting this parameter to true can improve query performance and stability, but may increase load latency.FALSE: The apply task is asynchronously executed at the publish phase of a load transaction. It means that the load transaction is reported as successful after the apply task is submitted, but the loaded data cannot be immediately queried. In this case, concurrent queries need to wait for the apply task to complete or time out before they can continue. When a task loads a large volume of data at a time or loads data frequently, setting this parameter to false may affect query performance and stability.export_checker_interval_secondexport_max_bytes_per_be_per_taskexport_running_job_num_limitexport_task_default_timeout_secondexport_task_pool_sizeexternal_table_commit_timeout_ms10000 indicates a 10-second timeout duration.finish_transaction_default_lock_timeout_mshistory_job_keep_max_secondinsert_load_default_timeout_secondlabel_clean_interval_secondlabel_keep_max_numlabel_keep_max_secondload_checker_interval_secondload_parallel_instance_numenable_adaptive_sink_dop is true, the sessions sink_degree_of_parallelism` overrides this configuration. When shuffle is required, this value is applied to fragment parallel execution (scan fragment and sink fragment parallel exec instances). When no shuffle is needed, it is used as the sink pipeline DOP. Note: loads from local files are forced to a single instance (pipeline DOP = 1, parallel exec = 1) to avoid local disk contention. Increasing this number raises per-host concurrency and throughput but may increase CPU, memory and I/O contention.load_straggler_wait_secondloads_history_retained_days_statistics_.loads_history table. This value is used for table creation to set the table property partition_live_number and is passed to TableKeeper (clamped to a minimum of 1) to determine how many daily partitions to keep. Increasing or decreasing this value adjusts how long completed load jobs are retained in daily partitions; it affects new table creation and the keeper's pruning behavior but does not automatically recreate past partitions. The LoadsHistorySyncer relies on this retention when managing the loads history lifecycle; its sync cadence is controlled by loads_history_sync_interval_second.loads_history_sync_interval_secondinformation_schema.loads into the internal _statistics_.loads_history table. The value is multiplied by 1000 in the constructor to set the FrontendDaemon interval. The syncer skips the first run (to allow table creation) and only imports loads that finished more than one minute ago; small values increase DML and executor load, while larger values delay availability of historical load records. See loads_history_retained_days for retention/partitioning behavior of the target table.max_broker_load_job_concurrencyasync_load_task_pool_sizemax_running_txn_num_per_db. From v2.5 onwards, the default value is changed from 10 to 5.max_load_timeout_secondmax_routine_load_batch_sizemax_routine_load_task_concurrent_nummax_routine_load_task_num_per_beroutine_load_thread_pool_size (deprecated).max_running_txn_num_per_db1000. From v3.1 onwards, the default value is changed to 1000 from 100. When the actual number of load transactions running for a database exceeds the value of this parameter, new load requests will not be processed. New requests for synchronous load jobs will be denied, and new requests for asynchronous load jobs will be placed in queue. We do not recommend you increase the value of this parameter because this will increase system load.max_stream_load_timeout_secondmax_tolerable_backend_down_nummin_bytes_per_broker_scannermin_load_timeout_secondmin_routine_load_lag_for_metricsperiod_of_auto_resume_minprepared_transaction_default_timeout_secondroutine_load_task_consume_secondtask_consume_second in job_properties. This parameter applies to individual load tasks within a Routine Load job, which is more flexible.routine_load_task_timeout_secondtask_timeout_second in job_properties. This parameter applies to individual load tasks within a Routine Load job, which is more flexible.routine_load_unstable_threshold_secondspark_dpp_versionspark_home_default_dirStarRocksFE.STARROCKS_HOME_DIR + "/lib/spark2x"spark_launcher_log_dirsys_log_dir + "/spark_launcher_log"spark_load_default_timeout_secondspark_load_submit_timeout_secondSparkLauncherMonitor.LogMonitor converts this value to milliseconds and will stop monitoring and forcibly kill the spark launcher process if the job remains in UNKNOWN/CONNECTED/SUBMITTED longer than this timeout. SparkLoadJob reads this configuration as the default and allows a per-load override via the LoadStmt.SPARK_LOAD_SUBMIT_TIMEOUT property. Set it high enough to accommodate YARN queueing delays; setting it too low may abort legitimately queued jobs, while setting it too high may delay failure handling and resource cleanup.spark_resource_pathstream_load_default_timeout_secondstream_load_max_txn_num_per_be>= this limit. A value of < 0 disables the limit (unlimited). This check occurs during stream load begin and may cause a streamload txn num per be exceeds limit error when exceeded. Related runtime behavior uses stream_load_default_timeout_second for request timeout fallback.stream_load_task_keep_max_numidToStreamLoadTask) exceeds this threshold, StreamLoadMgr first calls cleanSyncStreamLoadTasks() to remove completed synchronous stream-load tasks; if the size still remains greater than half of this threshold, it invokes cleanOldStreamLoadTasks(true) to force removal of older or finished tasks. Increase this value to retain more task history in memory; decrease it to reduce memory usage and make cleanup more aggressive. This value controls in-memory retention only and does not affect persisted/replayed tasks.stream_load_task_keep_max_secondcurrentMs - endTimeMs > stream_load_task_keep_max_second * 1000), it becomes eligible for removal by StreamLoadMgr.cleanOldStreamLoadTasks and is discarded when loading persisted state. Applies to both StreamLoadTask and StreamLoadMultiStmtTask. If total task count exceeds stream_load_task_keep_max_num, cleanup may be triggered earlier (synchronous tasks are prioritized by cleanSyncStreamLoadTasks). Set this to balance history/debugability against memory usage.transaction_clean_interval_secondtransaction_stream_load_coordinator_cache_capacitytransaction_stream_load_coordinator_cache_expire_secondsyarn_client_pathStarRocksFE.STARROCKS_HOME_DIR + "/lib/yarn-client/hadoop/bin/yarn"yarn_config_dirStarRocksFE.STARROCKS_HOME_DIR + "/lib/yarn-config"