(/)

Products (/products) Cloud (/cloud) Services (/services) Customers (/use-cases

Learn (/learn)

(/downloads)
(/contact?storm=glo

header-

en)
Docs (/guide)

Java REST Client [7.0] (index.html) » Java High Level REST Client
On this page
(java-rest-high.html) » Search APIs (_search_apis.html) » Search
Search Request
API
Synchronous Execution
«  Search APIs (_search_apis.html)     Search Scroll API  » (java-rest-high-
Asynchronous Execution
search-scroll.html)
SearchResponse

Search API
Getting Started
Search Request Videos
The SearchRequest is used for any operation that has to do
with searching documents, aggregations, suggestions and also Starting
o�ers ways of requesting highlighting on the resulting Elasticsearch
documents. Introduction to
In its most basic form, we can add a query to the request: Kibana

Logstash
SearchRequest searchRequest = new SearchRequest
Starter Guide
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilde
searchSourceBuilder.query(QueryBuilders.matchAllQuery
searchRequest.source(searchSourceBuilder);

Java REST Client:

1
 7.0 (current)
Creates the SeachRequest . Without arguments this runs
against all indices. Overview (java-rest-
overview.html)
Most search parameters are added to the
Java Low Level REST Clien
SearchSourceBuilder . It o�ers setters for everything that
(java-rest-low.html
goes into the search request body.
Java High Level REST
Add a match_all query to the SearchSourceBuilder . Client (java-rest-high.htm

Getting started
Add the SearchSourceBuilder to the SeachRequest . high-getting-started.html

Document APIs
Optional arguments high-supported-apis.html
Let’s �rst look at some of the optional arguments of a Search APIs
SearchRequest : (_search_apis.html

Search API (
SearchRequest searchRequest = new SearchRequest
high-search.html

Search Scroll API

Restricts the request to an index rest-high-search-
scroll.html)
There are a couple of other interesting optional parameters: Clear Scroll API
rest-high-clear-
searchRequest.routing("routing");
scroll.html)

Multi-Search API
Set a routing parameter rest-high-multi-
search.html

searchRequest.indicesOptions(IndicesOptions.lenientExpandOpen
Search Template API
(java-rest-high-search-
template.html
Setting IndicesOptions controls how unavailable indices
Multi-Search-Template
are resolved and how wildcard expressions are expanded
API (java-rest-high-mult
search-template.html
searchRequest.preference("_local");
Field Capabilities API
(java-rest-high-�eld-
caps.html)

2
 Ranking Evaluation API
Use the preference parameter e.g. to execute the search to
(java-rest-high-rank-

prefer local shards. The default is to randomize across eval.html)

shards. Explain API (

high-explain.html

Count API (java-rest-

Using the SearchSourceBuilder high-count.html
Most options controlling the search behavior can be set on the
SearchSourceBuilder , which contains more or less the Miscellaneous APIs
(_miscellaneous_apis.html
equivalent of the options in the search request body of the
Rest API. Indices APIs
(_indices_apis.html
Here are a few examples of some common options:
Cluster APIs
(_cluster_apis.html
SearchSourceBuilder sourceBuilder = new SearchSourceBuilder
sourceBuilder.query(QueryBuilders.termQuery("user" Ingest APIs
sourceBuilder.from(0); (_ingest_apis.html
sourceBuilder.size(5);
Snapshot APIs
sourceBuilder.timeout(new TimeValue(60, TimeUnit
(_snapshot_apis.html

Tasks APIs
Create a SearchSourceBuilder with default options. (_tasks_apis.html

Script APIs
Set the query. Can be any type of QueryBuilder (_script_apis.html

Licensing APIs
Set the from option that determines the result index to (_licensing_apis.html
start searching from. Defaults to 0.
Machine Learning APIs
(_machine_learning_apis.h
Set the size option that determines the number of search
Migration APIs
hits to return. Defaults to 10.
(_migration_apis.html

Set an optional timeout that controls how long the search Rollup APIs

is allowed to take. (_rollup_apis.html

Security APIs

After this, the SearchSourceBuilder only needs to be added (_security_apis.html

to the SearchRequest : Watcher APIs

(_watcher_apis.html

Graph APIs

3
 (_graph_apis.html
SearchRequest searchRequest = new SearchRequest
searchRequest.indices("posts"); CCR APIs (_ccr_apis.html
searchRequest.source(sourceBuilder); Index Lifecycle
Management APIs
(_index_lifecycle_managem

Using Java Builders

Building queries
rest-high-java-
Search queries are created using QueryBuilder objects. A
builders.html)
QueryBuilder exists for every search query type supported by
Migration Guide
Elasticsearch’s Query DSL (https://www.elastic.co/guide
high-level-migration.html
/en/elasticsearch/reference/7.0/query-dsl.html).
License (_license_2.html
A QueryBuilder can be created using its constructor:

MatchQueryBuilder matchQueryBuilder = new MatchQueryBuilder

Create a full text Match Query (https://www.elastic.co

/guide/en/elasticsearch/reference/7.0/query-dsl-match-
query.html) that matches the text "kimchy" over the �eld
"user".

Once created, the QueryBuilder object provides methods to

con�gure the options of the search query it creates:

matchQueryBuilder.fuzziness(Fuzziness.AUTO);
matchQueryBuilder.prefixLength(3);
matchQueryBuilder.maxExpansions(10);

Enable fuzzy matching on the match query

Set the pre�x length option on the match query

Set the max expansion options to control the fuzzy process

of the query

QueryBuilder objects can also be created using the

4
QueryBuilders utility class. This class provides helper
methods that can be used to create QueryBuilder objects
using a �uent programming style:

QueryBuilder matchQueryBuilder = QueryBuilders.

Whatever the method used to create it, the QueryBuilder

object must be added to the SearchSourceBuilder as follows:

searchSourceBuilder.query(matchQueryBuilder);

The Building Queries (java-rest-high-query-builders.html) page

gives a list of all available search queries with their
corresponding QueryBuilder objects and QueryBuilders
helper methods.

Specifying Sorting
The SearchSourceBuilder allows to add one or more
SortBuilder instances. There are four special
implementations (Field-, Score-, GeoDistance- and
ScriptSortBuilder).

sourceBuilder.sort(new ScoreSortBuilder().order
sourceBuilder.sort(new FieldSortBuilder("_id").

Sort descending by _score (the default)

Also sort ascending by _id �eld

Source �ltering
By default, search requests return the contents of the

5
document _source but like in the Rest API you can overwrite
this behavior. For example, you can turn o� _source retrieval
completely:

sourceBuilder.fetchSource(false);

The method also accepts an array of one or more wildcard

patterns to control which �elds get included or excluded in a
more �ne grained way:

String[] includeFields = new String[] {"title",

String[] excludeFields = new String[] {"user"};
sourceBuilder.fetchSource(includeFields, excludeFields

Requesting Highlighting
Highlighting search results can be achieved by setting a
HighlightBuilder on the SearchSourceBuilder . Di�erent
highlighting behaviour can be de�ned for each �elds by adding
one or more HighlightBuilder.Field instances to a
HighlightBuilder .

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilde

HighlightBuilder highlightBuilder = new HighlightBuilder
HighlightBuilder.Field highlightTitle =
new HighlightBuilder.Field("title");
highlightTitle.highlighterType("unified");
highlightBuilder.field(highlightTitle);
HighlightBuilder.Field highlightUser = new HighlightBuilder
highlightBuilder.field(highlightUser);
searchSourceBuilder.highlighter(highlightBuilder

Creates a new HighlightBuilder

Create a �eld highlighter for the title �eld

6
 Set the �eld highlighter type

Add the �eld highlighter to the highlight builder

There are many options which are explained in detail in the

Rest API documentation. The Rest API parameters (e.g.
pre_tags ) are usually changed by setters with a similar name
(e.g. #preTags(String ...) ).

Highlighted text fragments can later be retrieved (java-rest-

high-search.html#java-rest-high-search-response-highlighting)
from the SearchResponse .

Requesting Aggregations
Aggregations can be added to the search by �rst creating the
appropriate AggregationBuilder and then setting it on the
SearchSourceBuilder . In the following example we create a
terms aggregation on company names with a sub-aggregation
on the average age of employees in the company:

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilde

TermsAggregationBuilder aggregation = AggregationBuilders
.field("company.keyword");
aggregation.subAggregation(AggregationBuilders.
.field("age"));
searchSourceBuilder.aggregation(aggregation);

The Building Aggregations (java-rest-high-aggregation-

builders.html) page gives a list of all available aggregations
with their corresponding AggregationBuilder objects and
AggregationBuilders helper methods.

We will later see how to access aggregations (java-rest-high-

search.html#java-rest-high-search-response-aggs) in the
SearchResponse .

7
Requesting Suggestions
To add Suggestions to the search request, use one of the
SuggestionBuilder implementations that are easily
accessible from the SuggestBuilders factory class.
Suggestion builders need to be added to the top level
SuggestBuilder , which itself can be set on the
SearchSourceBuilder .

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilde

SuggestionBuilder termSuggestionBuilder =
SuggestBuilders.termSuggestion("user").text
SuggestBuilder suggestBuilder = new SuggestBuilder
suggestBuilder.addSuggestion("suggest_user", termSuggestionBuild
searchSourceBuilder.suggest(suggestBuilder);

Creates a new TermSuggestionBuilder for the user �eld

and the text kmichy

Adds the suggestion builder and names it suggest_user

We will later see how to retrieve suggestions (java-rest-high-

search.html#java-rest-high-search-response-suggestions) from
the SearchResponse .

Pro�ling Queries and Aggregations

The Pro�le API (https://www.elastic.co/guide/en/elasticsearch
/reference/7.0/search-pro�le.html) can be used to pro�le the
execution of queries and aggregations for a speci�c search
request. in order to use it, the pro�le �ag must be set to true
on the SearchSourceBuilder :

SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilde

searchSourceBuilder.profile(true);

Once the SearchRequest is executed the corresponding

8
SearchResponse will contain the pro�ling results (java-rest-
high-search.html#java-rest-high-search-response-pro�le).

Synchronous Execution
When executing a SearchRequest in the following manner, the
client waits for the SearchResponse to be returned before
continuing with code execution:

SearchResponse searchResponse = client.search(searchRequest

Synchronous calls may throw an IOException in case of either

failing to parse the REST response in the high-level REST client,
the request times out or similar cases where there is no
response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the
high-level client tries to parse the response body error details
instead and then throws a generic ElasticsearchException
and adds the original ResponseException as a suppressed
exception to it.

Asynchronous Execution
Executing a SearchRequest can also be done in an
asynchronous fashion so that the client can return directly.
Users need to specify how the response or potential failures
will be handled by passing the request and a listener to the
asynchronous search method:

client.searchAsync(searchRequest, RequestOptions

The SearchRequest to execute and the ActionListener

to use when the execution completes

The asynchronous method does not block and returns

9
immediately. Once it is completed the ActionListener is
called back using the onResponse method if the execution
successfully completed or using the onFailure method if it
failed. Failure scenarios and expected exceptions are the same
as in the synchronous execution case.

A typical listener for search looks like:

ActionListener<SearchResponse> listener = new ActionListener

@Override
public void onResponse(SearchResponse searchResponse

@Override
public void onFailure(Exception e) {

}
};

Called when the execution is successfully completed.

Called when the whole SearchRequest fails.

SearchResponse
The SearchResponse that is returned by executing the search
provides details about the search execution itself as well as
access to the documents returned. First, there is useful
information about the request execution itself, like the HTTP
status code, execution time or whether the request terminated
early or timed out:

10
 RestStatus status = searchResponse.status();
TimeValue took = searchResponse.getTook();
Boolean terminatedEarly = searchResponse.isTerminatedEarly
boolean timedOut = searchResponse.isTimedOut();

Second, the response also provides information about the

execution on the shard level by o�ering statistics about the
total number of shards that were a�ected by the search, and
the successful vs. unsuccessful shards. Possible failures can
also be handled by iterating over an array o�
ShardSearchFailures like in the following example:

int totalShards = searchResponse.getTotalShards

int successfulShards = searchResponse.getSuccessfulShards
int failedShards = searchResponse.getFailedShards
for (ShardSearchFailure failure : searchResponse
// failures should be handled here
}

Retrieving SearchHits
To get access to the returned documents, we need to �rst get
the SearchHits contained in the response:

SearchHits hits = searchResponse.getHits();

The SearchHits provides global information about all hits, like

total number of hits or the maximum score:

TotalHits totalHits = hits.getTotalHits();

// the total number of hits, must be interpreted in the context
long numHits = totalHits.value;
// whether the number of hits is accurate (EQUAL_TO) or a lower
TotalHits.Relation relation = totalHits.relation
float maxScore = hits.getMaxScore();

Nested inside the SearchHits are the individual search results

11
that can be iterated over:

SearchHit[] searchHits = hits.getHits();

for (SearchHit hit : searchHits) {
// do something with the SearchHit
}

The SearchHit provides access to basic information like index,

document ID and score of each search hit:

String index = hit.getIndex();

String id = hit.getId();
float score = hit.getScore();

Furthermore, it lets you get back the document source, either

as a simple JSON-String or as a map of key/value pairs. In this
map, regular �elds are keyed by the �eld name and contain
the �eld value. Multi-valued �elds are returned as lists of
objects, nested objects as another key/value map. These cases
need to be cast accordingly:

String sourceAsString = hit.getSourceAsString();

Map<String, Object> sourceAsMap = hit.getSourceAsMap
String documentTitle = (String) sourceAsMap.get
List<Object> users = (List<Object>) sourceAsMap
Map<String, Object> innerObject =
(Map<String, Object>) sourceAsMap.get("innerObject"

Retrieving Highlighting
If requested (java-rest-high-search.html#java-rest-high-search-
request-highlighting), highlighted text fragments can be
retrieved from each SearchHit in the result. The hit object
o�ers access to a map of �eld names to HighlightField
instances, each of which contains one or many highlighted text
fragments:

12
SearchHits hits = searchResponse.getHits();
for (SearchHit hit : hits.getHits()) {
Map<String, HighlightField> highlightFields
HighlightField highlight = highlightFields.
Text[] fragments = highlight.fragments();
String fragmentString = fragments[0].string
}

Get the highlighting for the title �eld

Get one or many fragments containing the highlighted �eld

content

13
Retrieving Aggregations
Aggregations can be retrieved from the SearchResponse by
�rst getting the root of the aggregation tree, the
Aggregations object, and then getting the aggregation by
name.

Aggregations aggregations = searchResponse.getAggregations

Terms byCompanyAggregation = aggregations.get("by_company"
Bucket elasticBucket = byCompanyAggregation.getBucketByKey
Avg averageAge = elasticBucket.getAggregations().
double avg = averageAge.getValue();

Get the by_company terms aggregation

Get the buckets that is keyed with Elastic

Get the average_age sub-aggregation from that bucket

Note that if you access aggregations by name, you need to

specify the aggregation interface according to the type of
aggregation you requested, otherwise a ClassCastException
will be thrown:

Range range = aggregations.get("by_company");

This will throw an exception because "by_company" is a

terms aggregation but we try to retrieve it as a range
aggregation

It is also possible to access all aggregations as a map that is

keyed by the aggregation name. In this case, the cast to the
proper aggregation interface needs to happen explicitly:

Map<String, Aggregation> aggregationMap = aggregations

Terms companyAggregation = (Terms) aggregationMap

14
There are also getters that return all top level aggregations as
a list:

List<Aggregation> aggregationList = aggregations

And last but not least you can iterate over all aggregations and
then e.g. decide how to further process them based on their
type:

for (Aggregation agg : aggregations) {

String type = agg.getType();
if (type.equals(TermsAggregationBuilder.NAME
Bucket elasticBucket = ((Terms) agg).getBucketByKey
long numberOfDocs = elasticBucket.getDocCount
}
}

Retrieving Suggestions
To get back the suggestions from a SearchResponse , use the
Suggest object as an entry point and then retrieve the nested
suggestion objects:

Suggest suggest = searchResponse.getSuggest();

TermSuggestion termSuggestion = suggest.getSuggestion
for (TermSuggestion.Entry entry : termSuggestion
for (TermSuggestion.Entry.Option option : entry
String suggestText = option.getText().string
}
}

Use the Suggest class to access suggestions

15
 Suggestions can be retrieved by name. You need to assign
them to the correct type of Suggestion class (here
TermSuggestion ), otherwise a ClassCastException is

thrown

Iterate over the suggestion entries

Iterate over the options in one entry

Retrieving Pro�ling Results

Pro�ling results are retrieved from a SearchResponse using
the getProfileResults() method. This method returns a
Map containing a ProfileShardResult object for every shard
involved in the SearchRequest execution.
ProfileShardResult are stored in the Map using a key that
uniquely identi�es the shard the pro�le result corresponds to.

Here is a sample code that shows how to iterate over all the
pro�ling results of every shard:

Map<String, ProfileShardResult> profilingResults

searchResponse.getProfileResults();
for (Map.Entry<String, ProfileShardResult> profilingResult
String key = profilingResult.getKey();
ProfileShardResult profileShardResult = profilingResult
}

Retrieve the Map of ProfileShardResult from the

SearchResponse

Pro�ling results can be retrieved by shard’s key if the key is

known, otherwise it might be simpler to iterate over all the
pro�ling results

16
 Retrieve the key that identi�es which shard the
ProfileShardResult belongs to

Retrieve the ProfileShardResult for the given shard

The ProfileShardResult object itself contains one or more

query pro�le results, one for each query executed against the
underlying Lucene index:

List<QueryProfileShardResult> queryProfileShardResults
profileShardResult.getQueryProfileResults
for (QueryProfileShardResult queryProfileResult

Retrieve the list of QueryProfileShardResult

Iterate over each QueryProfileShardResult

Each QueryProfileShardResult gives access to the detailed

query tree execution, returned as a list of ProfileResult
objects:

for (ProfileResult profileResult : queryProfileResult

String queryName = profileResult.getQueryName
long queryTimeInMillis = profileResult.getTime
List<ProfileResult> profiledChildren = profileResult
}

Iterate over the pro�le results

Retrieve the name of the Lucene query

Retrieve the time in millis spent executing the Lucene

query

17
 Retrieve the pro�le results for the sub-queries (if any)

The Rest API documentation contains more information about

Pro�ling Queries (https://www.elastic.co/guide
/en/elasticsearch/reference/7.0/search-pro�le-queries.html)
with a description of the query pro�ling information.

The QueryProfileShardResult also gives access to the

pro�ling information for the Lucene collectors:

CollectorResult collectorResult = queryProfileResult

String collectorName = collectorResult.getName();
Long collectorTimeInMillis = collectorResult.getTime
List<CollectorResult> profiledChildren = collectorResult

Retrieve the pro�ling result of the Lucene collector

Retrieve the name of the Lucene collector

Retrieve the time in millis spent executing the Lucene

collector

Retrieve the pro�le results for the sub-collectors (if any)

The Rest API documentation contains more information about

pro�ling information for Lucene collectors. See Pro�ling
queries (https://www.elastic.co/guide/en/elasticsearch
/reference/7.0/search-pro�le-queries.html).

In a very similar manner to the query tree execution, the

QueryProfileShardResult objects gives access to the detailed
aggregations tree execution:

18
 AggregationProfileShardResult aggsProfileResults
profileShardResult.getAggregationProfileResults
for (ProfileResult profileResult : aggsProfileResults
String aggName = profileResult.getQueryName
long aggTimeInMillis = profileResult.getTime
List<ProfileResult> profiledChildren = profileResult
}

Retrieve the AggregationProfileShardResult

Iterate over the aggregation pro�le results

Retrieve the type of the aggregation (corresponds to Java

class used to execute the aggregation)

Retrieve the time in millis spent executing the Lucene

collector

Retrieve the pro�le results for the sub-aggregations (if any)

The Rest API documentation contains more information about

Pro�ling aggregations (https://www.elastic.co/guide
/en/elasticsearch/reference/7.0/search-pro�le-
aggregations.html).

«  Search APIs (_search_apis.html)     Search Scroll API  » (java-rest-high-

search-scroll.html)

Be in the know with the latest and Email Address

greatest from Elastic.

19
PRODUCTS >
(/PRODUCTS)
Elasticsearch (/products
/elasticsearch)
Kibana (/products/kibana)
Beats (/products/beats)
Logstash (/products
/logstash)
Stack Features (formerly
X-Pack) (/products/stack)
Security (/products/stack
/security)
Alerting (/products/stack
/alerting)
Canvas (/products/stack
/canvas)
Monitoring (/products/stack
/monitoring)
Graph (/products/stack
/graph)
Reporting (/products/stack
/reporting)
Machine Learning
(/products/stack/machine-
learning)
Elasticsearch SQL
(/products/stack
/elasticsearch-sql)
Elasticsearch-Hadoop
(/products/hadoop)
Elastic Cloud Enterprise
(/products/ece)
()
SOLUTIONS > RESOURCES ABOUT > (
(/SOLUTIONS) Blog (/blog) Careers/Jobs (
Logging (/solutions/logging)
Cloud Status (https://cloud- /careers)
Metrics (/solutions/metrics)
status.elastic.co) Our Source Code
Site Search (/solutions/site-
Community (/community) /our-source-code
search)
Customers & Use Cases Teams (/about/teams
Security Analytics
(/use-cases) Board of Directors
(/solutions/security-
Documentation (/guide) /teams/board
analytics)
Elastic{ON} Events Leadership (/about/teams
APM (/solutions/apm)
(/elasticon) /leadership)
App Search (/solutions/app-
Forums Contact (/contact
search)
(https://discuss.elastic.co/) Our Story (/about/history-
Google Site Search
Meetups (/community of-elasticsearch
Alternative (/google-site-
/meetups) Why Open Source
search-alternative)
Subscriptions /why-open-source
ELASTIC CLOUD > (/subscriptions) Distributed by Intention
(/CLOUD) Support Portal (/about/distributed
Elasticsearch Service (/cloud
(https://support.elastic.co) Partners (/about/partners
/elasticsearch-service)
Videos & Webinars (/videos) Media (/about/press
AWS Elasticsearch Service
Training (/training) Investor Relations
Comparison (/aws-
(https://ir.elastic.co
elasticsearch-service)
Elastic Store
Elastic App Search Service
(https://www.elastic.shop
(/cloud/app-search-service)
()
Elastic Site Search Service
(/cloud/site-search-service)
20
 FOLLOW US

Trademarks (/legal/trademarks) / Terms of Use (/legal/terms-of-use) / Privacy (/legal/privacy-statement) / Brand (/brand)

© 2019. Elasticsearch B.V. All Rights Reserved

Elasticsearch is a trademark of Elasticsearch B.V., registered in the U.S. and in other countries.
Apache, Apache Lucene, Apache Hadoop, Hadoop, HDFS and the yellow elephant logo are trademarks of the Apache Software Foundation
(http://www.apache.org/) in the United States and/or other countries.

(/)

21