The Index, Update, Delete, and Bulk APIs support setting refresh to control when changes made by this request are made visible to search. These are the allowed values:

Choosing which setting to useedit

Unless you have a good reason to wait for the change to become visible, always use refresh=false (the default setting). The simplest and fastest choice is to omit the refresh parameter from the URL.

If you absolutely must have the changes made by a request visible synchronously with the request, you must choose between putting more load on Elasticsearch (true) and waiting longer for the response (wait_for). Here are a few points that should inform that decision:

refresh=wait_for Can Force a Refreshedit

If a refresh=wait_for request comes in when there are already index.max_refresh_listeners (defaults to 1000) requests waiting for a refresh on that shard then that request will behave just as though it had refresh set to true instead: it will force a refresh. This keeps the promise that when a refresh=wait_for request returns that its changes are visible for search while preventing unchecked resource usage for blocked requests. If a request forced a refresh because it ran out of listener slots then its response will contain "forced_refresh": true.

Bulk requests only take up one slot on each shard that they touch no matter how many times they modify the shard.

Examplesedit

These will create a document and immediately refresh the index so it is visible:

PUT /test/_doc/1?refresh
{"test": "test"}
PUT /test/_doc/2?refresh=true
{"test": "test"}

These will create a document without doing anything to make it visible for search:

PUT /test/_doc/3
{"test": "test"}
PUT /test/_doc/4?refresh=false
{"test": "test"}

This will create a document and wait for it to become visible for search:

PUT /test/_doc/4?refresh=wait_for
{"test": "test"}