distributed_plan_* session settings

These settings are available in system.settings and are autogenerated from source.

​

distributed_plan_default_reader_bucket_count

Default number of tasks for parallel reading in distributed query. Tasks are spread across between replicas. Used by the rule-based distributed planner. The cost-based optimizer chooses the read fan-out by estimated cost and does not use this setting.

​

distributed_plan_default_shuffle_join_bucket_count

Default number of buckets for distributed shuffle-hash-join. Used by the rule-based distributed planner. The cost-based optimizer chooses the fan-out by estimated cost and does not use this setting.

​

distributed_plan_exchange_compression_method

The codec for compressing the packets of the streaming exchange between the tasks of a distributed query plan. Exchanges through temporary files use the default codec of the server. Possible values:

• '' — use the codec of network_compression_method.
• NONE — no compression.
• LZ4 — use the LZ4 codec.
• LZ4HC — use the LZ4HC codec at its default level 9. It compresses many times slower than LZ4.
• ZSTD — use the ZSTD codec with the level of distributed_plan_exchange_zstd_compression_level.

​

distributed_plan_exchange_zstd_compression_level

The level of ZSTD compression of the streaming exchange of a distributed query plan. Used only when distributed_plan_exchange_compression_method is set to ZSTD. Possible values:

• Integer from 1 to 22. Higher levels compress better and slower.

​

distributed_plan_execute_locally

Run all tasks of a distributed query plan locally. Useful for testing and debugging.

​

distributed_plan_fallback_to_local_execution

When a query plan contains a step that does not support distributed execution, log the reason and execute the query on the initiator instead of throwing an exception. Disable to get an exception instead. Only takes effect when make_distributed_plan (private preview) is enabled.

​

distributed_plan_force_exchange_kind

Force specified kind of Exchange operators between distributed query stages. Possible values:

• ” - do not force any kind of Exchange operators, let the optimizer choose,
• ‘Persisted’ - use temporary files in object storage,
• ‘Streaming’ - stream exchange data over network.

​

distributed_plan_force_shuffle_aggregation

Use Shuffle aggregation strategy instead of PartialAggregation + Merge in distributed query plan. Ignored where the Shuffle strategy cannot produce a correct result, for example for GROUPING SETS or when the aggregation must produce results in bucket order.

​

distributed_plan_join_runtime_filters

With make_distributed_plan, send join runtime filters built in one stage to the stages that read the probe side, so those stages filter rows before sending them. If a filter does not arrive, rows pass unfiltered. Requires enable_join_runtime_filters.

​

distributed_plan_max_buffered_log_rows

When send_logs_level forwards stateless-worker task logs to the coordinator, each worker task buffers at most this many log lines between status polls. Lines beyond the bound are dropped and their count is reported to the client. 0 means unbounded (never drops, but a stalled status poll can grow the buffer without limit).

​

distributed_plan_max_rows_to_broadcast

Maximum rows to use broadcast join instead of shuffle join in distributed query plan. A heuristic for the rule-based distributed planner. When the cost-based optimizer is enabled, the broadcast-vs-shuffle choice is made by estimated cost and this setting has no effect.

​

distributed_plan_optimize_exchanges

Removes unnecessary exchanges in distributed query plan. Disable it for debugging.

​

distributed_plan_partial_aggregation_before_shuffle

Aggregate partially on the nodes that read the data before a distributed aggregation shuffles it by the GROUP BY keys, so the shuffle sends one aggregation state per group from each node instead of every input row, and each bucket merges the states of its own keys. The rule-based planner keeps shuffling the input rows when column statistics show that partial aggregation would not reduce the data at least twofold. With enable_cascades_optimizer, the setting allows the optimizer to choose such a merge per bucket by cost. Takes effect only together with make_distributed_plan = 1, and not with distributed_plan_force_shuffle_aggregation, which shuffles the input rows.

​

distributed_plan_prefer_replicas_over_workers

Serialize the distributed query plan for execution at replicas.

​

distributed_plan_read_in_order

Allow the read-in-order optimization for ORDER BY in a distributed query plan, so a sorted read of the table’s sorting key can skip the sort and stop early instead of scanning and sorting. Off by default: the rewrite that distributes a sort assumes the sort it wraps does not depend on its input already being ordered, and a sort that does can be fed rows through an exchange that does not preserve order. Only shapes where no exchange survives between the read and the sort are safe today.

​

distributed_plan_worker_cluster

Name of the stateless-worker cluster to execute this query’s distributed plan on. The empty default selects the pre-configured default cluster; other clusters are configured under stateless_worker_client.clusters.

​

distributed_plan_workers_num

How many stateless workers will be used to execute this query. Zero disables stateless-worker leasing for distributed plans.

​

distributed_plan_workers_provisioning_timeout_ms

Total wall-clock time, in milliseconds, a query may spend provisioning stateless workers before execution: leasing them from the discovery service and verifying they are reachable. The query blocks up to this budget for the leased workers to become ready; when it elapses the query proceeds with the workers verified so far, or fails if none became available. Zero waits only for the initial lease-and-verify pass (no retries).