system-variables: add tidb_paging_size_bytes (internal use) by JmPotato · Pull Request #21752 · pingcap/docs-cn

JmPotato · 2026-07-01T05:15:47Z

What is changed, added or deleted? (Required)

新增系统变量 tidb_paging_size_bytes 的文档说明。

该变量由 pingcap/tidb#68091 引入，用于在 coprocessor 分页协议中，按字节数为单个 paging 响应设置上限（在按行数分页 tidb_max_paging_size 之外，额外提供按字节分页的能力）。默认值为 0，表示关闭按字节数分页；与 pingcap/tidb#70052 保持一致。该功能仅在开启资源管控且当前语句所属资源组具有固定的 RU 配额时生效，供 PD 的资源管控模块在执行语句前根据扫描数据量预估并预扣 RU。如需启用，可考虑设置为 4194304（即 4 MiB）。

该变量为 TiDB 内部变量，因此文档中已明确标注 不推荐修改该变量的值。

字段（作用域、是否持久化、SET_VAR Hint、类型、默认值、范围、单位）均取自源码定义（ScopeGlobal | ScopeSession、TypeUnsigned、默认 0、范围 [0, math.MaxInt64]）。

Which TiDB version(s) do your changes apply to? (Required)

master (the latest development version)

What is the related PR or file link(s)?

Other reference link(s):
- pingcap/tidb PR: *: add tidb_paging_size_bytes and forward it to coprocessor RPC tidb#68091
- pingcap/tidb PR（恢复默认值为 0）: sessionctx: restore tidb_paging_size_bytes default to 0 tidb#70052
- kvproto PR: proto: add paging_size_bytes to coprocessor.Request kvproto#1448

Summary by CodeRabbit

文档
- 新增系统变量 tidb_paging_size_bytes 的说明：包含作用域（SESSION | GLOBAL）、默认值/取值范围、集群持久化与 Hint 可设置方式。
- 补充“按字节数分页”的生效条件（需满足资源管控与固定 RU 配额等要求）及使用限制。
- 标注该变量为 TiDB 内部变量，不建议修改。

Signed-off-by: JmPotato <github@ipotato.me>

qiancai · 2026-07-14T07:05:31Z

+- 范围：`[0, 9223372036854775807]`
+- 单位：字节
+- 这个变量用来设置 coprocessor 协议中单个 paging 响应的字节数上限，用于在按行数分页（[`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入)）之外，额外提供按字节分页的能力。默认值为 `0`，表示关闭按字节分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)时生效，供 PD 资源管控做 RU 预扣费使用。
+- 该变量是 TiDB 内部使用的变量，**不推荐**修改该变量的值。


Suggested change

- 该变量是 TiDB 内部使用的变量，**不推荐**修改该变量的值。

- 该变量为 TiDB 内部变量，**不推荐**修改该变量的值。

已采纳，感谢 review！

qiancai

Rest LGTM

qiancai · 2026-07-14T07:07:44Z

+- 默认值：`0`
+- 范围：`[0, 9223372036854775807]`
+- 单位：字节
+- 这个变量用来设置 coprocessor 协议中单个 paging 响应的字节数上限，用于在按行数分页（[`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入)）之外，额外提供按字节分页的能力。默认值为 `0`，表示关闭按字节分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)时生效，供 PD 资源管控做 RU 预扣费使用。


Suggested change

- 这个变量用来设置 coprocessor 协议中单个 paging 响应的字节数上限，用于在按行数分页（[`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入)）之外，额外提供按字节分页的能力。默认值为 `0`，表示关闭按字节分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)时生效，供 PD 资源管控做 RU 预扣费使用。

- 控制 coprocessor 协议中单个分页响应的字节数上限，用于在 [`tidb_max_paging_size`](#tidb_max_paging_size-从-v630-版本开始引入) 所提供的按行数分页机制之外，额外提供按字节数分页的能力。默认值为 `0`，表示关闭按字节分页。该功能仅在开启[资源管控](/tidb-resource-control-ru-groups.md)时且当前语句所属资源组具有固定的 RU 配额时生效，供 PD 的资源管控模块在执行语句前根据扫描数据量预估并预扣 RU。

reason: “预扣费”通常表示预先扣除费用，容易使人误以为 RU 是货币费用；此处实际是预扣 RU。

已采纳该措辞，并同步了 pingcap/tidb#69868 的改动：默认值更新为 4194304（即 4 MiB），同时补充说明设为 0 表示关闭按字节数分页。

ti-chi-bot · 2026-07-14T07:23:37Z

[LGTM Timeline notifier]

Timeline:

2026-07-14 07:23:37.163120982 +0000 UTC m=+698403.199216038: ☑️ agreed by qiancai.

qiancai · 2026-07-14T07:24:39Z

@JmPotato I've added a few comments on this PR. PTAL.

…rding - 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 <github@ipotato.me>

ti-chi-bot · 2026-07-17T15:40:19Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from qiancai. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

coderabbitai · 2026-07-17T15:40:49Z

📝 Walkthrough

Walkthrough

新增 tidb_paging_size_bytes 系统变量文档，说明其配置属性、默认值、取值范围、按字节数分页的生效条件，以及内部变量属性。

Changes

分页字节数变量文档

Layer / File(s)	Summary
分页字节数变量说明 `system-variables.md`	新增 `tidb_paging_size_bytes` 的版本、作用域、集群持久化与 Hint 设置属性、类型、默认值、范围及生效条件说明。

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: qiancai, lilin90, ti-chi-bot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	标题准确概括了为系统变量 tidb_paging_size_bytes 补充文档说明这一主要变更。
Description check	✅ Passed	描述包含变更内容、适用版本和相关链接，整体符合模板要求。

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

JmPotato · 2026-07-17T15:41:51Z

/hold

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 <github@ipotato.me>

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b5f43bb2-0ded-4640-acda-39baa662020c

📥 Commits

Reviewing files that changed from the base of the PR and between 684e35b and 201b47f.

📒 Files selected for processing (1)

system-variables.md

coderabbitai · 2026-07-24T08:54:46Z

+- 类型：整数型
+- 默认值：`0`
+- 范围：`[0, 9223372036854775807]`


🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

将变量类型标注为无符号整数型。

PR 目标明确该变量为 unsigned，但当前文档写成“整数型”，容易让读者误以为支持负值；这也与 [0, 9223372036854775807] 的范围不一致。

Suggested change

- 类型：整数型

- 默认值：`0`

- 范围：`[0, 9223372036854775807]`

- 类型：无符号整数型

system-variables: add tidb_paging_size_bytes (internal use)

0a4e26f

Signed-off-by: JmPotato <github@ipotato.me>

ti-chi-bot Bot added missing-translation-status This PR does not have translation status info. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jul 1, 2026

qiancai self-assigned this Jul 10, 2026

qiancai added the translation/doing This PR’s assignee is translating this PR. label Jul 10, 2026

ti-chi-bot Bot removed the missing-translation-status This PR does not have translation status info. label Jul 10, 2026

qiancai reviewed Jul 14, 2026

View reviewed changes

qiancai approved these changes Jul 14, 2026

View reviewed changes

ti-chi-bot Bot added the needs-1-more-lgtm Indicates a PR needs 1 more LGTM. label Jul 14, 2026

qiancai added the v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3. label Jul 14, 2026

ti-chi-bot Bot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jul 17, 2026

system-variables: restore tidb_paging_size_bytes default to 0

201b47f

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 <github@ipotato.me>

coderabbitai Bot reviewed Jul 24, 2026

View reviewed changes

	- 该变量是 TiDB 内部使用的变量，不推荐修改该变量的值。
	- 该变量为 TiDB 内部变量，不推荐修改该变量的值。

Uh oh!

Conversation

JmPotato commented Jul 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

Summary by CodeRabbit

Uh oh!

qiancai Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

JmPotato Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

qiancai left a comment

Choose a reason for hiding this comment

Uh oh!

qiancai Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

qiancai Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

JmPotato Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

ti-chi-bot Bot commented Jul 14, 2026

[LGTM Timeline notifier]

Uh oh!

qiancai commented Jul 14, 2026

Uh oh!

ti-chi-bot Bot commented Jul 17, 2026

Uh oh!

coderabbitai Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

JmPotato commented Jul 17, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JmPotato commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 17, 2026 •

edited

Loading