Troubleshooting
editTroubleshooting
edit[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
When you query your data, Elasticsearch may return an error, no search results, or results in an unexpected order. This guide describes how to troubleshoot searches.
Ensure the data stream, index, or alias exists
editElasticsearch returns an index_not_found_exception
when the data stream, index
or alias you try to query does not exist. This can happen when you misspell the
name or when the data has been indexed to a different data stream or index.
Use the Exists API to check whether a data stream, index, or alias exists:
HEAD my-index
Use the Get index API to list all indices and their aliases:
GET /_all?filter_path=*.aliases
Instead of an error, it is possible to retrieve partial search results if some
of the indices you’re querying are unavailable.
Set ignore_unavailable
to true
:
GET /my-alias/_search?ignore_unavailable=true
Ensure the data stream or index contains data
editWhen a search request returns no hits, the data stream or index may contain no data. This can happen when there is a data ingestion issue. For example, the data may have been indexed to a data stream or index with another name.
Use the Count API
to retrieve the number of documents in a data
stream or index.
Check that count
in the response is not 0.
GET /my-index-000001/_count
If you aren’t getting search results in the UI, check that you have selected the correct data view and a valid time range. Also, ensure the data view has been configured with the correct time field.
Check that the field exists and its capabilities
editQuerying a field that does not exist will not return any results. Use the Field capabilities API to check whether a field exists:
GET /my-index-000001/_field_caps?fields=my-field
If the field does not exist, check the data ingestion process. The field may have a different name.
If the field exists, the request will return the field’s type and whether it is searchable and aggregatable.
{ "indices": [ "my-index-000001" ], "fields": { "my-field": { "keyword": { "type": "keyword", "metadata_field": false, "searchable": true, "aggregatable": true } } } }
The field is of type |
|
The field is searchable in this index. |
|
The field is aggregatable in this index. |
Check the field’s mappings
editA field’s capabilities are determined by its mapping. To retrieve the mapping, use the Get mapping API:
GET /my-index-000001/_mappings
If you query a text
field, pay attention to the analyzer that may have been
configured.
You can use the Analyze API
to check how a field’s analyzer processes values and query terms:
GET /my-index-000001/_analyze { "field": "my-field", "text": "this is a test" }
To change the mapping of an existing field use the Update mapping API.
Check the field’s values
editUse the exists
query to check whether there are
documents that return a value for a field.
Check that count
in the response is
not 0.
GET /my-index-000001/_count { "query": { "exists": { "field": "my-field" } } }
If the field is aggregatable, you can use aggregations
to check the field’s values. For keyword
fields, you can use a terms
aggregation to retrieve the field’s most common values:
GET /my-index-000001/_search?filter_path=aggregations { "size": 0, "aggs": { "top_values": { "terms": { "field": "my-field", "size": 10 } } } }
For numeric fields, you can use stats aggregation to get an idea of the field’s value distribution:
GET /my-index-000001/_search?filter_path=aggregations { "aggs": { "my-num-field-stats": { "stats": { "field": "my-num-field" } } } }
If the field does not return any values, check the data ingestion process. The field may have a different name.
Check the latest value
editFor time-series data, confirm there is non-filtered data within the attempted
time range.
For example, if you are trying to query the latest data for the
@timestamp
field, run the following to see if the max @timestamp
falls
within the attempted range:
GET /my-index-000001/_search?sort=@timestamp:desc&size=1
Validate, explain, and profile queries
editWhen a query returns unexpected results, Elasticsearch offers several tools to investigate why.
The Validate API
enables you to validate a query.
Use the rewrite
parameter to return the Lucene query an Elasticsearch query is
rewritten into:
GET /my-index-000001/_validate/query?rewrite=true { "query": { "match": { "user.id": { "query": "kimchy", "fuzziness": "auto" } } } }
Use the Explain API to find out why a specific document matches or doesn’t match a query:
GET /my-index-000001/_explain/0 { "query" : { "match" : { "message" : "elasticsearch" } } }
The Profile API provides detailed timing information about a search request. For a visual representation of the results, use the Search Profiler.
To troubleshoot queries, select Inspect in the toolbar. Next, select Request. You can now copy the query sent to Elasticsearch for further analysis in Console.
Check index settings
editIndex settings
can influence search results.
For example, the index.query.default_field
setting, which determines the field
that is queried when a query specifies no explicit field.
Use the Get index settings API
to retrieve the settings for an index:
GET /my-index-000001/_settings
You can update dynamic index settings with the Update index settings API. Changing dynamic index settings for a data stream requires changing the index template used by the data stream.
For static settings, you need to create a new index with the correct settings. Next, you can reindex the data into that index.