How does refresh=wait_for on an Elasticsearch index request differ from refresh=true?

## The problem both options solve Elasticsearch search is near-real-time: a document becomes searchable only once a refresh has turned the shard's in-memory buffer into a Lucene segment, by default about once per second. Some workflows cannot tolerate that: a user saves a record and is immediately redirected to a list view that queries the index, or an integration test asserts on a search straight after a write. The `refresh` parameter on the index, update, delete and bulk APIs exists for exactly these cases. ## The three values - **`refresh=false`** (default) — do nothing extra; visibility happens whenever the next scheduled refresh runs. - **`refresh=wait_for`** — do not trigger a refresh; instead hold this response open until a refresh has occurred that makes this change visible, then respond. - **`refresh=true`** — force an immediate refresh of the shards touched by this request, then respond. ## Why wait_for is usually the better choice The key insight is that a refresh is a *per-shard* operation whose cost is amortised over everything in the buffer. If a hundred writes land in the same second and each one sets `refresh=true`, you have forced up to a hundred refreshes and produced up to a hundred small segments, each of which now has to be merged in the background — CPU, I/O, file handles, and a longer per-query segment list. If those same hundred writes use `wait_for`, they all attach to the same upcoming refresh: one segment, one refresh, and every caller returns at roughly the same moment. The cost of `wait_for` is latency in the caller. The request will block for up to `index.refresh_interval`, so a client that indexes with `wait_for` in a tight loop serialises itself at one document per refresh cycle. The fix there is to batch: send a bulk request with `refresh=wait_for` once rather than N single writes with it. ## The listener limit A shard tracks pending `wait_for` requests as refresh listeners, and the number it will hold is bounded by `index.max_refresh_listeners`. When that bound is exceeded, additional requests do not fail — they fall back to forcing a refresh, i.e. they behave like `refresh=true`. This matters operationally: a system that puts `wait_for` on a high-throughput write path does not stay cheap under load; it degrades into exactly the segment storm you were trying to avoid. ## The standalone refresh API `POST /index/_refresh` refreshes an entire index on demand, independently of any write. It is the natural tool in a test harness (write a batch, refresh once, assert) and in bulk-load pipelines where `index.refresh_interval` was set to `-1` for the duration of the load and you want one refresh at the end. ## What this does not give you Neither value has anything to do with durability. Durability is the translog's job, governed by `index.translog.durability`; a refresh writes segments to the filesystem cache and never fsyncs. A request that returned with `refresh=true` is no more crash-safe than one that returned with `refresh=false`. Equally, neither one gives cluster-wide guarantees beyond the shards involved. `wait_for` guarantees that *this change* is visible when the response arrives; it says nothing about other concurrent writes to other shards. ## Choosing in practice Ask who needs the visibility. If it is a single user-facing flow, put `wait_for` on that one write and leave everything else alone. If it is a test, `wait_for` or an explicit `_refresh` between phases is clean and deterministic — much better than a sleep. If you find yourself wanting it on the majority of writes, the real answer is usually to fix the read path instead: fetch the just-written document by id (the get API is real-time) rather than searching for it.