---
title: "Parallel queries"
url: "https://docs.yugabyte.com/stable/additional-features/parallel-query/"
---

# Parallel queries

Parallel queries in YSQL

YugabyteDB supports the use of [PostgreSQL parallel queries](https://www.postgresql.org/docs/15/parallel-query.html "PostgreSQL parallel queries"). Using parallel queries, the [query planner](/stable/architecture/query-layer/planner-optimizer/ "query planner") can devise plans that leverage multiple CPUs to answer queries faster.

YugabyteDB supports parallel queries for [colocated](/stable/additional-features/colocation/ "colocated") tables.

[EA](/stable/releases/versioning/#feature-maturity) [Hash- and range-sharded](/stable/architecture/docdb-sharding/sharding/ "Hash- and range-sharded") tables are also supported in v2025.2.3 and later.

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. This is an alias of the PostgreSQL parameter enable\_parallel\_append. `true` 

enable\_parallel\_append PostgreSQL parameter for enabling the planner's use of parallel append plans. For more information, refer to [Parallel Append](https://www.postgresql.org/docs/15/parallel-plans.html#PARALLEL-APPEND "Parallel Append") in the PostgreSQL documentation. `true` 

yb\_enable\_parallel\_scan\_colocated Enables the planner's use of parallel queries for colocated tables.  
This flag was added in v2025.2.2. `true` 

[EA](/stable/releases/versioning/#feature-maturity) yb\_enable\_parallel\_scan\_hash\_sharded Enables the planner's use of parallel queries for hash-sharded tables.  
v2025.2.3 and later. `false` 

[EA](/stable/releases/versioning/#feature-maturity) yb\_enable\_parallel\_scan\_range\_sharded Enables the planner's use of parallel queries for range-sharded tables.  
v2025.2.3 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](https://www.postgresql.org/docs/15/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS "max_parallel_workers")
  - [max\_parallel\_workers\_per\_gather](https://www.postgresql.org/docs/15/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER "max_parallel_workers_per_gather")
  - [max\_parallel\_maintenance\_workers](https://www.postgresql.org/docs/15/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-MAINTENANCE "max_parallel_maintenance_workers")
- Optimize cost of parallel plan to achieve the optimal plan.
  
  - [parallel\_setup\_cost](https://www.postgresql.org/docs/15/runtime-config-query.html#GUC-PARALLEL-SETUP-COST "parallel_setup_cost")
  - [parallel\_tuple\_cost](https://www.postgresql.org/docs/15/runtime-config-query.html#GUC-PARALLEL-TUPLE-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](https://www.postgresql.org/docs/15/runtime-config-query.html#RUNTIME-CONFIG-QUERY-ENABLE "enable_parallel_hash")

For more information, refer to [How Parallel Query Works](https://www.postgresql.org/docs/15/how-parallel-query-works.html "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: `true`.
- yb\_enable\_parallel\_scan\_hash\_sharded, and/or yb\_enable\_parallel\_scan\_range\_sharded: `true` (v2025.2.3 and later only).

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](/stable/best-practices-operations/ysql-yb-enable-cbo/ "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](/stable/best-practices-operations/ysql-yb-enable-cbo/ "Enable cost-based optimizer").