From c46d73fc8cac5480658e182c814e0bd282912377 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 11 Jun 2026 09:02:44 +0800 Subject: [PATCH 1/5] Create empty translation PR From 05dcc80d1826725971a49aa4812099b4f699f469 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 11 Jun 2026 01:04:11 +0000 Subject: [PATCH 2/5] Auto-sync: Update English docs from Chinese PR Synced from: https://github.com/pingcap/docs-cn/pull/20040 Target PR: https://github.com/pingcap/docs/pull/23037 AI Provider: azure Co-authored-by: github-actions[bot] --- system-variables.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/system-variables.md b/system-variables.md index c16e0dc2ee434..008c0cdd6eb88 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2090,6 +2090,23 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi - Default value: `OFF` - This variable controls whether to enable the deprecated batch-dml feature. When it is enabled, certain statements might be split into multiple transactions, which is non-atomic and should be used with care. When using batch-dml, you must ensure that there are no concurrent operations on the data you are operating on. To make it work, you must also specify a positive value for `tidb_batch_dml_size` and enable at least one of `tidb_batch_insert` and `tidb_batch_delete`. +### `tidb_enable_batch_query_region` New in v8.5.7 and v9.0.0 + +- Scope: GLOBAL +- Persists to cluster: Yes +- Is controlled by the Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Boolean +- Default value: `OFF` +- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it needs to query PD for Region routing information to update the local Region Cache. Among them, point query requests `GetRegion` (query the Region containing a Key), `GetPrevRegion` (query the previous adjacent Region by Key), and `GetRegionByID` (query by Region ID) are by default independent Unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. + - When this value is `OFF`, TiDB sends each point query for Region information to PD one by one as an independent Unary gRPC request. + - When this value is `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC Stream and sends them to PD in a merged way. PD then processes them uniformly and returns the results. Similar to the batching mechanism for TSO requests, this method can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when handling a large number of Region information query requests. +- This variable does not affect scan requests such as `BatchScanRegions`: although `BatchScanRegions` can also merge queries for multiple Key ranges into one request, it is itself an independent Unary gRPC request and does not go through the QueryRegion batching path. +- Changes to this variable take effect immediately across the whole cluster without restarting TiDB, so enabling and disabling it can both be controlled dynamically: after enabling it, TiDB switches to the preceding batching mode to obtain Region information; after disabling it, TiDB restores sending Unary gRPC requests one by one. +- Scenarios suitable for enabling Batch Query Region: + - The cluster has a large number of Regions, TiDB query concurrency is high, and Region Cache misses or invalidations generate a large number of concurrent Region information query requests, resulting in high CPU pressure on the PD leader. + - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing a large number of Region Cache invalidations and triggering concentrated retries of query requests, thereby generating a large number of Region information query requests. +- This variable and [`pd_enable_follower_handle_region`](#pd_enable_follower_handle_region-从-v760-版本开始引入) optimize in complementary directions: the former reduces the number of requests sent to PD through batching, while the latter reduces the load on the PD leader by allowing PD followers to handle Region query requests. They can be enabled at the same time. + ### tidb_enable_binding_usage New in v9.0.0 - Scope: GLOBAL From 096510a4c05d69fe451557fe5a1256bc8a3672a3 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 11 Jun 2026 09:15:07 +0800 Subject: [PATCH 3/5] Update system-variables.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- system-variables.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/system-variables.md b/system-variables.md index 008c0cdd6eb88..fc4fe59581597 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2094,18 +2094,18 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi - Scope: GLOBAL - Persists to cluster: Yes -- Is controlled by the Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it needs to query PD for Region routing information to update the local Region Cache. Among them, point query requests `GetRegion` (query the Region containing a Key), `GetPrevRegion` (query the previous adjacent Region by Key), and `GetRegionByID` (query by Region ID) are by default independent Unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. - - When this value is `OFF`, TiDB sends each point query for Region information to PD one by one as an independent Unary gRPC request. - - When this value is `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC Stream and sends them to PD in a merged way. PD then processes them uniformly and returns the results. Similar to the batching mechanism for TSO requests, this method can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when handling a large number of Region information query requests. -- This variable does not affect scan requests such as `BatchScanRegions`: although `BatchScanRegions` can also merge queries for multiple Key ranges into one request, it is itself an independent Unary gRPC request and does not go through the QueryRegion batching path. -- Changes to this variable take effect immediately across the whole cluster without restarting TiDB, so enabling and disabling it can both be controlled dynamically: after enabling it, TiDB switches to the preceding batching mode to obtain Region information; after disabling it, TiDB restores sending Unary gRPC requests one by one. -- Scenarios suitable for enabling Batch Query Region: - - The cluster has a large number of Regions, TiDB query concurrency is high, and Region Cache misses or invalidations generate a large number of concurrent Region information query requests, resulting in high CPU pressure on the PD leader. - - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing a large number of Region Cache invalidations and triggering concentrated retries of query requests, thereby generating a large number of Region information query requests. -- This variable and [`pd_enable_follower_handle_region`](#pd_enable_follower_handle_region-从-v760-版本开始引入) optimize in complementary directions: the former reduces the number of requests sent to PD through batching, while the latter reduces the load on the PD leader by allowing PD followers to handle Region query requests. They can be enabled at the same time. +- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it queries PD for Region routing information to update the local Region Cache. By default, point query requests such as `GetRegion` (queries the Region containing a key), `GetPrevRegion` (queries the previous adjacent Region by key), and `GetRegionByID` (queries by Region ID) are independent Unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. + - When this variable is set to `OFF`, TiDB sends each point query for Region information to PD as an independent Unary gRPC request. + - When this variable is set to `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC Stream and sends them to PD together. PD then processes them and returns the results. Similar to the batching mechanism for TSO requests, this feature can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when it handles a large number of Region query requests. +- This variable does not affect scan requests such as `BatchScanRegions`. Although `BatchScanRegions` can merge queries for multiple key ranges into one request, it is an independent Unary gRPC request and does not go through the QueryRegion batching path. +- Changes to this variable take effect immediately across the cluster without restarting TiDB, so you can enable or disable it dynamically. When you enable this variable, TiDB switches to the batching mode to obtain Region information. When you disable it, TiDB restores sending Unary gRPC requests one by one. +- You can enable the Batch Query Region feature in the following scenarios: + - The cluster has a large number of Regions, TiDB query concurrency is high, and Region Cache misses or invalidations generate many concurrent Region query requests, resulting in high CPU pressure on the PD leader. + - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing many Region Cache invalidations and triggering concentrated retries of query requests, which generates a large number of Region query requests. +- This variable and [`pd_enable_follower_handle_region`](#pd_enable_follower_handle_region-new-in-v760) optimize performance in complementary directions: the former reduces the number of requests sent to PD through batching, while the latter reduces the load on the PD leader by allowing PD followers to handle Region query requests. You can enable both variables at the same time. ### tidb_enable_binding_usage New in v9.0.0 From 893b4aad13362afe0927e82c8ba8e6cbef676599 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 11 Jun 2026 09:23:00 +0800 Subject: [PATCH 4/5] Apply suggestions from code review --- system-variables.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/system-variables.md b/system-variables.md index fc4fe59581597..6d89717d25731 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2097,14 +2097,14 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it queries PD for Region routing information to update the local Region Cache. By default, point query requests such as `GetRegion` (queries the Region containing a key), `GetPrevRegion` (queries the previous adjacent Region by key), and `GetRegionByID` (queries by Region ID) are independent Unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. - - When this variable is set to `OFF`, TiDB sends each point query for Region information to PD as an independent Unary gRPC request. - - When this variable is set to `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC Stream and sends them to PD together. PD then processes them and returns the results. Similar to the batching mechanism for TSO requests, this feature can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when it handles a large number of Region query requests. +- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it queries PD for Region routing information to update the local Region cache. By default, point query requests such as `GetRegion` (queries the Region containing a key), `GetPrevRegion` (queries the previous adjacent Region by key), and `GetRegionByID` (queries by Region ID) are independent Unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. + - When this variable is `OFF`, TiDB sends each point query for Region information to PD as an independent Unary gRPC request. + - When this variable is `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC Stream and sends them to PD together. PD then processes them and returns the results. Similar to the batching mechanism for TSO requests, this feature can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when it handles a large number of Region query requests. - This variable does not affect scan requests such as `BatchScanRegions`. Although `BatchScanRegions` can merge queries for multiple key ranges into one request, it is an independent Unary gRPC request and does not go through the QueryRegion batching path. - Changes to this variable take effect immediately across the cluster without restarting TiDB, so you can enable or disable it dynamically. When you enable this variable, TiDB switches to the batching mode to obtain Region information. When you disable it, TiDB restores sending Unary gRPC requests one by one. - You can enable the Batch Query Region feature in the following scenarios: - - The cluster has a large number of Regions, TiDB query concurrency is high, and Region Cache misses or invalidations generate many concurrent Region query requests, resulting in high CPU pressure on the PD leader. - - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing many Region Cache invalidations and triggering concentrated retries of query requests, which generates a large number of Region query requests. + - The cluster has a large number of Regions, TiDB query concurrency is high, and Region cache misses or invalidations generate many concurrent Region query requests, resulting in high CPU pressure on the PD leader. + - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing many Region cache invalidations and triggering concentrated retries of query requests, which generates a large number of Region query requests. - This variable and [`pd_enable_follower_handle_region`](#pd_enable_follower_handle_region-new-in-v760) optimize performance in complementary directions: the former reduces the number of requests sent to PD through batching, while the latter reduces the load on the PD leader by allowing PD followers to handle Region query requests. You can enable both variables at the same time. ### tidb_enable_binding_usage New in v9.0.0 From 3d780a288d067cdafd43043cb4d9c67e31d56e8a Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 11 Jun 2026 09:46:14 +0800 Subject: [PATCH 5/5] Update system-variables.md --- system-variables.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/system-variables.md b/system-variables.md index 6d89717d25731..b59418c73fc06 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2097,14 +2097,14 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it queries PD for Region routing information to update the local Region cache. By default, point query requests such as `GetRegion` (queries the Region containing a key), `GetPrevRegion` (queries the previous adjacent Region by key), and `GetRegionByID` (queries by Region ID) are independent Unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. - - When this variable is `OFF`, TiDB sends each point query for Region information to PD as an independent Unary gRPC request. - - When this variable is `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC Stream and sends them to PD together. PD then processes them and returns the results. Similar to the batching mechanism for TSO requests, this feature can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when it handles a large number of Region query requests. -- This variable does not affect scan requests such as `BatchScanRegions`. Although `BatchScanRegions` can merge queries for multiple key ranges into one request, it is an independent Unary gRPC request and does not go through the QueryRegion batching path. -- Changes to this variable take effect immediately across the cluster without restarting TiDB, so you can enable or disable it dynamically. When you enable this variable, TiDB switches to the batching mode to obtain Region information. When you disable it, TiDB restores sending Unary gRPC requests one by one. +- This variable controls whether to enable the Batch Query Region feature. When TiDB accesses data, it queries PD for Region routing information to update the local Region cache. By default, point query requests such as `GetRegion` (queries the Region containing a key), `GetPrevRegion` (queries the previous adjacent Region by key), and `GetRegionByID` (queries by Region ID) are independent unary gRPC requests. The Batch Query Region feature batches and merges these three types of requests. + - When this variable is `OFF`, TiDB sends each point query for Region information to PD as an independent unary gRPC request. + - When this variable is `ON`, TiDB batches concurrent point query requests for Region information within a short period through the QueryRegion gRPC stream and sends them to PD together. PD then processes them and returns the results. Similar to the batching mechanism for TSO requests, this feature can significantly reduce the number of gRPC requests, thereby reducing the CPU overhead of the PD leader when it handles a large number of Region query requests. +- This variable does not affect scan requests such as `BatchScanRegions`. Although `BatchScanRegions` can merge queries for multiple key ranges into one request, it is an independent unary gRPC request and does not go through the QueryRegion batching path. +- Changes to this variable take effect immediately across the cluster without restarting TiDB, so you can enable or disable it dynamically. When you enable this variable, TiDB switches to batching mode to obtain Region information. When you disable it, TiDB resumes sending unary gRPC requests one by one. - You can enable the Batch Query Region feature in the following scenarios: - The cluster has a large number of Regions, TiDB query concurrency is high, and Region cache misses or invalidations generate many concurrent Region query requests, resulting in high CPU pressure on the PD leader. - - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing many Region cache invalidations and triggering concentrated retries of query requests, which generates a large number of Region query requests. + - Changes such as Region split, merge, or Leader migration occur frequently in the cluster, causing many Region cache invalidations and triggering concentrated retries of query requests, generating a large number of Region query requests. - This variable and [`pd_enable_follower_handle_region`](#pd_enable_follower_handle_region-new-in-v760) optimize performance in complementary directions: the former reduces the number of requests sent to PD through batching, while the latter reduces the load on the PD leader by allowing PD followers to handle Region query requests. You can enable both variables at the same time. ### tidb_enable_binding_usage New in v9.0.0