NOTE: You are looking at documentation for an older release. For the latest information, see the current release documentation.
Start searching
editStart searching
editOnce you have ingested some data into an Elasticsearch index, you can search it
by sending requests to the _search
endpoint. To access the full suite of
search capabilities, you use the Elasticsearch Query DSL to specify the
search criteria in the request body. You specify the name of the index you
want to search in the request URI.
For example, the following request retrieves all documents in the bank
index sorted by account number:
GET /bank/_search { "query": { "match_all": {} }, "sort": [ { "account_number": "asc" } ] }
By default, the hits
section of the response includes the first 10 documents
that match the search criteria:
{ "took" : 63, "timed_out" : false, "_shards" : { "total" : 5, "successful" : 5, "skipped" : 0, "failed" : 0 }, "hits" : { "total" : 1000, "max_score": null, "hits" : [ { "_index" : "bank", "_type" : "_doc", "_id" : "0", "sort": [0], "_score" : null, "_source" : {"account_number":0,"balance":16623,"firstname":"Bradshaw","lastname":"Mckenzie","age":29,"gender":"F","address":"244 Columbus Place","employer":"Euron","email":"bradshawmckenzie@euron.com","city":"Hobucken","state":"CO"} }, { "_index" : "bank", "_type" : "_doc", "_id" : "1", "sort": [1], "_score" : null, "_source" : {"account_number":1,"balance":39225,"firstname":"Amber","lastname":"Duke","age":32,"gender":"M","address":"880 Holmes Lane","employer":"Pyrami","email":"amberduke@pyrami.com","city":"Brogan","state":"IL"} }, ... ] } }
The response also provides the following information about the search request:
-
took
– how long it took Elasticsearch to run the query, in milliseconds -
timed_out
– whether or not the search request timed out -
_shards
– how many shards were searched and a breakdown of how many shards succeeded, failed, or were skipped. -
max_score
– the score of the most relevant document found -
hits.total.value
- how many matching documents were found -
hits.sort
- the document’s sort position (when not sorting by relevance score) -
hits._score
- the document’s relevance score (not applicable when usingmatch_all
)
Each search request is self-contained: Elasticsearch does not maintain any
state information across requests. To page through the search hits, specify
the from
and size
parameters in your request.
For example, the following request gets hits 10 through 19:
GET /bank/_search { "query": { "match_all": {} }, "sort": [ { "account_number": "asc" } ], "from": 10, "size": 10 }
Now that you’ve seen how to submit a basic search request, you can start to
construct queries that are a bit more interesting than match_all
.
To search for specific terms within a field, you can use a match
query.
For example, the following request searches the address
field to find
customers whose addresses contain mill
or lane
:
GET /bank/_search { "query": { "match": { "address": "mill lane" } } }
To perform a phrase search rather than matching individual terms, you use
match_phrase
instead of match
. For example, the following request only
matches addresses that contain the phrase mill lane
:
GET /bank/_search { "query": { "match_phrase": { "address": "mill lane" } } }
To construct more complex queries, you can use a bool
query to combine
multiple query criteria. You can designate criteria as required (must match),
desirable (should match), or undesirable (must not match).
For example, the following request searches the bank
index for accounts that
belong to customers who are 40 years old, but excludes anyone who lives in
Idaho (ID):
GET /bank/_search { "query": { "bool": { "must": [ { "match": { "age": "40" } } ], "must_not": [ { "match": { "state": "ID" } } ] } } }
Each must
, should
, and must_not
element in a Boolean query is referred
to as a query clause. How well a document meets the criteria in each must
or
should
clause contributes to the document’s relevance score. The higher the
score, the better the document matches your search criteria. By default, Elasticsearch
returns documents ranked by these relevance scores.
The criteria in a must_not
clause is treated as a filter. It affects whether
or not the document is included in the results, but does not contribute to
how documents are scored. You can also explicitly specify arbitrary filters to
include or exclude documents based on structured data.
For example, the following request uses a range filter to limit the results to accounts with a balance between $20,000 and $30,000 (inclusive).
GET /bank/_search { "query": { "bool": { "must": { "match_all": {} }, "filter": { "range": { "balance": { "gte": 20000, "lte": 30000 } } } } } }