Document the asynchronous preparation flow of IMPORT INTO on TiDB X

[D3Hunter]

What is changed, added, or deleted? (Required)

Document the asynchronous preparation flow that IMPORT INTO ... FROM FILE uses on TiDB X (NextGen) deployments, and correct the job phase list and the Source_File_Size description of SHOW IMPORT JOB(s).

On TiDB X, an IMPORT INTO ... FROM FILE job is created first and then prepared in the background: TiDB lists the source files that match fileLocation, detects the file format when the FORMAT clause is omitted, calculates resource-related parameters such as the import concurrency, and splits the source files into chunks for parallel processing. Until the preparation succeeds, the job is in the preparing phase and Source_File_Size is N/A. For a large single-table import, such as an import of tens of TiB, the preparing phase can take a noticeable amount of time even when the statement is executed with the DETACHED option, and no data is imported during this period. To avoid misoperations during this period, the new note tells users to check the job phase before taking any action on the job, such as canceling it. Starter instances prepare import jobs synchronously, so the new section states that the preparing phase is not shown for them.

The new section is wrapped in <CustomContent platform="tidb-cloud" plan="starter,essential,premium">, because the asynchronous preparation flow exists only in the NextGen kernel, which TiDB X instances run.

Changed files:

• sql-statements/sql-statement-import-into.md: add a ### Asynchronous preparation section between ### Global Sort and ### Output.
• sql-statements/sql-statement-show-import-job.md: correct the Phase list to preparing, global-sorting, importing, resolving-conflicts, and validating (add-index is not an IMPORT INTO job phase), and document the N/A value of Source_File_Size.

Validation on the changed files:

• ./scripts/markdownlint sql-statements/sql-statement-import-into.md sql-statements/sql-statement-show-import-job.md
• python3 scripts/check-tags.py sql-statements/sql-statement-import-into.md sql-statements/sql-statement-show-import-job.md
• python3 scripts/check-manual-line-breaks.py sql-statements/sql-statement-import-into.md sql-statements/sql-statement-show-import-job.md
• ./node_modules/.bin/remark -u lint -u @breeswish-org/remark-lint-pingcap-docs-anchor sql-statements/sql-statement-import-into.md sql-statements/sql-statement-show-import-job.md --frail --quiet
• ./node_modules/.bin/markdown-link-check --config <generated from scripts/markdown-link-check.tpl> <changed files>

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

• Related code change PR links (if applicable):
  • importinto: integrate async prepare flow for nextgen tidb#68668
  • dxf: add StepPrepared prepare-mode transition in scheduler framework tidb#68581
  • importinto, config: use synchronous prepare and add default max import size for Starter tidb#70511
• This PR is translated from:
• Other reference link(s):
  • IMPORT INTO nextgen: add Init->Prepared async prepare flow (prepare_mode) tidb#68580

AI agent involvement

• The changes in this PR were primarily made by an AI agent on behalf of the PR author.

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

• Documentation
  • Documented asynchronous preparation for IMPORT INTO ... FROM FILE on TiDB Cloud platforms.
  • Clarified job phases, including preparing, and how to monitor progress with SHOW IMPORT JOB(S).
  • Explained that source file size may display as N/A while preparation is in progress.
  • Added guidance on preparation times and platform-specific behavior.

[ti-chi-bot]

[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 assign tangenta for approval. 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]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

📝 Walkthrough

Walkthrough

The documentation adds asynchronous preparation details for TiDB Cloud imports. It documents the preparing phase, DETACHED behavior, starter-instance differences, preparation delays, and updated SHOW IMPORT output fields.

Changes

Import preparation documentation

Layer / File(s)	Summary
Asynchronous preparation and status reporting sql-statements/sql-statement-import-into.md, sql-statements/sql-statement-show-import-job.md	The documentation describes background preparation, preparing status checks, N/A source-file size reporting, preparation time for large imports, and synchronous preparation on .starter instances. The SHOW IMPORT phase list is updated.

Priority: ⬇️ Low

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

Change: Other

Merge Risk: 🟡 Moderate · up to 25d51

The import documentation incorrectly describes Global Sort as universal for plans where it is unavailable. Correct the opening statement before merging to avoid misleading import configuration decisions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting asynchronous preparation for IMPORT INTO on TiDB X.
Description check	✅ Passed	The description is complete and follows the repository template. It explains the changes, affected version, related links, AI involvement, scope, and validation steps. The optional first-time contribu…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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

🧪 Generate unit tests (beta)

• Create a new PR

---

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: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: pingcap/docs/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e5df805e-0ab4-4b3f-af35-471b5992f9ba

📥 Commits

Reviewing files that changed from the base of the PR and between e24d9f6 and 25d51af.

📒 Files selected for processing (2)

• sql-statements/sql-statement-import-into.md
• sql-statements/sql-statement-show-import-job.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

sed -n '180,270p' sql-statements/sql-statement-import-into.md
rg -n -i 'global sort|starter|essential|premium' sql-statements/sql-statement-import-into.md

Repository: pingcap/docs

Length of output: 14540

---

Scope the Global Sort statement to asynchronous-preparation instances.

The section applies to Starter, Essential, and Premium instances. Global Sort is unavailable on Starter and Essential, and Starter uses synchronous preparation. Replace the incorrect universal Global Sort claim with asynchronous-preparation wording.

Suggested wording

-On TiDB X instances, `IMPORT INTO ... FROM FILE` uses [Global Sort](`#global-sort`). TiDB creates the import job first and then prepares it asynchronously in the background. The preparation work includes:
+On TiDB X instances that use asynchronous preparation, `IMPORT INTO ... FROM FILE` creates the import job first and then prepares it asynchronously in the background. The preparation work includes:

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	On TiDB X instances, `IMPORT INTO ... FROM FILE` uses [Global Sort](#global-sort). TiDB creates the import job first and then prepares it asynchronously in the background. The preparation work includes:
	On TiDB X instances that use asynchronous preparation, `IMPORT INTO ... FROM FILE` creates the import job first and then prepares it asynchronously in the background. The preparation work includes: