The Elasticsearch refresh interval (index.refresh_interval) controls how often a shard exposes newly indexed documents to search. The default is 1 second, which is where the "near real-time" label comes from: a document indexed at time T becomes searchable around T + 1s. Each refresh creates a new in-memory Lucene segment, so refresh frequency is a direct lever on indexing throughput, search freshness, and segment count.
How Refresh Works
When a document is indexed it lands in the in-memory buffer of a shard. It is not searchable yet. A refresh closes the current buffer, opens it as a searchable segment, and starts a new buffer. Refreshes are cheap relative to flushes (they don't fsync to disk), but each refresh produces a new segment, and segments must eventually be merged.
Refresh is separate from flush. Flush writes the translog to disk and commits segments; it's controlled by index.translog.flush_threshold_size (default 512mb). Refresh only makes data visible to search. You can refresh many times between flushes.
index doc -> in-memory buffer -> [refresh] -> new searchable segment -> [merge] -> larger segment -> [flush] -> committed to disk
Refresh Interval Settings
| Setting value | Effect | Use case |
|---|---|---|
1s (default) |
Refresh every 1 second | General-purpose, near real-time search |
30s |
Refresh every 30 seconds | High-throughput ingest where 30s lag is acceptable |
-1 |
Disable scheduled refresh | Bulk reindexing, snapshot restore, big imports |
0 |
Invalid - rejected by Elasticsearch | - |
Change it dynamically without closing the index:
PUT /my-index/_settings
{
"index.refresh_interval": "30s"
}
Disable refreshes entirely during a bulk load and re-enable when done:
PUT /my-index/_settings
{ "index.refresh_interval": "-1" }
# ... bulk index millions of docs ...
PUT /my-index/_settings
{ "index.refresh_interval": "1s" }
POST /my-index/_refresh
A common pitfall: disabling refresh and forgetting to re-enable it. The index stays invisible to search until someone notices.
When to Tune Refresh Interval
The right value depends on whether ingest throughput or search freshness is the bottleneck.
- Increase to 30s-60s for write-heavy workloads (log ingest, metric pipelines, change-data-capture sinks) where users tolerate seconds-to-minute search lag. The throughput gain comes from fewer, larger segments and less work for the merge thread.
- Keep at 1s for interactive search-after-write flows (user posts a comment and expects to see it).
- Use
-1for bulk reindexing and snapshot restores. Re-enable explicitly when done. - Use
?refresh=wait_foron the individual write request when you need the specific document immediately visible without forcing a global refresh - this is cheaper than?refresh=true.
For data streams and time-series indices, you can also tier: hot indices at 1s for live queries, warm/cold rolled-over indices at 30s or longer since they're rarely written to.
Refresh vs Flush vs Merge
These three operations get confused often. They're distinct:
| Operation | What it does | Cost | Trigger |
|---|---|---|---|
| Refresh | Makes new docs searchable (in-memory segment) | Low | index.refresh_interval or _refresh API |
| Flush | Writes translog + commit point to disk | Medium | translog size threshold, periodic |
| Merge | Combines smaller segments into larger ones | High (I/O + CPU) | Background, segment count thresholds |
A short refresh interval makes more segments. More segments make more merge work. More merge work competes with indexing for CPU and I/O. This is the chain that makes 1-second refresh too aggressive on write-heavy clusters.
Monitoring Refresh Performance
Watch refresh time and refresh count via the index stats API:
GET /my-index/_stats/refresh
Key signals:
- High refresh time per refresh (>200ms) indicates the refresh is expensive - usually too much in the in-memory buffer.
- Rising segment count (
segments.countper shard climbing past a few hundred) hints at refresh-driven segment churn outpacing merges. - Indexing throughput dropping after a config change to a shorter interval is a direct signal you over-tuned.
Pulse tracks refresh time, segment count, and merge throughput per shard, and alerts when these get out of balance. Its agentic analysis ties an indexing-latency spike to the underlying cause - whether that's an over-aggressive refresh interval, segment merge pressure, or translog flush thrash - rather than just surfacing the symptom.
Common Refresh Interval Mistakes
- Setting refresh too low (200ms-500ms) hoping to "make search faster." This raises segment count, raises merge pressure, and usually slows search.
- Disabling refresh with
-1and forgetting to re-enable. Index goes silent to search forever. - Using
?refresh=trueon every write in a hot ingest path. Forces a global refresh per request and destroys throughput. - Treating refresh and flush as the same thing. Flush is about durability, refresh is about visibility.
- Ignoring per-tier refresh tuning in time-series workloads. Hot indices need different refresh behavior than cold ones.
Frequently Asked Questions
Q: What is the default refresh interval in Elasticsearch?
A: The default index.refresh_interval is 1s (1 second). Documents indexed at time T become searchable around T + 1s. This default is what gives Elasticsearch its "near real-time" search characterization.
Q: How do I disable refresh in Elasticsearch?
A: Set index.refresh_interval to -1: PUT /my-index/_settings {"index.refresh_interval": "-1"}. Disabling is useful during bulk indexing. Remember to re-enable it afterward or the index stays invisible to search.
Q: What is the difference between refresh and flush in Elasticsearch?
A: Refresh makes recently-indexed documents searchable by opening a new in-memory Lucene segment; it doesn't write to disk. Flush writes the translog and commits segments to disk for durability. Refresh runs every 1s by default; flush runs based on translog size (default 512mb).
Q: Does increasing refresh interval improve indexing performance?
A: Yes, raising it from 1s to 30s typically improves bulk indexing throughput by 20-40% by reducing segment creation and downstream merge work. The trade-off is search freshness - new documents take up to 30s to appear.
Q: What is ?refresh=wait_for in Elasticsearch?
A: ?refresh=wait_for on a write request waits for the next scheduled refresh before returning, so the caller knows the document is searchable when the response arrives. It does not force an extra refresh, unlike ?refresh=true, so it's the right choice for write-then-read flows under high load.
Q: How do I trigger a manual refresh in Elasticsearch?
A: Send a POST /_refresh to refresh all indices, or POST /my-index/_refresh for a specific index. Manual refresh is fine for occasional use but expensive if hit in a tight loop.
Related Reading
- What is Elasticsearch Index: how indices and shards relate to refresh
- What is Elasticsearch Mapping: mapping settings that affect indexing
- What is Elasticsearch Node: node roles and indexing pipeline
- What is Elasticsearch Query Cache: how refresh invalidates caches
- Elasticsearch Aggregation Types: aggregation freshness depends on refresh
