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_execute_locally
Run all tasks of a distributed query plan locally. Useful for testing and debugging.
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.
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_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_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). Last modified on September 4, 2026
