From 0a4e26f57aee977f703be17ee093387eddc74e1e Mon Sep 17 00:00:00 2001 From: JmPotato Date: Wed, 1 Jul 2026 13:15:24 +0800 Subject: [PATCH 1/4] system-variables: add tidb_paging_size_bytes (internal use) Signed-off-by: JmPotato --- system-variables.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/system-variables.md b/system-variables.md index 9bae413e7f84..8f317ec45fa9 100644 --- a/system-variables.md +++ b/system-variables.md @@ -4745,6 +4745,18 @@ SHOW WARNINGS; - 范围：`[0, 2147483647]` - 控制优化器估算逻辑的更迭。更改该变量值后，优化器的估算逻辑会产生较大的改变。目前该变量的有效值只有 `0`，不建议设为其它值。 +### `tidb_paging_size_bytes` 从 v9.0.0 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 +- 类型：整数型 +- 默认值：`0` +- 范围：`[0, 9223372036854775807]` +- 单位：字节 +- 这个变量用来设置 coprocessor 协议中单个 paging 响应的字节数上限，用于在按行数分页（[`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入)）之外，额外提供按字节分页的能力。默认值为 `0`，表示关闭按字节分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)时生效，供 PD 资源管控做 RU 预扣费使用。 +- 该变量是 TiDB 内部使用的变量，**不推荐**修改该变量的值。 + ### `tidb_partition_prune_mode` 从 v5.1 版本开始引入 > **警告：** From 684e35b085f5e2f09be969fa5641f021ca72aec9 Mon Sep 17 00:00:00 2001 From: JmPotato Date: Fri, 17 Jul 2026 23:40:08 +0800 Subject: [PATCH 2/4] system-variables: update tidb_paging_size_bytes default and refine wording - Sync the default value with pingcap/tidb#69868: 0 -> 4194304 (4 MiB) - Apply review suggestions: clarify the byte-budget paging description, note that 0 disables it, and reword the internal-variable notice Signed-off-by: JmPotato --- system-variables.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/system-variables.md b/system-variables.md index 8f317ec45fa9..c6a456353a0d 100644 --- a/system-variables.md +++ b/system-variables.md @@ -4751,11 +4751,11 @@ SHOW WARNINGS; - 是否持久化到集群：是 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 - 类型：整数型 -- 默认值：`0` +- 默认值：`4194304`（即 4 MiB） - 范围：`[0, 9223372036854775807]` - 单位：字节 -- 这个变量用来设置 coprocessor 协议中单个 paging 响应的字节数上限，用于在按行数分页（[`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入)）之外，额外提供按字节分页的能力。默认值为 `0`，表示关闭按字节分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)时生效，供 PD 资源管控做 RU 预扣费使用。 -- 该变量是 TiDB 内部使用的变量，**不推荐**修改该变量的值。 +- 控制 coprocessor 协议中单个分页响应的字节数上限，用于在 [`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入) 所提供的按行数分页机制之外，额外提供按字节数分页的能力。默认值为 `4194304`（即 4 MiB），设为 `0` 表示关闭按字节数分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)且当前语句所属资源组具有固定的 RU 配额时生效，供 PD 的资源管控模块在执行语句前根据扫描数据量预估并预扣 RU。 +- 该变量为 TiDB 内部变量，**不推荐**修改该变量的值。 ### `tidb_partition_prune_mode` 从 v5.1 版本开始引入 From 201b47fb9f100eed75f535445b391a82e2e6d32b Mon Sep 17 00:00:00 2001 From: JmPotato Date: Fri, 24 Jul 2026 16:52:31 +0800 Subject: [PATCH 3/4] system-variables: restore tidb_paging_size_bytes default to 0 Sync with pingcap/tidb#70052: keep byte-budget paging disabled by default, and note 4 MiB as a candidate value when explicitly enabling it. Signed-off-by: JmPotato --- system-variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/system-variables.md b/system-variables.md index c6a456353a0d..ba00b3ee07a1 100644 --- a/system-variables.md +++ b/system-variables.md @@ -4751,10 +4751,10 @@ SHOW WARNINGS; - 是否持久化到集群：是 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 - 类型：整数型 -- 默认值：`4194304`（即 4 MiB） +- 默认值：`0` - 范围：`[0, 9223372036854775807]` - 单位：字节 -- 控制 coprocessor 协议中单个分页响应的字节数上限，用于在 [`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入) 所提供的按行数分页机制之外，额外提供按字节数分页的能力。默认值为 `4194304`（即 4 MiB），设为 `0` 表示关闭按字节数分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)且当前语句所属资源组具有固定的 RU 配额时生效，供 PD 的资源管控模块在执行语句前根据扫描数据量预估并预扣 RU。 +- 控制 coprocessor 协议中单个分页响应的字节数上限，用于在 [`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入) 所提供的按行数分页机制之外，额外提供按字节数分页的能力。默认值为 `0`，表示关闭按字节数分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)且当前语句所属资源组具有固定的 RU 配额时生效，供 PD 的资源管控模块在执行语句前根据扫描数据量预估并预扣 RU。如需启用，可考虑设置为 `4194304`（即 4 MiB）。 - 该变量为 TiDB 内部变量，**不推荐**修改该变量的值。 ### `tidb_partition_prune_mode` 从 v5.1 版本开始引入 From 7e6027e566b2baa92e1b0471f1876ec6bcb59c70 Mon Sep 17 00:00:00 2001 From: JmPotato Date: Thu, 17 Sep 2026 19:07:28 +0800 Subject: [PATCH 4/4] system-variables: document global paging byte budget updates Signed-off-by: JmPotato --- system-variables.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/system-variables.md b/system-variables.md index ba00b3ee07a1..dab5e6db224f 100644 --- a/system-variables.md +++ b/system-variables.md @@ -4747,14 +4747,18 @@ SHOW WARNINGS; ### `tidb_paging_size_bytes` 从 v9.0.0 版本开始引入 -- 作用域：SESSION | GLOBAL +- 作用域：GLOBAL - 是否持久化到集群：是 -- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 类型：整数型 - 默认值：`0` - 范围：`[0, 9223372036854775807]` - 单位：字节 -- 控制 coprocessor 协议中单个分页响应的字节数上限，用于在 [`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入) 所提供的按行数分页机制之外，额外提供按字节数分页的能力。默认值为 `0`，表示关闭按字节数分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)且当前语句所属资源组具有固定的 RU 配额时生效，供 PD 的资源管控模块在执行语句前根据扫描数据量预估并预扣 RU。如需启用，可考虑设置为 `4194304`（即 4 MiB）。 +- 该变量用于设置 TiKV coprocessor 请求的每页字节预算，仅在开启[资源管控](/tidb-resource-control-ru-groups.md)且当前语句所属资源组具有有限突发额度时生效。对于 `BURSTABLE=UNLIMITED` 的资源组，该预算不生效。 +- 按字节数分页与 [`tidb_enable_paging`](#tidb_enable_paging-从-v540-版本开始引入) 控制的按行数分页相互独立。将该变量设为 `0` 仅关闭按字节数分页，不影响按行数分页；关闭 `tidb_enable_paging` 也不会关闭按字节数分页。 +- 使用 `SET GLOBAL tidb_paging_size_bytes = ...` 修改该变量。更新对当前 TiDB 实例上已有连接和新建连接的后续语句生效，包括已开启事务中的后续语句，无需重新连接。语句在初始化分布式执行上下文时读取本实例的全局值；已初始化的执行上下文及其分页请求保留原有预算。其他 TiDB 实例通过系统变量缓存异步同步该值，因此各实例不保证同时生效。 +- 不支持通过 `SET SESSION` 或未指定作用域的 `SET` 修改该变量，这两种操作都会返回错误。使用 `SET_VAR` Hint 会产生警告，且不会覆盖全局值。可以通过 `@@GLOBAL.tidb_paging_size_bytes` 或 `@@tidb_paging_size_bytes` 查询当前实例的全局值。 +- 执行 `SET GLOBAL tidb_paging_size_bytes = 0` 或 `SET GLOBAL tidb_paging_size_bytes = DEFAULT` 可关闭按字节数分页，生效时机与其他全局值更新相同。 - 该变量为 TiDB 内部变量，**不推荐**修改该变量的值。 ### `tidb_partition_prune_mode` 从 v5.1 版本开始引入