- Elasticsearch Guide: other versions:
- Getting Started
- Setup Elasticsearch
- Breaking changes
- Breaking changes in 5.3
- Breaking changes in 5.2
- Breaking changes in 5.1
- Breaking changes in 5.0
- Search and Query DSL changes
- Mapping changes
- Percolator changes
- Suggester changes
- Index APIs changes
- Document API changes
- Settings changes
- Allocation changes
- HTTP changes
- REST API changes
- CAT API changes
- Java API changes
- Packaging
- Plugin changes
- Filesystem related changes
- Path to data on disk
- Aggregation changes
- Script related changes
- API Conventions
- Document APIs
- Search APIs
- Aggregations
- Metrics Aggregations
- Avg Aggregation
- Cardinality Aggregation
- Extended Stats Aggregation
- Geo Bounds Aggregation
- Geo Centroid Aggregation
- Max Aggregation
- Min Aggregation
- Percentiles Aggregation
- Percentile Ranks Aggregation
- Scripted Metric Aggregation
- Stats Aggregation
- Sum Aggregation
- Top hits Aggregation
- Value Count Aggregation
- Bucket Aggregations
- Adjacency Matrix Aggregation
- Children Aggregation
- Date Histogram Aggregation
- Date Range Aggregation
- Diversified Sampler Aggregation
- Filter Aggregation
- Filters Aggregation
- Geo Distance Aggregation
- GeoHash grid Aggregation
- Global Aggregation
- Histogram Aggregation
- IP Range Aggregation
- Missing Aggregation
- Nested Aggregation
- Range Aggregation
- Reverse nested Aggregation
- Sampler Aggregation
- Significant Terms Aggregation
- Terms Aggregation
- Pipeline Aggregations
- Avg Bucket Aggregation
- Derivative Aggregation
- Max Bucket Aggregation
- Min Bucket Aggregation
- Sum Bucket Aggregation
- Stats Bucket Aggregation
- Extended Stats Bucket Aggregation
- Percentiles Bucket Aggregation
- Moving Average Aggregation
- Cumulative Sum Aggregation
- Bucket Script Aggregation
- Bucket Selector Aggregation
- Serial Differencing Aggregation
- Matrix Aggregations
- Caching heavy aggregations
- Returning only aggregation results
- Aggregation Metadata
- Metrics Aggregations
- Indices APIs
- Create Index
- Delete Index
- Get Index
- Indices Exists
- Open / Close Index API
- Shrink Index
- Rollover Index
- Put Mapping
- Get Mapping
- Get Field Mapping
- Types Exists
- Index Aliases
- Update Indices Settings
- Get Settings
- Analyze
- Index Templates
- Shadow replica indices
- Indices Stats
- Indices Segments
- Indices Recovery
- Indices Shard Stores
- Clear Cache
- Flush
- Refresh
- Force Merge
- cat APIs
- Cluster APIs
- Query DSL
- Mapping
- Analysis
- Anatomy of an analyzer
- Testing analyzers
- Analyzers
- Normalizers
- Tokenizers
- Token Filters
- Standard Token Filter
- ASCII Folding Token Filter
- Flatten Graph Token Filter
- Length Token Filter
- Lowercase Token Filter
- Uppercase Token Filter
- NGram Token Filter
- Edge NGram Token Filter
- Porter Stem Token Filter
- Shingle Token Filter
- Stop Token Filter
- Word Delimiter Token Filter
- Stemmer Token Filter
- Stemmer Override Token Filter
- Keyword Marker Token Filter
- Keyword Repeat Token Filter
- KStem Token Filter
- Snowball Token Filter
- Phonetic Token Filter
- Synonym Token Filter
- Synonym Graph Token Filter
- Compound Word Token Filter
- Reverse Token Filter
- Elision Token Filter
- Truncate Token Filter
- Unique Token Filter
- Pattern Capture Token Filter
- Pattern Replace Token Filter
- Trim Token Filter
- Limit Token Count Token Filter
- Hunspell Token Filter
- Common Grams Token Filter
- Normalization Token Filter
- CJK Width Token Filter
- CJK Bigram Token Filter
- Delimited Payload Token Filter
- Keep Words Token Filter
- Keep Types Token Filter
- Classic Token Filter
- Apostrophe Token Filter
- Decimal Digit Token Filter
- Fingerprint Token Filter
- Minhash Token Filter
- Character Filters
- Modules
- Index Modules
- Ingest Node
- Pipeline Definition
- Ingest APIs
- Accessing Data in Pipelines
- Handling Failures in Pipelines
- Processors
- Append Processor
- Convert Processor
- Date Processor
- Date Index Name Processor
- Fail Processor
- Foreach Processor
- Grok Processor
- Gsub Processor
- Join Processor
- JSON Processor
- KV Processor
- Lowercase Processor
- Remove Processor
- Rename Processor
- Script Processor
- Set Processor
- Split Processor
- Sort Processor
- Trim Processor
- Uppercase Processor
- Dot Expander Processor
- How To
- Testing
- Glossary of terms
- Release Notes
- 5.3.3 Release Notes
- 5.3.2 Release Notes
- 5.3.1 Release Notes
- 5.3.0 Release Notes
- 5.2.2 Release Notes
- 5.2.1 Release Notes
- 5.2.0 Release Notes
- 5.1.2 Release Notes
- 5.1.1 Release Notes
- 5.1.0 Release Notes
- 5.0.2 Release Notes
- 5.0.1 Release Notes
- 5.0.0 Combined Release Notes
- 5.0.0 GA Release Notes
- 5.0.0-rc1 Release Notes
- 5.0.0-beta1 Release Notes
- 5.0.0-alpha5 Release Notes
- 5.0.0-alpha4 Release Notes
- 5.0.0-alpha3 Release Notes
- 5.0.0-alpha2 Release Notes
- 5.0.0-alpha1 Release Notes
- 5.0.0-alpha1 Release Notes (Changes previously released in 2.x)
- Painless API Reference
?refresh
edit?refresh
editThe 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:
-
Empty string or
true
- Refresh the relevant primary and replica shards (not the whole index) immediately after the operation occurs, so that the updated document appears in search results immediately. This should ONLY be done after careful thought and verification that it does not lead to poor performance, both from an indexing and a search standpoint.
-
wait_for
-
Wait for the changes made by the request to be made visible by a refresh before
replying. This doesn’t force an immediate refresh, rather, it waits for a
refresh to happen. Elasticsearch automatically refreshes shards that have changed
every
index.refresh_interval
which defaults to one second. That setting is dynamic. Calling the Refresh API or settingrefresh
totrue
on any of the APIs that support it will also cause a refresh, in turn causing already running requests withrefresh=wait_for
to return. -
false
(the default) - Take no refresh related actions. The changes made by this request will be made visible at some point after the request returns.
Choosing which setting to use
editUnless you have a good reason to wait for the change to become visible always
use refresh=false
, or, because that is the default, just leave the refresh
parameter out of the URL. That is the simplest and fastest choice.
If you absolutely must have the changes made by a request visible synchronously
with the request then you must pick 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:
-
The more changes being made to the index the more work
wait_for
saves compared totrue
. In the case that the index is only changed once everyindex.refresh_interval
then it saves no work. -
true
creates less efficient indexes constructs (tiny segments) that must later be merged into more efficient index constructs (larger segments). Meaning that the cost oftrue
is payed at index time to create the tiny segment, at search time to search the tiny segment, and at merge time to make the larger segments. -
Never start multiple
refresh=wait_for
requests in a row. Instead batch them into a single bulk request withrefresh=wait_for
and Elasticsearch will start them all in parallel and return only when they have all finished. -
If the refresh interval is set to
-1
, disabling the automatic refreshes, then requests withrefresh=wait_for
will wait indefinitely until some action causes a refresh. Conversely, settingindex.refresh_interval
to something shorter than the default like200ms
will makerefresh=wait_for
come back faster, but it’ll still generate inefficient segments. -
refresh=wait_for
only affects the request that it is on, but, by forcing a refresh immediately,refresh=true
will affect other ongoing request. In general, if you have a running system you don’t wish to disturb thenrefresh=wait_for
is a smaller modification.
refresh=wait_for
Can Force a Refresh
editIf 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.
Examples
editThese will create a document and immediately refresh the index so it is visible:
PUT /test/test/1?refresh {"test": "test"} PUT /test/test/2?refresh=true {"test": "test"}
These will create a document without doing anything to make it visible for search:
PUT /test/test/3 {"test": "test"} PUT /test/test/4?refresh=false {"test": "test"}
This will create a document and wait for it to become visible for search:
PUT /test/test/4?refresh=wait_for {"test": "test"}