Before diving into internals, let’s build a rock-solid definition in plain language.

The refresh interval is a per-index setting in Elasticsearch that controls how frequently the search engine takes everything that has been indexed recently — but is still sitting in a temporary, in-memory holding area — and makes it visible to search queries. By default, this happens automatically every 1 second. That one-second delay is why Elasticsearch is officially described as “near real-time” (NRT) rather than “real-time.” A document is durably stored the moment it is accepted, but it is only searchable after the next refresh.

Why This Matters for Everyday Developers

If you have ever indexed a document in Elasticsearch and then immediately searched for it, only to find nothing — and then searched again a moment later and found it — you have experienced the refresh interval directly. It is not a bug. It is Elasticsearch deliberately trading a tiny amount of freshness for a large amount of indexing speed and cluster stability.

To understand refresh, you first have to understand what Elasticsearch is actually built on top of.

Underneath every Elasticsearch index sits Apache Lucene, a lower-level search library that does the actual heavy lifting of storing and searching text. Lucene organizes data into immutable, read-only files called segments. “Immutable” is the key word here — once a segment is written, it is never edited again. This design choice is what makes Lucene searches extremely fast, because a search never has to worry about data changing underneath it mid-query.

But this creates an obvious problem: if segments can never be changed, how does Elasticsearch handle new documents arriving every second? The answer is that it doesn’t edit existing segments — it creates brand-new, small segments to hold the new data, and later merges many small segments into fewer, larger ones in the background. The refresh interval controls exactly one thing in this picture: how often a new segment gets created and opened up for searching.

The Cost of Making Everything Instant

You might reasonably ask: why not just refresh after every single document, so everything is searchable the instant it’s written? Elasticsearch actually supports this — you can set the refresh interval to a very small number, or even request a refresh after every single write. The problem is cost. Creating a new Lucene segment is not free. Each new segment consumes file handles, memory for its internal data structures, and CPU cycles. If you create thousands of tiny segments per second, the cluster spends more time managing segments than it does actually serving useful search traffic. The one-second default is a carefully chosen middle ground between “fresh enough for almost every use case” and “not so frequent that it wrecks performance.”

Four moving parts work together to make refresh possible. Understanding each one individually makes the whole picture click.

Let’s walk through the exact sequence of internal steps, from the moment the timer fires to the moment a document becomes searchable.

Notice something important: the translog is not cleared during this process. The translog only gets trimmed during a separate operation called a flush. This is exactly why refresh is considered a “cheap and frequent” operation while flush is a “heavier and less frequent” one — refresh only touches memory-backed structures, while flush deals with guaranteed durability on physical disk.

Following one document from the moment your application sends it to the moment it’s fully durable and searchable ties everything together.

flowchart TD
    A["App sends document
(index request)"] --> B["Written to In-Memory Buffer"]
    B --> C["Appended to Translog on disk
(durability guaranteed)"]
    C --> D{"Refresh Interval
elapsed?"}
    D -- "No, wait" --> D
    D -- "Yes" --> E["New Lucene Segment created
from buffer contents"]
    E --> F["Segment written to
Filesystem Cache"]
    F --> G["Segment opened for search
Document is now SEARCHABLE"]
    G --> H{"Flush interval /
translog size limit reached?"}
    H -- "No, wait" --> H
    H -- "Yes" --> I["Segments fsynced to disk,
Translog cleared"]
        

Two milestones matter most for engineers to remember. The first milestone is durability — reached the instant the document is written to the translog, seconds before it is even searchable. Even if the node crashes right after this point, the document will not be lost; it will be replayed from the translog on restart. The second milestone is searchability — reached only after the next refresh completes and opens a new segment. These two milestones are often reached at almost the same time in practice, but they are conceptually and mechanically distinct events.

This setting is deliberately easy to change, because different indices in the same cluster often need very different freshness guarantees.

The refresh interval is configured per index using the setting index.refresh_interval. It is a dynamic setting, which means it can be updated on an index that is already live, receiving traffic, and serving queries — no downtime, no reindexing, no closing the index required. It accepts a time value such as 1s, 30s, 5m, or the special disabling value -1.

Index-Level, Not Cluster-Level

It’s worth emphasizing that this setting lives at the index level, not the cluster level. A single Elasticsearch cluster can happily run one index with a 1-second refresh interval for a live customer-facing search feature, right alongside another index with a 30-second interval for background log ingestion — each tuned to what that specific workload actually needs.

Every value you choose for the refresh interval is really a trade-off along the same dial — freshness on one end, throughput and stability on the other.

Refresh activity is not invisible — Elasticsearch exposes detailed statistics so engineers can see exactly how much work refreshing is costing the cluster.

Both the index-stats and node-stats APIs expose a dedicated refresh section. This section reports how many refreshes have happened, how much cumulative time has been spent refreshing, and whether any refreshes are currently in progress. Watching these numbers over time is the standard way to tell whether your refresh interval is well-tuned or is quietly eating into cluster capacity.

Over years of production use, the Elasticsearch community has converged on a few clear “do this” and “don’t do this” patterns around refresh.

A short, practical checklist that summarizes what experienced Elasticsearch operators actually do differently from beginners.

Different industries lean on different points along the refresh-interval trade-off, depending on what their users actually need.

No. Durability comes from the translog, which is written on every index request regardless of the refresh interval. Refresh only affects when data becomes searchable, not whether it’s safely stored.

They are still safely indexed and durable via the translog, but they will not become searchable until a manual refresh is triggered or the setting is changed back to a scheduled interval.

Yes. It is a per-index setting, so each index in a cluster can have its own value, chosen based on that index’s specific freshness and throughput needs.

Generally no, for high-volume workloads, because it forces constant small-segment creation and removes the batching benefits of bulk indexing. It’s better reserved for specific cases genuinely requiring instant visibility.

No. It’s a dynamic setting and can be updated on a live, running index without any downtime.

Because refreshing has a real resource cost (creating new Lucene segments). One second was chosen as a balance point that feels instant to most users while keeping segment-creation overhead manageable for typical workloads.

The refresh interval is one of the smallest settings in Elasticsearch, and yet it governs one of the biggest architectural trade-offs in the entire system: freshness versus throughput. It controls how often the in-memory buffer of newly indexed documents is turned into a new, searchable Lucene segment — completely separate from durability, which is handled by the translog and the flush process. Understanding this distinction clearly is often the difference between an engineer who fights confusing “missing document” bugs and one who tunes Elasticsearch confidently for exactly the workload in front of them.