All Products
Search

This Product

    PolarDB:Compute layer parameters for PolarDB-X

    Document Center

    PolarDB:Compute layer parameters for PolarDB-X

    Last Updated:Mar 30, 2026

    This page lists the compute layer parameters for PolarDB-X. These parameters control query execution, transaction behavior, connection pooling, optimizer behavior, and DDL operations.

    Only PolarDB-X Enterprise instances support compute layer parameters.

    Parameters that require a restart are marked with Restart required. All other parameters take effect immediately after you change them.

    Parameter groups

    General

    Parameter Restart required Default Range Unit Description
    PLAN_CACHE No FALSE TRUE | FALSE — Enables or disables the plan cache.
    ENABLE_RECYCLEBIN No FALSE TRUE | FALSE — Enables or disables the recycle bin.
    SHOW_TABLES_CACHE No FALSE TRUE | FALSE — Controls whether to cache the results of SHOW TABLES statements.
    TABLE_META_CACHE_EXPIRE_TIME No 300 0–180000 Seconds The time-to-live (TTL) for the metadata cache.
    COLUMN_LABEL_INSENSITIVE No TRUE TRUE | FALSE — Controls whether returned column labels are case-sensitive.
    MAX_ALLOWED_PACKET No 16777216 4194304–33554432 Bytes The maximum packet size.
    CHUNK_SIZE No 1024 1–10240 Rows The batch size for the executor. The executor processes data in batches of this size.
    LOGICAL_DB_TIME_ZONE No SYSTEM SYSTEM | ±HH:mm — The time zone of the database.
    SHOW_ALL_PARAMS No FALSE TRUE | FALSE — Controls whether SHOW VARIABLES displays all parameters.
    ENABLE_SPILL No FALSE TRUE | FALSE — Enables or disables spilling temporary tables to disk.
    PER_QUERY_MEMORY_LIMIT Yes -1 -1–9223372036854775807 Bytes The memory limit for the query-level memory pool. The default value (-1) means one-third of the global connection pool size.
    ENABLE_COROUTINE Yes FALSE TRUE | FALSE — Enables or disables the Wisp coroutine.
    SUPPORT_INSTANT_ADD_COLUMN No OFF ON | OFF — Enables or disables the instant add column feature. Set this parameter using SET GLOBAL.
    ENABLE_STATEMENTS_SUMMARY No true true | false — Enables or disables SQL statement aggregation.
    STATEMENTS_SUMMARY_PERCENT No 1 0–100 Percent The percentage of SQL statements to aggregate.

    Query execution and parallelism

    Parallelism

    Parameter Restart required Default Range Unit Description
    PARALLELISM No -1 1–1024 Threads The degree of parallelism (DOP) for a single node. The default value (-1) means the system determines this based on the node specifications.
    MPP_PARALLELISM No -1 1–1024 Threads The DOP for massively parallel processing (MPP) execution mode. The default value (-1) means the system determines this based on the node specifications.
    DATABASE_PARALLELISM No 0 0–1024 — The number of SQL statements a single query can concurrently send to one data node (DN). This value is used to calculate the DOP for scan operations.
    POLARDBX_PARALLELISM No 0 0–1024 Threads The maximum DOP for a single query on one compute node (CN). The default value (0) equals the number of CPU cores.
    MPP_METRIC_LEVEL No 3 0 | 1 | 2 | 3 — The level of detail for collecting performance statistics during computation. Higher values indicate finer granularity.
    LOGICAL_DDL_PARALLELISM No 1 1–10240 — The DOP for logical DDL execution. The default value (1) means DDL tasks are executed sequentially.

    Execution mode

    WORKLOAD_TYPE and EXECUTOR_MODE control how PolarDB-X classifies and executes queries.

    Parameter Restart required Default Range Unit Description
    WORKLOAD_TYPE No (auto) AP | TP — The workload type for a query. If not set, the system automatically identifies the workload type based on cost. Set AP to force analytical processing; set TP to force transactional processing.
    EXECUTOR_MODE No (auto) MPP | TP_LOCAL | AP_LOCAL — The execution mode for a query. If not set, the system selects a mode based on the workload type. MPP enables distributed execution across nodes; TP_LOCAL and AP_LOCAL limit execution to the local compute node.
    ENABLE_MASTER_MPP No FALSE TRUE | FALSE — Controls whether to enable MPP on the primary instance.

    Concurrency control

    Parameter Restart required Default Range Unit Description
    MERGE_CONCURRENT No FALSE TRUE | FALSE — Enables or disables full parallel execution. Mainly affects the DOP for Data Definition Language (DDL) statements and simple queries that are fully pushed down.
    MERGE_UNION No FALSE TRUE | FALSE — Controls UNION optimization for physical SQL statements. When enabled, UNION optimization is not performed, and pushed-down physical SQL statements are executed sequentially.
    MERGE_UNION_SIZE No -1 0–10000 — The number of physical SQL statements to merge using UNION. The default value (-1) means the system determines this automatically based on the number of available connections in the connection pool.
    GROUP_CONCURRENT_BLOCK No TRUE TRUE | FALSE — The execution policy at the database sharding level when not in MPP mode.
    SEQUENTIAL_CONCURRENT_POLICY No FALSE TRUE | FALSE — The sequential execution policy for concurrent requests when not in MPP mode.
    MERGE_SORT_BUFFER_SIZE No 2048 1024–81920 KB The buffer size for merge sort operations at the TableScan layer. The default value is 2 MB.

    BKA join batch sizes

    Batched Key Access (BKA) join parameters control how many IN values are batched per query, which affects both performance and memory usage.

    Parameter Restart required Default Range Unit Description
    JOIN_BLOCK_SIZE Yes 300 1–100000 Values The number of IN values for a BKA join when dynamic pruning is disabled.
    LOOKUP_JOIN_MAX_BATCH_SIZE Yes 6400 1–100000 Values The maximum number of IN values for a BKA join.
    LOOKUP_JOIN_MIN_BATCH_SIZE Yes 100 1–100000 Values The minimum number of IN values for a BKA join.
    LOOKUP_JOIN_BLOCK_SIZE_PER_SHARD Yes 50 1–100000 Values The number of IN values per shard for a BKA join when pruning is enabled.

    Optimizer switches

    All optimizer switch parameters take effect immediately without a restart.

    Join strategies

    Parameter Default Description
    ENABLE_HASH_JOIN TRUE Controls whether the optimizer can generate HashJoin nodes during query plan optimization.
    ENABLE_BKA_JOIN TRUE Controls whether the optimizer can generate BKAJoin nodes during query plan optimization.
    ENABLE_NL_JOIN TRUE Controls whether the optimizer can generate NLJoin (nested loop) nodes during query plan optimization.
    ENABLE_SORT_MERGE_JOIN TRUE Controls whether the optimizer can generate SortMergeJoin nodes during query plan optimization.
    ENABLE_BKA_PRUNING TRUE Enables or disables the pruning feature for BKA joins.

    SemiJoin conversion

    Parameter Default Description
    ENABLE_SEMI_NL_JOIN TRUE Controls whether the optimizer can convert a SemiJoin to an NLJoin during query plan optimization.
    ENABLE_SEMI_HASH_JOIN TRUE Controls whether the optimizer can convert a SemiJoin to a HashJoin during query plan optimization.
    ENABLE_SEMI_BKA_JOIN TRUE Controls whether the optimizer can convert a SemiJoin to a BKAJoin during query plan optimization.
    ENABLE_SEMI_SORT_MERGE_JOIN TRUE Controls whether the optimizer can convert a SemiJoin to a MergeJoin during query plan optimization.
    ENABLE_MATERIALIZED_SEMI_JOIN TRUE Controls whether the optimizer can convert a SemiJoin to a MaterializedJoin during query plan optimization.
    ENABLE_SEMI_JOIN_REORDER TRUE Controls whether the optimizer can include SemiJoin in cost-based optimizer (CBO) reordering.

    Aggregation strategies

    Parameter Default Description
    ENABLE_HASH_AGG TRUE Controls whether the optimizer can generate HashAgg nodes.
    ENABLE_PARTIAL_AGG TRUE Controls whether the optimizer can split an aggregation into two stages.
    ENABLE_SORT_AGG TRUE Controls whether the optimizer can generate SortAgg nodes.

    Pushdown optimizations

    Parameter Default Description
    ENABLE_PUSH_PROJECT TRUE Controls whether the optimizer can perform Project pushdown.
    ENABLE_PUSH_JOIN TRUE Controls whether the optimizer can perform Join pushdown.
    ENABLE_PUSH_AGG TRUE Controls whether the optimizer can perform Aggregation pushdown.
    ENABLE_CBO_PUSH_AGG TRUE Controls whether the optimizer can push an aggregation through a join.
    ENABLE_PUSH_SORT TRUE Controls whether the optimizer can perform Sort pushdown.
    ENABLE_CBO_PUSH_JOIN TRUE Controls whether the optimizer can perform join pass-through optimization.
    ENABLE_SORT_JOIN_TRANSPOSE TRUE Controls whether the optimizer can push a sort through a join.

    Statistics and plan management

    Parameter Default Description
    ENABLE_STATISTIC_FEEDBACK TRUE Controls whether to enable feedback-based statistics correction.
    ENABLE_BACKGROUND_STATISTIC_COLLECTION TRUE Controls whether to enable background collection of statistics.
    ENABLE_RUNTIME_FILTER TRUE Enables or disables the runtime filter.
    ENABLE_EXPRESSION_VECTORIZATION TRUE Enables or disables vectorization for expressions.
    ENABLE_SPM TRUE Specifies whether execution plan management (SPM) is enabled.

    HTAP workload feedback

    Parameter Default Description
    FEEDBACK_WORKLOAD_AP_THRESHOLD FALSE Enables or disables hybrid transactional and analytical processing (HTAP) feedback for analytical processing (AP) queries.
    FEEDBACK_WORKLOAD_TP_THRESHOLD FALSE Enables or disables HTAP feedback for transactional processing (TP) queries.

    Transaction

    Parameter Restart required Default Range Unit Description
    TRANSACTION_POLICY No TSO XA | TSO | TSO_READONLY — The transaction policy. See Choosing a transaction policy.
    TRANSACTION_ISOLATION No REPEATABLE-READ READ-UNCOMMITTED | READ-COMMITTED | REPEATABLE-READ | SERIALIZABLE — The transaction isolation level.
    SHARE_READ_VIEW No FALSE TRUE | FALSE — Enables or disables the shared ReadView feature.
    ENABLE_TRX_SINGLE_SHARD_OPTIMIZATION No TRUE TRUE | FALSE — Enables or disables single-shard optimization for transactions.
    GET_TSO_TIMEOUT No 10 1–1800 Seconds The timeout for getting a Timestamp Oracle (TSO) timestamp.
    MAX_TRX_DURATION No 28800 1–180000 Seconds The physical timeout for a transaction.
    PURGE_TRANS_INTERVAL Yes 300 1–180000 Seconds The interval for purging transaction logs.
    PURGE_TRANS_BEFORE Yes 1800 1–180000 Seconds The age of transaction logs to purge. The system purges logs older than this value.
    FORCE_READ_OUTSIDE_TX No FALSE TRUE | FALSE — Controls whether to forcibly open multiple connections to a single database shard within a transaction.

    Choosing a transaction policy

    TRANSACTION_POLICY accepts three values:

    • TSO (default): Uses Timestamp Oracle for distributed transaction ordering. Recommended for most production workloads because it provides consistent reads with lower overhead than XA.

    • XA: Uses the XA two-phase commit protocol. Use this when strict external transaction compatibility is required.

    • TSO_READONLY: Similar to TSO, but restricts the session to read-only transactions.

    DML behavior

    Parameter Restart required Default Range Unit Description
    DML_SKIP_DUPLICATE_CHECK_FOR_PK No TRUE TRUE | FALSE — Controls whether to skip the primary key conflict check during DML statement execution.
    DML_SKIP_CRUCIAL_ERR_CHECK No FALSE TRUE | FALSE — Controls whether to allow a transaction with DML errors to be committed.
    DML_USE_RETURNING No TRUE TRUE | FALSE — Controls whether to use the RETURNING clause for optimization.
    BROADCAST_DML No FALSE TRUE | FALSE — Controls whether writes to broadcast tables can bypass distributed transactions.
    FORBID_EXECUTE_DML_ALL No TRUE TRUE | FALSE — Controls whether to prohibit full-table DELETE and UPDATE operations.
    ENABLE_COMPLEX_DML_CROSS_DB No TRUE TRUE | FALSE — Controls whether to support complex DML statements across databases.
    SEQUENCE_STEP No 10000 1–10000000 — The step size for a sequence. The default value is 100,000.
    ALLOW_SIMPLE_SEQUENCE No FALSE TRUE | FALSE — Controls whether to allow the use of simple sequences.
    GENERAL_DYNAMIC_SPEED_LIMITATION No -1 -1–10000000 Rows/sec The dynamic speed limit for data backfill and validation. The default value (-1) sets a limit of 10,000 rows per second.
    TRUNCATE_TABLE_WITH_GSI No FALSE TRUE | FALSE — Controls whether to allow TRUNCATE TABLE on tables that have a global secondary index (GSI).
    DML_ON_GSI No FALSE TRUE | FALSE — Controls whether to allow DML statements to be executed directly on GSI tables.

    DDL behavior

    Parameter Restart required Default Range Unit Description
    MERGE_DDL_TIMEOUT No 0 1–10000000 — The timeout for a physical DDL connection. The default value (0) means no timeout.
    MERGE_DDL_CONCURRENT No FALSE TRUE | FALSE — Controls whether to execute DDL statements in full parallel mode. By default, DDL statements are executed with database-level concurrency.
    DDL_ON_GSI No FALSE TRUE | FALSE — Controls whether to allow DDL statements to be executed directly on GSI tables.
    FORCE_DDL_ON_LEGACY_ENGINE No TRUE TRUE | FALSE — Specifies whether the new DDL engine is enabled.
    PURE_ASYNC_DDL_MODE No FALSE TRUE | FALSE — Controls whether to execute DDL tasks in non-blocking (asynchronous) mode. When enabled, the client returns immediately after submitting a DDL statement. Check execution status with SHOW [FULL] DDL.
    DDL_JOB_REQUEST_TIMEOUT No 90000 1–9223372036854775807 — The maximum timeout for a DDL job. The default value is 25 days.
    GROUP_SEQ_CHECK_INTERVAL Yes 60 1–36000 Seconds The interval for checking explicitly inserted values.
    ENABLE_BROADCAST_RANDOM_READ No TRUE TRUE | FALSE — Enables or disables random read optimization for broadcast tables.

    Connection pool

    Parameters prefixed with CONN_POOL_ apply to the standard (JDBC) connection pool. Parameters prefixed with XPROTO_ apply to the proprietary protocol connection pool.

    Parameter Restart required Default Range Unit Description
    CONN_POOL_MIN_POOL_SIZE No 20 0–60 Connections The minimum number of connections to a physical database shard.
    CONN_POOL_MAX_POOL_SIZE No 60 1–1600 Connections The maximum number of connections to a physical database shard.
    CONN_POOL_MAX_WAIT_THREAD_COUNT No 0 -1–8192 Threads The maximum number of threads waiting for a connection to a single database shard. This applies to the Druid connection pool.
    CONN_POOL_IDLE_TIMEOUT No 30 1–60 Seconds The timeout for an idle physical connection.
    CONN_POOL_BLOCK_TIMEOUT No 5000 1000–60000 Milliseconds The maximum time to wait for a connection from the physical connection pool.
    CONN_POOL_XPROTO_MAX_POOLED_SESSION_PER_INST No 512 1–8192 Sessions The maximum number of cached sessions per storage node (proprietary protocol only).
    SOCKET_TIMEOUT No 900000 0–3600000 Milliseconds The connection timeout for physical SQL statements.
    XPROTO_MAX_DN_CONCURRENT No 500 1–8192 Requests The maximum number of concurrent requests per storage node (proprietary protocol only). The default was updated to 2000 on October 23, 2023 to accommodate most production and stress testing workloads.
    XPROTO_MAX_DN_WAIT_CONNECTION No 32 1–8192 Requests The maximum number of waiting requests per storage node (proprietary protocol only). The default was updated to 2000 on June 13, 2024 to accommodate most production and stress testing workloads.
    KILL_CLOSE_STREAM No FALSE TRUE | FALSE — Enables or disables early termination for physical connection streams.

    Read/write splitting

    Parameter Restart required Default Range Unit Description
    MASTER_READ_WEIGHT No -1 0–100 Percent Determines read traffic distribution. The percentage of traffic routed to read-only DNs is (100 - MASTER_READ_WEIGHT). The remaining traffic goes to the primary instance's DNs.
    STORAGE_DELAY_THRESHOLD No 16777216 0–16777216 — The synchronization latency threshold for a DN as perceived by a CN. If a read-only DN's latency exceeds this threshold, traffic is handled based on DELAY_EXECUTION_STRATEGY.
    DELAY_EXECUTION_STRATEGY No CONTINUE_TO_SLAVE CONTINUE_TO_SLAVE | CHANGE_TO_MASTER | THROW_EXCEPTION — The policy when a read-only DN exceeds the STORAGE_DELAY_THRESHOLD. See Choosing a delay execution strategy.
    STORAGE_BUSY_THRESHOLD No 100 0–16777216 Threads The active thread count threshold for a read-only DN. If a DN's active thread count exceeds this value, the router avoids sending read traffic to it. If all read-only DNs are busy, traffic falls back to a random read-only DN.
    ENABLE_CONSISTENT_REPLICA_READ No TRUE TRUE | FALSE — Enables or disables consistent reads from replicas. When TRUE, reads from read-only DNs satisfy consistent read requirements and return the latest committed data. When FALSE, data freshness depends on replication latency.

    Choosing a delay execution strategy

    DELAY_EXECUTION_STRATEGY accepts three values:

    • CONTINUE_TO_SLAVE (default): Routes read traffic to the read-only DN even if its latency exceeds the threshold. Use this when availability is more important than data freshness.

    • CHANGE_TO_MASTER: Routes traffic to a healthy read-only DN. If all read-only DNs exceed the threshold, traffic falls back to the primary instance's DNs. Use this when you need fresh data but want to avoid errors.

    • THROW_EXCEPTION: Fails queries routed to read-only DNs when all read-only DNs exceed the threshold. Use this when your application cannot tolerate stale data and must fail explicitly.

    Monitoring and logging

    Parameter Restart required Default Range Unit Description
    RECORD_SQL No TRUE TRUE | FALSE — Enables or disables the audit log.
    SLOW_SQL_TIME No 1000 1–180000 Milliseconds The threshold for a slow SQL statement.
    MAX_PARAMETERIZED_SQL_LOG_LENGTH No 5000 1–1000000 Characters The maximum length of a parameterized SQL statement that can be printed in the log.
    MPP_METRIC_LEVEL No 3 0 | 1 | 2 | 3 — The level of detail for collecting performance statistics during computation. Higher values indicate finer granularity.

    LOAD DATA

    Parameter Restart required Default Range Unit Description
    LOAD_DATA_BATCH_INSERT_SIZE No 1024 1–180000 Rows The number of records in each batch insert for a LOAD DATA statement.
    LOAD_DATA_CACHE_BUFFER_SIZE No 60 1–180000 MB The cache buffer size for LOAD DATA statements. The default value is 60 MB. This parameter is primarily used for throttling.