pingcap / pingcap/tidb

Support auto pre-splitting hot index regions before add-index backfill

Open
#69,399 5 comments 0 reactions 0 assignees View on GitHub
type/enhancement
Dominant language
Go
Stars
40.5k
Forks
6.2k
PR merge metrics
PR metrics pending

Description

## Feature Request

**Is your feature request related to a problem? Please describe:**

TiDB supports manually pre-splitting index regions for add-index jobs through `PRE_SPLIT_REGIONS`. However, users or support engineers must understand the expected index-key distribution, estimate suitable split boundaries, and specify them before the DDL job starts.

Without suitable pre-splitting, writes to the new index keyspace can initially be concentrated in only a few TiKV Regions or stores. The affected write path depends on the add-index reorganization mode:

- In txn reorg, backfill and concurrent DML write the normal index keyspace.
- In ingest and txn-merge reorg, concurrent DML writes the temporary index keyspace while historical backfill writes the normal index keyspace.

The existing manual `PRE_SPLIT_REGIONS` behavior splits the normal index keyspace in txn reorg and the temporary index keyspace in ingest or txn-merge reorg. Users currently have no statistics-driven way to derive those manual split boundaries automatically.

Users also need a SQL-visible way to inspect whether automatic pre-splitting was applied, skipped, unsupported, or failed, instead of relying only on TiDB logs.

**Describe the feature you'd like:**

Add an opt-in automatic index-region pre-split feature for add-index jobs on non-partitioned tables. When the feature is enabled and the user has not explicitly specified `PRE_SPLIT_REGIONS`, TiDB should use available statistics to derive a bounded split plan from hot TopN values of the leading indexed column.

Automatic pre-splitting must preserve the target-keyspace behavior of explicit `PRE_SPLIT_REGIONS`:

- txn reorg: split the normal index keyspace;
- ingest or txn-merge reorg: split the temporary index keyspace used by concurrent DML.

The feature should:

1. Preserve existing manual behavior. An explicitly specified `PRE_SPLIT_REGIONS` option takes precedence over automatic pre-splitting.
2. Capture the session setting in the DDL job so owner changes and retries use the value from submission time.
3. Use only reliable, sufficiently healthy statistics and keep the number of generated split keys bounded.
4. Use the leading indexed column's TopN values. Later-column split planning is out of scope because ordinary column statistics do not describe their conditional distribution under each leading-column value.
5. Skip partitioned tables conservatively instead of planning per-partition or global-index split keys.
6. Be best-effort. Planning, splitting, scattering, or unsupported storage must not cancel the add-index job.
7. Expose the per-index automatic pre-split result in the `COMMENT` column of `SHOW DDL JOBS`.

The SQL-visible result should identify the affected index and show whether automatic pre-splitting was applied, skipped, unsupported, or failed. When available, it should include split-key, split-Region, and scattered-Region counts, plus the reason for a skipped or failed attempt.

Non-goals:

- This feature does not change the established manual `PRE_SPLIT_REGIONS` target-keyspace semantics.
- In ingest and txn-merge reorg, it does not additionally pre-split the normal/final index keyspace used by historical backfill.
- It does not replace ingest's own Region management during SST import.
- It does not derive split boundaries by scanning user table data.

**Describe alternatives you've considered:**

- Continue requiring users to specify `PRE_SPLIT_REGIONS` manually. This remains available and takes precedence, but requires workload-specific knowledge before the DDL starts.
- Split both the normal and temporary index keyspaces in fast reorg. This would expand the behavior beyond existing manual pre-split semantics and is not part of this feature.
- Read table data to derive multi-column conditional distributions. This would add significant complexity and I/O before backfill, so the proposed implementation uses leading-column statistics only.

**Teachability, Documentation, Adoption, Migration Strategy:**

The feature is disabled by default and enabled through a `GLOBAL | SESSION` system variable. Existing DDL behavior is unchanged when the variable is OFF or when the statement contains an explicit `PRE_SPLIT_REGIONS` option.

Documentation should explain the mode-specific target keyspace:

- txn reorg pre-splits the normal index;
- ingest and txn-merge reorg pre-split the temporary index used by concurrent DML;
- fast reorg does not gain an additional normal-index pre-split from this feature.

Examples of `SHOW DDL JOBS` comments:

```text
auto_split_hot_region=idx(split, split_keys=3, split_regions=3, scattered_regions=2)
auto_split_hot_region=idx(skipped, reason="stats pseudo")
auto_split_hot_region=idx(skipped, reason="partitioned table")
```

Contributor guide

Open the contributing guide

Research direction

Start by tracing the existing PRE_SPLIT_REGIONS handling for add-index jobs and the code that produces SHOW DDL JOBS COMMENT output. Then inspect how txn, ingest, and txn-merge reorg modes select their target keyspace and how index statistics expose leading-column TopN values. Done means an opt-in, bounded, best-effort plan with manual-option precedence and per-index applied, skipped, unsupported, or failed status visible in SHOW DDL JOBS.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.