All Products
Search

This Product

    PolarDB:Use elastic parallel query (ePQ)

    Document Center

    PolarDB:Use elastic parallel query (ePQ)

    Last Updated:Jun 02, 2026

    Learn how to enable, configure, and control ePQ for PolarDB for MySQL, including parallel execution thresholds, hint syntax, and known limits.

    Before you begin

    • Confirm that your cluster supports elastic parallel query.

      • Single-node elastic parallel query:

        • Database engine: 8.0.1 whose revision version is 8.0.1.0.5 or later.

        • Database edition: Enterprise Edition.

      • Single-node elastic parallel query:

        • Database engine: 8.0.2 whose revision version is 8.0.2.1.4.1 or later.

        • Database edition: Enterprise Edition.

      • Multi-node elastic parallel query:

        • Database engine: 8.0.2 whose revision version is 8.0.2.2.6 or later.

        • Database edition: Enterprise Edition.

    • Review Limits and compatibility issues before enabling parallel query.

    • Read-only and RW nodes both support parallel query, but it is disabled by default on RW nodes. To enable it on RW nodes, Adaptively adjust the degree of parallelism.

    Enable or disable parallel query

    Enable

    Go to the PolarDB console. On the Basic Information page of the cluster, find the Database Connection section. Select the target endpoint and click Configure. In the Edit Endpoint Configuration dialog box, enable parallel query and configure the Degree of Parallelism.

    Click to expand the detailed steps

    1. Log on to the PolarDB console. In the navigation pane on the left, click Clusters. Select the region where the cluster is located, and then click the cluster ID to go to the cluster details page.

    2. On the Basic Information page of the cluster, find the Database Connection section. Select the target endpoint and click Configure.image

    3. In the Edit Endpoint Configuration dialog box, enable parallel query and configure the Degree of Parallelism. Other endpoint parameters are documented in Configure a database proxy.imageimage

    Recommended settings and notes:

    • Degree of Parallelism specifies the maximum worker threads a single query can use on one compute node. Total threads per query = Degree of Parallelism × number of nodes.

    • Increase the degree of parallelism gradually. Do not exceed one-fourth of the CPU core count. Start with 2. After one day, raise the value if CPU load stays low; stop if it rises.

    • Enabling parallel query takes effect only for new connections.

    • Console settings and cluster parameters interact as follows:

      • The loose_max_parallel_degree parameter applies to all nodes and connections in the cluster, but console adjustments apply only to the configured endpoint.

      • If both the console setting and loose_max_parallel_degree are configured, the console setting takes precedence. Use the console to enable parallel query.

      • If parallel query is not enabled in the console but loose_max_parallel_degree is set above 0, single-node parallel query is enabled by default.

      Note

      The loose_max_parallel_degree parameter sets the maximum worker threads for parallel execution of a single query. Parameter description.

    Disable

    Go to the PolarDB console. On the Basic Information page of the cluster, find the Database Connection section. Select the target endpoint and click Configure. In the Edit Endpoint Configuration dialog box, disable parallel query.

    Click to expand the detailed steps

    1. Log on to the PolarDB console. In the navigation pane on the left, click Clusters. Select the region where the cluster is located, and then click the cluster ID to go to the cluster details page.

    2. On the Basic Information page of the cluster, find the Database Connection section. Select the target endpoint and click Configure.image

    3. In the Edit Endpoint Configuration dialog box, disable parallel query.image

    Note:

    • Disabling parallel query takes effect only for new connections.

    • After disabling parallel query in the console, verify that loose_max_parallel_degree is also set to 0.

      Note

      The loose_max_parallel_degree parameter sets the maximum worker threads for parallel execution of a single query. Parameter description.

    Configure parallel query

    PolarDB provides several control policies for parallel query, summarized below. The full list is available in Configure parallel resource control policies.

    Type

    Description

    Optimizer parallel execution thresholds

    PolarDB provides two thresholds. The optimizer considers a parallel plan when a query exceeds either one.

    • loose_records_threshold_for_parallelism

      When the estimated scan count of a table exceeds this threshold, the optimizer considers a parallel plan. Default: 10000. For small datasets or low query concurrency, set to 2000 or higher.

      Note

      The scan count is an estimate based on table statistics and may not be exact.

    • loose_cost_threshold_for_parallelism

      When the estimated sequential execution cost exceeds this threshold, the optimizer considers a parallel plan. Default: 50000.

    Multi-node parallel scaling thresholds

    PolarDB provides two thresholds for multi-node parallel scaling. The system scales out when either is exceeded.

    • loose_records_threshold_for_mpp

      When a table's estimated scan count exceeds this threshold, the optimizer scales from single-node to multi-node parallel. By default, this value is N times the value of loose_records_threshold_for_parallelism, where N is the number of nodes within the current cluster endpoint.

    • loose_cost_threshold_for_mpp

      When a query's sequential execution cost exceeds this threshold, the optimizer scales to multi-node parallel. By default, this value is N times the value of loose_cost_threshold_for_parallelism, where N is the number of nodes within the current cluster endpoint.

    Control parallel query with hints

    Hints control parallel execution at the statement level, letting you override the default behavior, set the degree of parallelism, and specify which tables to parallelize. For example, use a hint to accelerate a specific slow query. Full syntax is documented in Parallel query hint syntax.

    Can I use hints to enable parallel query for a PolarDB cluster primary endpoint?

    Yes, but using the PolarDB console is recommended. For statement-level control, use /*+ PARALLEL(n) */ or /*+ SET_VAR(max_parallel_degree=n) */ to set the degree of parallelism to n. The two hints differ:

    • /*+ PARALLEL(n) */ forces parallel execution regardless of node type or data volume.

    • /*+ SET_VAR(max_parallel_degree=n) */ enables parallel execution only if the query routes to a read-only node and the optimizer cost and volume estimates justify it.

    Is there a conflict between parallel parameters set by hints in an SQL statement and settings in the console?

    No. Hint parameters apply only to the current statement and override global console settings.

    Limits and compatibility issues

    Limits

    PolarDB parallel execution has the following limitations:

    • Queries on non-InnoDB tables cannot be executed in parallel.

    • Queries that use a full-text index cannot be executed in parallel.

    • Expressions that contain stored Procedures must be executed on the leader node.

    • If a table is scanned using Index Merge, the table scan cannot be parallelized.

    • Query statements within serializable isolation level transactions cannot be executed in parallel.

    • If the isolation level is Repeatable-read, the query part of INSERT ... SELECT/REPLACE ... SELECT statements within a transaction cannot be executed in parallel.

    Compatibility

    • The number of error messages may change

      For a query that returns an error during sequential execution, the total number of error messages may differ during parallel execution.

    • Precision issues

      Parallel execution may store more intermediate floating-point results, which can cause minor precision differences in the final output.

    • Network packet or intermediate result exceeds max_allowed_packet

      Parallel execution may generate larger intermediate results. If the length of a network packet or intermediate result exceeds max_allowed_packet, an error may occur. Increase the max_allowed_packet parameter to resolve this. Set cluster parameters and node parameters.

    • Differences in result set order

      A SELECT ... LIMIT n statement without an ORDER BY clause may return rows in a different order during parallel execution, because multiple workers complete at different speeds.

    • Row lock count may increase

      During parallel execution of SELECT ... FROM ... FOR SHARE, InnoDB locks every accessed row. The row lock count may be higher than in sequential execution.

    FAQ

    After I enable parallel query, will all queries be accelerated in parallel?

    Not all queries run in parallel. The following cases fall back to sequential execution:

    • The query type is not supported. Limits.

    • The scan volume or query cost is below the threshold set by loose_records_threshold_for_parallelism and loose_cost_threshold_for_parallelism.

    • The cluster resource load is too high. System resource control policies.

    After I enable parallel query, why does the hint syntax not take effect?

    Check the following:

    • Parallel query changes take effect only on new connections. Reconnect to the cluster.

    • Parallel query is disabled by default on RW nodes. Use the cluster endpoint instead of the primary endpoint. Configure parallel resource control policies.