Parallel queries

YugabyteDB supports the use of PostgreSQL parallel queries. Using parallel queries, the query planner can devise plans that leverage multiple CPUs to answer queries faster.

YugabyteDB supports parallel queries for colocated, hash-, and range-sharded tables.

To configure parallel queries, set the following configuration parameters.

Parameter	Description	Default
yb_enable_parallel_append	Enables the planner's use of parallel append plans in YugabyteDB.	false
enable_parallel_append	PostgreSQL parameter for enabling the planner's use of parallel append plans. For more information, refer to Parallel Append in the PostgreSQL documentation.	true
yb_enable_parallel_scan_colocated	Enables the planner's use of parallel queries for colocated tables.
Available in v2025.2.2 and later.	true
yb_enable_parallel_scan_hash_sharded	Enables the planner's use of parallel queries for hash-sharded tables.
Available in v2025.2.2 and later.	false
yb_enable_parallel_scan_range_sharded	Enables the planner's use of parallel queries for range-sharded tables.
Available in v2025.2.2 and later.	false
yb_parallel_range_rows	The number of rows to plan per parallel worker.	0
yb_parallel_range_size	Approximate size of parallel range for DocDB relation scans. Numeric with memory unit (B, kB, MB, or GB).	1MB

In addition, you can use the following PostgreSQL configuration parameters to configure parallel queries:

• Optimize the number of workers used by the parallel query.
  • max_parallel_workers
  • max_parallel_workers_per_gather
  • max_parallel_maintenance_workers
• Optimize cost of parallel plan to achieve the optimal plan.
  • parallel_setup_cost
  • parallel_tuple_cost
• Enable or disable the query planner's use of hash-join plan types with parallel hash. Has no effect if hash-join plans are not also enabled. The default is on.
  • enable_parallel_hash

For more information, refer to How Parallel Query Works in the PostgreSQL documentation.

Enable parallel query

To enable parallel query in v2025.2.2 or later, set the following parameters:

• yb_enable_parallel_append: true.
• yb_parallel_range_rows: a value other than 0 (10000 recommended).
• yb_enable_parallel_scan_colocated, yb_enable_parallel_scan_hash_sharded, and/or yb_enable_parallel_scan_range_sharded: true.

To enable parallel query in v2025.2.1 and earlier, set the following parameters:

• yb_enable_parallel_append: true.
• enable_parallel_append: true (the default).
• yb_parallel_range_rows: a value other than 0 (10000 recommended).

Parallel append is also enabled with the cost-based optimizer (CBO). When you set CBO to on, parallel append is enabled as follows:

• yb_enable_parallel_append is set to true.
• enable_parallel_append is set to true (the default).
• yb_parallel_range_rows is set to 10000.

Note that when upgrading a deployment to v2025.2 or later, if the universe has CBO enabled (on), parallel append is automatically enabled.

For information on CBO, refer to Enable cost-based optimizer.