Master Easysearch Write Throttling: Node, Shard, and Index Level Controls to Tame Bulk Write Spikes

In large‑scale data scenarios, bulk indexing can generate sudden write spikes that threaten Elasticsearch/Easysearch cluster stability. The author demonstrates how Easysearch (supported from version 1.8.0, verified on 2.0.0) offers dynamic, three‑tier write throttling—node, shard, and index—without requiring a cluster restart.

1. Cluster‑level throttling: Node Throttling

Node throttling limits the write load each data node can accept, controlling overall cluster pressure.

Core parameters

cluster.throttle.node.write (boolean): enable node throttling.

cluster.throttle.node.write.max_bytes (string): maximum write volume per interval (e.g., "50MB").

cluster.throttle.node.write.max_requests (int): maximum number of write requests per interval (e.g., 1000000).

cluster.throttle.node.write.action (string): action when limits are exceeded – retry (re‑try) or drop (reject).

cluster.throttle.node.write.interval (int): evaluation interval in seconds (default 1 s).

Practical DSL: Enable node throttling with retry

PUT _cluster/settings
{
  "transient": {
    "cluster.throttle.node.write": true,
    "cluster.throttle.node.write.max_bytes": "50MB",
    "cluster.throttle.node.write.max_requests": 1000000,
    "cluster.throttle.node.write.action": "retry",
    // "cluster.throttle.node.write.interval": 1 // optional, default 1s
  }
}

Tip: Using the transient block makes the change temporary; it reverts after a restart, which is handy for testing.

In production, the retry action smooths short‑lived spikes, improving write success rates.

2. Cluster‑level throttling: Shard Throttling

Shard throttling applies to individual primary shards, useful for hot‑shard mitigation and I/O bottleneck avoidance. It only counts bulk requests forwarded from the coordinating node to the data node shard.

Practical DSL: Enable shard throttling with drop

PUT _cluster/settings
{
  "transient": {
    "cluster.throttle.shard.write": true,
    "cluster.throttle.shard.write.max_bytes": "50MB",
    "cluster.throttle.shard.write.max_requests": 1000000,
    "cluster.throttle.shard.write.action": "drop"
  }
}

Tip: The drop action immediately rejects excess traffic, protecting cluster resources at the cost of some write requests.

Clients must handle the resulting rejected execution exception and retry if needed.

3. Index‑level throttling

Index throttling lets you limit write traffic for specific business indices while leaving system indices (e.g., .security‑*) untouched, ideal for multi‑tenant or mixed‑workload environments.

Practical DSL: Create an index with throttling settings

PUT test_0
{
  "settings": {
    "number_of_replicas": 1,
    "number_of_shards": 3,
    "index.throttle.write.enable": true,
    "index.throttle.write.max_requests": 6000,
    "index.throttle.write.action": "retry",
    // "index.throttle.write.max_bytes": "10MB", // optional byte limit
    // "index.throttle.write.interval": 1 // optional, default 1s
  }
}

Tip: Index‑level throttling can coexist with node and shard throttling without conflict, providing the most granular traffic control.

4. Summary and Best Practices

Layered throttling

Node, shard, and index throttling can be enabled simultaneously, forming a multi‑layer protection net.

System index exemption

The throttling feature does not affect Easysearch system indices; it only applies to business indices.

Choosing actions

retry : smooths short spikes, suitable when write success is critical, but adds latency.

drop : instantly relieves pressure, suitable when protecting core resources outweighs a few lost writes.

By mastering these three levels of write throttling, you can effectively “traffic‑control” massive bulk write bursts and keep the cluster stable.