RAFTSTORE 604: Region Split

A Region owns a continuous interval of the keyspace. A split divides that interval into two independent Regions. The resulting Regions have separate ranges, identities, Raft groups, and leaders. PD can schedule them independently afterward.

Suppose Region 10 owns [a, z) and TiKV chooses m as the split key:

before

Region 10: [a, z)

after

left:  [a, m)
right: [m, z)

A write to a key below m belongs to the left Region; a write to a key at or above m belongs to the right Region.

Region IDs and Epochs

The two resulting Regions need separate identities. PD allocates the new Region ID and the peer IDs for the new Region. For an automatic split, TiKV first asks PD for these IDs before proposing the split. PD acts as the cluster-wide allocator; TiKV does not invent the IDs locally.

TiKV uses a right-derived split by default. The right Region keeps the original Region ID and its existing peer identities. The left Region receives the new ID and peer IDs from PD:

before

Region 10: [a, z)

right-derived split

Region 20: [a, m)   <- new ID from PD
Region 10: [m, z)   <- original ID and peers

This is useful for workloads with monotonically increasing keys. New writes continue to land in the rightmost Region, so the active Region keeps its ID and peer identities. Its Region epoch still increments because its range changed.

TiKV also supports the opposite, left-derived arrangement. In either case, one side continues the original Region identity while the other becomes a new Region.

A Region also has an epoch, a version in its metadata. TiDB includes the epoch it knows in a request. When a split changes the Region's range, TiKV increments the epoch. A later Region merge also changes its range and increments the epoch; we will return to that later. A request carrying the old epoch is stale, so TiKV rejects it and TiDB refreshes its Region routing information.

The Split Command

A split is a Raft administrative command. The leader proposes it, and the replicas replicate and commit it through the normal Raft path:

leader proposes split command
          |
          v
replicas replicate the command
          |
          v
command commits
          |
          v
every replica applies the same new ranges

The split command is not a user key-value write. It is persisted as a Raft log entry, but applying it does not write a new user value to RocksDB. During apply, TiKV updates the Region metadata stored in RocksDB.

TiKV stores this metadata in a record called RegionLocalState. It describes the Region's key range, peer list, and lifecycle state. For a split, the apply step writes the updated metadata for the original Region and the initial metadata for the new Region.

RegionLocalState is the durable source of truth for the Region topology. If TiKV restarts after the split, it scans these records and reconstructs the two Region peers from them.

When Does a Split Start?

There are two main ways to initiate a split.

PD can request one directly, usually with a split key. This is useful when an operator or a scheduling decision identifies a particular boundary.

More commonly, TiKV detects that a Region has grown too large. A periodic split check first checks the Region's approximate size. This estimate is cheap and avoids scanning a Region that is clearly below the threshold.

If the approximate size exceeds the threshold, TiKV performs an exact scan to find a suitable split key. The scan looks for a key near the middle of the Region's data so that the resulting Regions are reasonably balanced.

The process is therefore:

periodic split check
          |
          v
approximate size exceeds threshold?
          |
          +-- no  -> do nothing
          |
          +-- yes -> scan and find a split key
                         |
                         v
                  ask PD for new IDs
                         |
                         v
                  propose the split command

Applying the Split

When the split command is applied, every replica performs the same metadata change. The original Region's range is shortened, and the new Region's range is created. Both Regions inherit the peer placement of the original Region, so each store receives one peer for each resulting Region.

On each store, the apply system persists the metadata for the resulting Regions in the KV Engine. Because the metadata changes are written together, a restart sees either the old single-Region state or the complete split state, rather than a partially published topology.

After the metadata is persisted, TiKV creates the new Region's in-memory Raft peer. The new peer has its own Region ID, Raft state, and future log. The original and new Regions can now receive writes independently:

key < m       -> left Region's Raft group
key >= m      -> right Region's Raft group

At this point, no key-value data needs to move between stores. Each peer of the original Region already stores data for [a, z), so each resulting peer keeps the portion belonging to its new range.

This is why a split is also the moment when a new Raft peer is born. It creates a new Region identity and Raft state machine over part of the data already held locally.

The detailed races between split, snapshot-based peer creation, and peer destruction are part of the peer lifecycle and are covered later in RAFTSTORE 901: Peer Lifecycle and Crash Recovery. For now, the core picture is enough: a split is a replicated topology change that creates two independent Raft Regions from one key range, while the data remains on the same stores.