statistics: add docs for the FLUSH STATS_DELTA statement (#21819)

[ti-chi-bot]

This is an automated cherry-pick of #21819

What is changed, added or deleted? (Required)

Add documentation for the FLUSH STATS_DELTA statement introduced in v8.5.7 and v9.0.0 (pingcap/tidb#65668), which persists the pending statistics delta buffered in TiDB memory to the mysql.stats_meta system table immediately.

• Add a new page: sql-statements/sql-statement-flush-stats-delta.md (synopsis, options, examples, privileges).
• Add the statement to TOC.md and sql-statements/sql-statement-overview.md.
• Cross-link the statement from the "Automatic update" section in statistics.md.

All examples and behavior descriptions (target scopes, CLUSTER broadcast, privilege requirements, and warnings) are verified against a TiDB v8.5.7 TiUP playground with two TiDB instances.

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

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)

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

• This PR is translated from: statistics: add docs for the FLUSH STATS_DELTA statement docs#23258
• Other reference link(s): planner: support flush stats_delta syntax for optimizer statistics tidb#65677, planner, executor, parser: implement scoped FLUSH STATS_DELTA tidb#67766, planner, executor, parser: support scoped FLUSH STATS_DELTA tidb#68159

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

Summary by CodeRabbit

• 新功能

  • 新增 FLUSH STATS_DELTA SQL 语句文档，涵盖语法、适用对象、集群级操作、分区表行为、权限要求及使用示例。
  • 该语句可立即将待持久化的统计信息 delta 写入系统表。

• 文档

  • 将语句添加至 SQL 目录、语句总览及统计信息管理文档。
  • 更新 v8.5.7 发布说明，明确其集群级范围及统计信息 delta 的相关描述。

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

新增 FLUSH STATS_DELTA SQL 参考文档，说明语法、刷新范围、执行行为、权限和兼容性，并更新目录、统计信息说明及 8.5.7 发布说明。

Changes

FLUSH STATS_DELTA 文档

Layer / File(s)	Summary
新增 SQL 参考文档 sql-statements/sql-statement-flush-stats-delta.md	新增 FLUSH STATS_DELTA 的语法、目标类型、集群刷新、去重、分区表处理、警告、示例、权限和 MySQL 兼容性说明。
接入文档导航和版本说明 TOC.md, sql-statements/sql-statement-overview.md, statistics.md, releases/release-8.5.7.md	在相关目录和统计信息说明中增加 FLUSH STATS_DELTA，并更新 8.5.7 发布说明中的范围和术语。

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

Suggested labels: type/enhancement

Suggested reviewers: qiancai

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题准确概括了新增 FLUSH STATS_DELTA 文档这一主要变更，内容简洁且明确。
Description check	✅ Passed	描述已说明变更内容、适用版本和相关链接，且涵盖主要文档变更与验证信息。
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.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a522fe99-265d-4139-8498-6720e34bc3d2

📥 Commits

Reviewing files that changed from the base of the PR and between 99d8d74 and 29b0aee.

📒 Files selected for processing (5)

• TOC.md
• releases/release-8.5.7.md
• sql-statements/sql-statement-flush-stats-delta.md
• sql-statements/sql-statement-overview.md
• statistics.md

[qiancai]

/approve

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: qiancai

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [qiancai]

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

[coderabbitai]

♻️ Duplicate comments (1)

sql-statements/sql-statement-flush-stats-delta.md (1)

71-71: ⚠️ Potential issue | 🟡 Minor

补充 stats-lease = 0s 时的加载行为。

当 stats-lease 为 0s 时，TiDB 仍会每隔 3s 从系统表加载统计信息并更新内存缓存；当前文案没有说明这个例外。官方配置文档明确了该行为。 (docs.pingcap.com)

请将 Line 71 替换为以下文本：

此时，TiDB 已将该表的行数变化持久化到 `mysql.stats_meta` 系统表。你可以使用 `SHOW STATS_META` 查看已持久化的值。注意，`SHOW STATS_META` 会从你当前连接的 TiDB 节点内存中读取统计信息。该 TiDB 节点会每隔 [`stats-lease`](/tidb-configuration-file.md#stats-lease) 时间（默认 `3s`）加载已持久化的值；当 `stats-lease` 为 `0s` 时，会以 `3s` 的时间间隔加载。因此，刷新后的值可能会在短暂延迟后才显示在输出中：

As per path instructions，**/*.md 文件中的连续行可以安全替换时，必须提供精确的 GitHub 可提交建议。

Source: Path instructions

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 27aa6491-a2bb-431a-a3fd-5958458ba44f

📥 Commits

Reviewing files that changed from the base of the PR and between 760e039 and 25ffa47.

📒 Files selected for processing (2)

• sql-statements/sql-statement-flush-stats-delta.md
• statistics.md