Understanding Shard Splitting Constraints

Elasticsearch indexes are designed with immutable shard counts after creation. To increase storage capacity or improve performance, shard splitting provdies a method to generate a new index with a higher shard count.

Prerequisites and Configuration

Before splitting, ensure the cluster allows shard allocation and rebalancing. This configuration typically needs to be set once per cluster.

PUT _cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all",
    "cluster.routing.allocation.cluster_concurrent_rebalance": 4,
    "cluster.routing.allocation.node_concurrent_recoveries": 4,
    "cluster.routing.allocation.allow_rebalance": "indices_primaries_active",
    "cluster.routing.rebalance.enable": "all",
    "indices.recovery.max_bytes_per_sec": "500mb"
  }
}

Step-by-Step Splitting Procedure

1. Block Writes to Source Index Prevent data modifications on the original index before splitting.

   PUT original_index/_settings
   {
     "index.blocks.write": true
   }
   

2. Execute Split Operation Create a new index with an increased shard count. The new shard count must be an integer multiple of the original count and a divisor of 640.

   POST original_index/_split/target_index
   {
     "settings": {
       "index.number_of_shards": 40
     }
   }
   

3. Verify New Index Creation Check the status of the newly created index.

   GET /_cat/indices/target_index?v
   

4. Enable Writes on Target Index Remove the write block to allow data ingestion.

   PUT target_index/_settings
   {
     "index.blocks.write": null
   }
   

5. Monitor Index Health Wait for the new index to reach a green health status.

   GET /_cat/indices/target_index?v
   

6. Check Cluster Health Ensure the entire cluster returns to a grean state.

   GET /_cluster/health
   

Post-Split Cleanup

After verifying the target index is operational, the original index can be deleted.

DELETE original_index

Common Error Conditions

• Invalid Shard Count: Splitting from 10 shards to 22 fails because 10 is not a factor of 22.
• Routing Shard Constraint: Attempting to split to 30 shards may fail if it is not a divisor of the routing shards limit (640).
• Write Block Not Set: The source index must be set to read-only before splitting. The error message will indicate: index must be read-only to resize index.