Session Variable List

This page is under construction and is not yet complete

This page collects the session variables of Doris. It currently only covers variables that were added, had their default changed, or were removed in recent versions; it is not yet a complete reference. For a variable that does not appear here, use SHOW VARIABLES LIKE '<pattern>' to inspect its current value.

For how variables are classified, scoped and set, see Variables.

Inspect and set

-- Inspect
SHOW VARIABLES LIKE 'enable_file_scanner_v2';

-- Current session only
SET enable_file_scanner_v2 = false;

-- Globally (applies to sessions created afterwards)
SET GLOBAL enable_file_scanner_v2 = false;

What changed in 4.1.4

Category	Variables
Added	enable_file_scanner_v2, enable_external_scan_task_reuse, file_split_size_on_fe, file_split_size_on_be, enable_expr_zonemap_filter, enable_local_exchange_before_agg, enable_local_exchange_before_streaming_agg, runtime_filter_broadcast_join_producer_num, runtime_filter_tree_publish_max_send_bytes, bucket_shuffle_downgrade_ratio, eager_aggregation_on_broadcast_join, eager_agg_broadcast_row_count, force_eager_agg_hint, enable_topn_lazy_mat_phase2_no_write_file_cache, file_cache_query_limit_bytes, file_presigned_url_ttl_seconds, force_forward_all_queries
Default value or semantics changed	max_scanners_concurrency, enable_runtime_filter_partition_prune, enable_nereids_distribute_planner
Removed	eager_aggregation_on_join, plan_nereids_dump

External table scan

enable_file_scanner_v2

Item	Value
Type	Boolean
Default	true
Version	Added in 4.1.4

Whether to use File Scanner V2 to scan external files. When enabled, FileScanNode uses the new native scan engine for the query scenarios it supports, covering the Parquet, ORC, CSV and JSON formats as well as the Hive, Iceberg, Paimon and Hudi table formats. JDBC catalogs and Iceberg system tables still use the legacy scan path.

Set it to false to compare behavior if you suspect a query issue is related to the new scanner. See Data Lake Query Tuning.

enable_external_scan_task_reuse

Item	Value
Type	Boolean
Default	true
Version	Added in 4.1.4

Whether equivalent external table scan nodes within one statement reuse the splits they generate. When enabled, a self-join or a CTE referenced several times over the same external table no longer re-plans the splits, which reduces FE planning time. Applies to Hive, Hudi, Iceberg and Paimon.

file_split_size_on_fe

Item	Value
Type	Long (bytes)
Default	536870912 (512 MB)
Version	Added in 4.1.4

Target size of the coarse-grained file splits produced by FE when the BE can refine them further. A non-positive value disables BE-side refinement and falls back to the legacy FE split policy.

file_split_size_on_be

Item	Value
Type	Long (bytes)
Default	67108864 (64 MB)
Version	Added in 4.1.4

Target size of the fine-grained splits the BE produces per Parquet row group or ORC stripe. Because a row group or stripe is indivisible, an individual split can exceed this target.

enable_expr_zonemap_filter

Item	Value
Type	Boolean
Default	false
Version	Added in 4.1.4

Controls expression ZoneMap filtering in the scanners that honor this variable.

File Scanner V2 always performs the safe form of expression ZoneMap filtering and is not affected by this variable.

enable_runtime_filter_partition_prune

Item	Value
Type	Boolean
Default	true
Version	Semantics changed in 4.1.4

Controls runtime-filter partition pruning in the scanners that honor this variable.

Since 4.1.4, File Scanner V2 always performs the safe form of partition pruning, so setting this variable to false has no effect on File Scanner V2.

max_scanners_concurrency

Item	Value
Type	Int
Default	8 (4 before 4.1.4)
Version	Default changed in 4.1.4

Maximum scan concurrency of a ScanNode. 4.1.4 raised the default from 4 to 8 to improve throughput when scan threads are the bottleneck. Set it back to 4 to keep the old behavior.

Query planning and execution

enable_nereids_distribute_planner

Item	Value
Type	Boolean
Default	true
Version	Upgrade behavior changed in 4.1.4

Whether to use the Nereids distributed planner.

Since 4.1.4, upgrading refreshes the global default of this variable to true, even when the cluster metadata previously persisted false. If plan distribution looks different after the upgrade, run SET GLOBAL enable_nereids_distribute_planner = false; to roll back.

runtime_filter_broadcast_join_producer_num

Item	Value
Type	Int
Default	3
Version	Added in 4.1.4

Maximum number of producer BEs for each runtime filter in a broadcast join. A value less than or equal to 0 removes the limit.

In a broadcast join every build-side BE produces the same runtime filter content, so bounding the number of producers noticeably reduces RPC overhead on large clusters. This only affects the Nereids distributed planning path; the legacy Coordinator path keeps its existing behavior.

runtime_filter_tree_publish_max_send_bytes

Item	Value
Type	Long (bytes)
Default	268435456 (256 MB)
Version	Added in 4.1.4

Maximum number of bytes sent in a single RPC when publishing a global runtime filter. Above this threshold Doris switches to tree (multi-level) publishing, so the merge node no longer sends the same large filter to every scan node.

A value of 0 disables tree publishing and falls back to direct publishing. The value must be greater than or equal to 0, otherwise setting it fails.

bucket_shuffle_downgrade_ratio

Item	Value
Type	Double
Default	0.8
Version	Added in 4.1.4 (experimental)

Downgrade a bucket shuffle join to a regular shuffle join when the base table side's total bucket count is smaller than the total instance count times this ratio. A value less than or equal to 0 never downgrades. The default of 0.8 keeps the original behavior.

enable_local_exchange_before_agg

Item	Value
Type	Boolean
Default	true
Version	Added in 4.1.4

Whether a local exchange is inserted before an aggregation operator.

caution

Turning this off is not recommended. Before 4.1.4, disabling this behavior could return wrong results with serial or non-hash local exchanges; that issue was fixed in 4.1.4.

enable_local_exchange_before_streaming_agg

Item	Value
Type	Boolean
Default	false
Version	Added in 4.1.4

Whether a local exchange is inserted before a streaming aggregation operator.

eager_aggregation_on_broadcast_join

Item	Value
Type	Boolean
Default	true
Version	Added in 4.1.4

Whether eager aggregation (aggregation push-down) is allowed on a broadcast join.

eager_agg_broadcast_row_count

Item	Value
Type	Int
Default	250000
Version	Added in 4.1.4

Row-count threshold used to decide whether to apply eager aggregation on a broadcast join.

force_eager_agg_hint

Item	Value
Type	String
Default	"" (empty)
Version	Added in 4.1.4

A matching hint that forces eager aggregation push-down, intended for testing and debugging. Not recommended in production.

The format is <func>:<qualifier.column | *>=<push|nopush>, with entries separated by ;:

SET force_eager_agg_hint = 'sum:t1.a=push; sum:t2.a=nopush; count:*=push';

Note that entries are matched per aggregate function, but the effect applies to the current candidate push-down branch or subtree rather than to one aggregate function independently. If any matched entry in a branch is nopush, that branch is not pushed down; otherwise, if any matched entry is push, that branch may be forced down, and the other aggregates in the same branch follow that branch-level decision.

force_forward_all_queries

Item	Value
Type	Boolean
Default	false
Version	Added in 4.1.4

When enabled, every query in the current session is forwarded to the master FE. This is useful when diagnosing problems caused by metadata inconsistency between the master and follower FEs. The variable is the session-level counterpart of the FE configuration item of the same name.

Cache

file_cache_query_limit_bytes

Item	Value
Type	Long (bytes)
Default	-1
Version	Added in 4.1.4

Maximum number of remote scan bytes a single query may write to the file cache through read-through on each BE:

• less than 0: no limit (feature disabled);
• equal to 0: the query never writes to the file cache;
• greater than 0: the query stops writing to the file cache once its cumulative remote scan volume reaches this threshold.

Use it to prevent a one-off large scan from evicting hot data from the cache.

enable_topn_lazy_mat_phase2_no_write_file_cache

Item	Value
Type	Boolean
Default	false
Version	Added in 4.1.4

When enabled, phase-2 reads of TopN lazy materialization go straight to remote storage on a file cache miss and do not write the missed range back to the file cache. This helps when the phase-2 read pattern is random and the cache hit rate is low.

AI functions

file_presigned_url_ttl_seconds

Item	Value
Type	Long (seconds)
Default	3600
Version	Added in 4.1.4

Expiration time of the presigned URL generated for an object in S3-compatible storage in multimodal EMBED() scenarios. Increase it when media files are large and the provider takes longer to fetch them. See EMBED.

Removed variables

Variable	Removed in	Notes
eager_aggregation_on_join	4.1.4	The aggregation push-down strategy was reworked; use eager_aggregation_on_broadcast_join and eager_agg_broadcast_row_count instead. Remove the variable from any script that still sets it
plan_nereids_dump	4.1.4	Now internal state that is only turned on while replaying a minidump; it can no longer be set with SET