Skip to content

dxf: document ADD INDEX disk space precheck #23190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
expxiaoli wants to merge 3 commits into
base: master
Choose a base branch
from
+43 −1
Open

dxf: document ADD INDEX disk space precheck #23190

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a70796d
master: document DXF add index disk space precheck
expxiaoli Jul 2, 2026
e83348e
master: address DXF add index precheck review comments
expxiaoli Jul 2, 2026
eba6f23
master: clarify ADD INDEX disk precheck scope
expxiaoli Jul 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions system-variable-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,13 @@ Referenced in:
- [System Variables](/system-variables.md#error_count)
- [TiDB 2.1 RC1 Release Notes](/releases/release-2.1-rc.1.md)

### enforce_disk_space_precheck_before_add_index

Referenced in:

- [System Variables](/system-variables.md#enforce_disk_space_precheck_before_add_index)
- [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md#tikv-disk-space-precheck-for-add-index-tasks)

### foreign_key_checks

Referenced in:
Expand Down
11 changes: 11 additions & 0 deletions system-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,17 @@ For more possible values of this variable, see [Authentication plugin status](/s
- Default value: `0`
- A read-only variable that indicates the number of errors that resulted from the last statement that generated messages.

### enforce_disk_space_precheck_before_add_index

- Scope: GLOBAL
- Persists to cluster: Yes
- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
- Type: Boolean
- Default value: `OFF`
- This variable controls whether TiDB rejects a DXF [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) task when the TiKV disk space precheck predicts insufficient TiKV capacity.

@wjhuang2016 wjhuang2016 Jul 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only apply to DXF?

@expxiaoli expxiaoli Jul 3, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will apply to both DXF and classic. Should I write doc now that it will apply for both envs?

- When the value is `OFF`, TiDB still performs the precheck and logs warnings for insufficient TiKV capacity, but it does not reject the DDL job.
- When the value is `ON`, TiDB rejects the DDL job if the precheck predicts insufficient TiKV capacity and the prediction uses non-pseudo table statistics. If the prediction uses pseudo statistics, TiDB logs a warning and does not reject the DDL job. For more information, see [TiKV disk space precheck for `ADD INDEX` tasks](/tidb-distributed-execution-framework.md#tikv-disk-space-precheck-for-add-index-tasks).

@gemini-code-assist gemini-code-assist Bot Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

To maintain consistency with the rest of the documentation, use the term 'non-pseudo statistics' instead of 'non-pseudo table statistics'.

Suggested change
- When the value is `ON`, TiDB rejects the DDL job if the precheck predicts insufficient TiKV capacity and the prediction uses non-pseudo table statistics. If the prediction uses pseudo statistics, TiDB logs a warning and does not reject the DDL job. For more information, see [TiKV disk space precheck for `ADD INDEX` tasks](/tidb-distributed-execution-framework.md#tikv-disk-space-precheck-for-add-index-tasks).
- When the value is `ON`, TiDB rejects the DDL job if the precheck predicts insufficient TiKV capacity and the prediction uses non-pseudo statistics. If the prediction uses pseudo statistics, TiDB logs a warning and does not reject the DDL job. For more information, see [TiKV disk space precheck for `ADD INDEX` tasks](/tidb-distributed-execution-framework.md#tikv-disk-space-precheck-for-add-index-tasks).
References
  1. Use consistent terminology. (link)


### foreign_key_checks

- Scope: SESSION | GLOBAL
Expand Down
21 changes: 20 additions & 1 deletion tidb-distributed-execution-framework.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,25 @@
* [`tidb_ddl_error_count_limit`](/system-variables.md#tidb_ddl_error_count_limit)
* [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size): use the default value. The recommended maximum value is `1024`.

## TiKV disk space precheck for `ADD INDEX` tasks

For [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) tasks executed by the DXF, TiDB collects a TiKV capacity snapshot before submitting the distributed task, predicts the TiKV index size based on block sampling, table statistics, and the replica count, and then checks whether TiKV has enough remaining disk space for the task. This precheck applies to both local sort and Global Sort execution paths.

Check warning on line 94 in tidb-distributed-execution-framework.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Ambiguous] Consider using a clearer word than 'enough' because it may cause confusion.

Raw Output:
{"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'enough' because it may cause confusion.", "location": {"path": "tidb-distributed-execution-framework.md", "range": {"start": {"line": 94, "column": 297}}}, "severity": "INFO"}

TiDB considers TiKV disk space insufficient if either of the following conditions is met:

@gemini-code-assist gemini-code-assist Bot Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Simplify the sentence and avoid passive voice ('is met') by using 'in either of the following cases:'.

Suggested change
TiDB considers TiKV disk space insufficient if either of the following conditions is met:
TiDB considers TiKV disk space insufficient in either of the following cases:
References
  1. Avoid passive voice overuse and unnecessary words. (link)


- After subtracting the predicted index size, the remaining TiKV cluster capacity is less than 20% of the total TiKV cluster capacity.
- After subtracting the per-store predicted index size, the remaining capacity of any TiKV store is less than 15% of that store's total capacity.

By default, [`enforce_disk_space_precheck_before_add_index`](/system-variables.md#enforce_disk_space_precheck_before_add_index) is `OFF`. In this mode, TiDB logs a warning if the precheck predicts insufficient TiKV capacity, but it still submits the DDL job. To reject such DDL jobs before task submission, set this variable to `ON`:

```sql
SET GLOBAL enforce_disk_space_precheck_before_add_index = ON;
```

When this variable is `ON`, TiDB rejects the DDL job only if the prediction uses non-pseudo table statistics. If the prediction uses pseudo statistics, TiDB logs a warning and does not reject the DDL job. If TiDB cannot collect the TiKV capacity snapshot or complete the prediction within 5 seconds, TiDB logs a warning, skips the precheck, and continues to submit the DDL job.

@gemini-code-assist gemini-code-assist Bot Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Improve clarity and conciseness by changing 'non-pseudo table statistics' to 'non-pseudo statistics' for consistency, replacing the repetitive use of 'TiDB' with 'it', and simplifying 'continues to submit' to 'submits'.

Suggested change
When this variable is `ON`, TiDB rejects the DDL job only if the prediction uses non-pseudo table statistics. If the prediction uses pseudo statistics, TiDB logs a warning and does not reject the DDL job. If TiDB cannot collect the TiKV capacity snapshot or complete the prediction within 5 seconds, TiDB logs a warning, skips the precheck, and continues to submit the DDL job.
When this variable is `ON`, TiDB rejects the DDL job only if the prediction uses non-pseudo statistics. If the prediction uses pseudo statistics, TiDB logs a warning and does not reject the DDL job. If TiDB cannot collect the TiKV capacity snapshot or complete the prediction within 5 seconds, it logs a warning, skips the precheck, and submits the DDL job.
References
  1. Use consistent terminology and avoid unnecessary words and repetition. (link)


To observe the predicted and actual TiKV storage usage of a DXF `ADD INDEX` task, check the TiDB logs. TiDB logs prediction fields such as `block_sample_predicted_tikv_index_all_replica_bytes`, `block_sample_predicted_tikv_index_single_replica_bytes`, and `block_sample_mvcc_overhead_total_bytes` at task submission time. After the task succeeds, TiDB also logs fields such as `logical_index_kv_bytes`, `ingested_sst_bytes`, `ingested_sst_bytes_source`, and `ingested_sst_bytes_reliable`.

## Task scheduling

By default, the DXF schedules all TiDB nodes to execute distributed tasks. Starting from v7.4.0, for TiDB Self-Managed clusters, you can control which TiDB nodes can be scheduled by the DXF to execute distributed tasks by configuring [`tidb_service_scope`](/system-variables.md#tidb_service_scope-new-in-v740).
Expand Down Expand Up @@ -128,4 +147,4 @@

* [Execution Principles and Best Practices of DDL Statements](https://docs.pingcap.com/tidb/stable/ddl-introduction)

</CustomContent>
</CustomContent>