Add docs for Analyze Embedded in DDL and new system variable #21031

AilinKid · 2025-10-28T16:48:20Z

First-time contributors' checklist

I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added or deleted? (Required)

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 (in Chinese).

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

This PR is translated from:
Other reference link(s):

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

Signed-off-by: AilinKid <[email protected]>

ddl_embedded_analyze.md

Signed-off-by: AilinKid <[email protected]>

ti-chi-bot · 2025-10-29T03:32:08Z

[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 hfxsd. 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.

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

Copilot

Pull Request Overview

This PR introduces documentation for the DDL Embedded Analyze optimization feature in TiDB v8.5.4. The feature allows DDL operations involving index creation or reorganization to automatically trigger inline statistics analysis.

Key Changes:

Adds a new system variable tidb_stats_update_during_ddl to control DDL embedded analyze behavior
Creates comprehensive documentation explaining DDL Embedded Analyze optimization for ADD INDEX and column modification operations
Includes practical SQL examples demonstrating the feature for both new index creation and existing index reorganization scenarios

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
system-variables.md	Adds documentation for the new `tidb_stats_update_during_ddl` system variable introduced in v8.5.4
ddl_embedded_analyze.md	New documentation file explaining DDL Embedded Analyze optimization with detailed examples for index creation and column modification operations

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ddl_embedded_analyze.md

Co-authored-by: Copilot <[email protected]>

Co-authored-by: Weizhen Wang <[email protected]>

ddl_embedded_analyze.md

Signed-off-by: AilinKid <[email protected]>

ddl_embedded_analyze.md

Signed-off-by: AilinKid <[email protected]>

ti-chi-bot · 2025-10-30T10:17:25Z

@hawkingrei: adding LGTM is restricted to approvers and reviewers in OWNERS files.

In response to this:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

AilinKid · 2025-10-30T10:17:33Z

@hfxsd can this be merged before Fri? one of the big customer wait for this document in v8.5.4

ddl_embedded_analyze.md

system-variables.md

ddl_embedded_analyze.md

tangenta · 2025-10-30T11:02:06Z

ddl_embedded_analyze.md

应该重点介绍需要开启这个变量的使用场景；演示的话 create index 和 modify column 选一个展示效果比较好。

在开头加了一个场景背景章节

Updated SQL code snippets in ddl_embedded_analyze.md to use consistent uppercase keywords and improved formatting. This enhances readability and aligns with common SQL style conventions.

ddl_embedded_analyze.md

system-variables.md

ddl_embedded_analyze.md

Co-authored-by: Grace Cai <[email protected]>

system-variables.md

qiancai

Rest LGTM

ddl_embedded_analyze.md

ti-chi-bot · 2025-11-05T06:53:54Z

[LGTM Timeline notifier]

Timeline:

2025-10-31 06:56:35.821661885 +0000 UTC m=+1632501.898914465: ☑️ agreed by tangenta.
2025-11-05 06:53:53.861156869 +0000 UTC m=+253083.304186738: ☑️ agreed by qiancai.

Co-authored-by: Grace Cai <[email protected]>

system-variables.md

ddl_embedded_analyze.md

Co-authored-by: xixirangrang <[email protected]>

Co-authored-by: Grace Cai <[email protected]>

ddl_embedded_analyze.md

Co-authored-by: Grace Cai <[email protected]>

qiancai · 2025-11-07T10:13:21Z

ddl_embedded_analyze.md

+
+- 在索引可见前开始进行统计信息收集。
+- 若 Analyze 超时，[`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md) 和 [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) 将不会同步等待 Analyze 完成，而是继续执行后续流程，使索引提前对用户可见。这意味着，该新索引的统计信息会在 Analyze 异步完成后更新。
+


Suggested change

示例：

.

89a00aa

Signed-off-by: AilinKid <[email protected]>

ti-chi-bot bot added missing-translation-status This PR does not have translation status info. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Oct 28, 2025

AilinKid commented Oct 28, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

Update ddl_embedded_analyze.md

3b75acc

hfxsd added translation/doing This PR’s assignee is translating this PR. and removed missing-translation-status This PR does not have translation status info. labels Oct 29, 2025

hfxsd self-assigned this Oct 29, 2025

hfxsd added the type/compatibility-or-feature-change This PR involves compatibility changes or feature behavior changes. label Oct 29, 2025

qiancai added the needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. label Oct 29, 2025

.

c59cb36

Signed-off-by: AilinKid <[email protected]>

hawkingrei requested a review from Copilot October 29, 2025 09:19

Copilot AI reviewed Oct 29, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

hawkingrei reviewed Oct 29, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

AilinKid and others added 2 commits October 29, 2025 17:56

Update ddl_embedded_analyze.md

46e3d4e

Co-authored-by: Copilot <[email protected]>

Update ddl_embedded_analyze.md

42621e0

Co-authored-by: Weizhen Wang <[email protected]>

AilinKid commented Oct 29, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

Update ddl_embedded_analyze.md

b638fdb

tangenta reviewed Oct 30, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

.

a0f8d4f

Signed-off-by: AilinKid <[email protected]>

AilinKid closed this Oct 30, 2025

AilinKid reopened this Oct 30, 2025

tangenta reviewed Oct 30, 2025

View reviewed changes

ddl_embedded_analyze.md Show resolved Hide resolved

./

7471ab1

Signed-off-by: AilinKid <[email protected]>

hawkingrei approved these changes Oct 30, 2025

View reviewed changes

tangenta reviewed Oct 30, 2025

View reviewed changes

hfxsd added 2 commits November 3, 2025 10:07

Standardize SQL syntax in documentation examples

ab5b411

Updated SQL code snippets in ddl_embedded_analyze.md to use consistent uppercase keywords and improved formatting. This enhances readability and aligns with common SQL style conventions.

Update ddl_embedded_analyze.md

01f0cb5

hfxsd requested a review from qiancai November 5, 2025 02:14

qiancai reviewed Nov 5, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

AilinKid and others added 3 commits November 5, 2025 11:44

Update ddl_embedded_analyze.md

a57db17

Co-authored-by: Grace Cai <[email protected]>

Update ddl_embedded_analyze.md

6839a74

Co-authored-by: Grace Cai <[email protected]>

Apply suggestions from code review

164f671

Co-authored-by: Grace Cai <[email protected]>

hfxsd reviewed Nov 5, 2025

View reviewed changes

system-variables.md Outdated Show resolved Hide resolved

Update system-variables.md

fe97ece

qiancai approved these changes Nov 5, 2025

View reviewed changes

ddl_embedded_analyze.md Show resolved Hide resolved

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

ddl_embedded_analyze.md Show resolved Hide resolved

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

ti-chi-bot bot added lgtm and removed needs-1-more-lgtm Indicates a PR needs 1 more LGTM. labels Nov 5, 2025

Apply suggestions from code review

1f934b4

Co-authored-by: Grace Cai <[email protected]>

qiancai reviewed Nov 5, 2025

View reviewed changes

system-variables.md Outdated Show resolved Hide resolved

hfxsd reviewed Nov 5, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

AilinKid and others added 2 commits November 5, 2025 17:02

Update ddl_embedded_analyze.md

bb2c97a

Co-authored-by: xixirangrang <[email protected]>

Update system-variables.md

332847c

Co-authored-by: Grace Cai <[email protected]>

hfxsd approved these changes Nov 5, 2025

View reviewed changes

qiancai reviewed Nov 6, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

qiancai reviewed Nov 6, 2025

View reviewed changes

ddl_embedded_analyze.md Outdated Show resolved Hide resolved

Apply suggestions from code review

4db08aa

Co-authored-by: Grace Cai <[email protected]>

hfxsd changed the title ~~add ddl embedded analyze related document.~~ Add docs for DDL-embedded Analyze and new system variable Nov 6, 2025

hfxsd mentioned this pull request Nov 6, 2025

Add docs for Analyze Embedded in DDL and new system variable pingcap/docs#22014

Open

14 tasks

hfxsd changed the title ~~Add docs for DDL-embedded Analyze and new system variable~~ Add docs for Analyze Embedded in DDL and new system variable Nov 6, 2025

hfxsd added translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR. and removed translation/doing This PR’s assignee is translating this PR. labels Nov 6, 2025

Update ddl_embedded_analyze.md

12e9b54

qiancai reviewed Nov 7, 2025

View reviewed changes


		- 在索引可见前开始进行统计信息收集。
		- 若 Analyze 超时，[`MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md) 和 [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) 将不会同步等待 Analyze 完成，而是继续执行后续流程，使索引提前对用户可见。这意味着，该新索引的统计信息会在 Analyze 异步完成后更新。

Add docs for Analyze Embedded in DDL and new system variable #21031

Are you sure you want to change the base?

Add docs for Analyze Embedded in DDL and new system variable #21031

Conversation

AilinKid commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

First-time contributors' checklist

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)?

Do your changes match any of the following descriptions?

Uh oh!

Uh oh!

ti-chi-bot bot commented Oct 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ti-chi-bot bot commented Oct 30, 2025

Uh oh!

AilinKid commented Oct 30, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tangenta Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

AilinKid Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qiancai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ti-chi-bot bot commented Nov 5, 2025

[LGTM Timeline notifier]

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qiancai Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

AilinKid commented Oct 28, 2025 •

edited

Loading