IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Clear Scroll API Ranking Evaluation API »

› › ›

Multi-Search API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Multi-Search API

edit

The multiSearch API executes multiple search requests in a single http request in parallel.

Multi-Search Request

edit

The MultiSearchRequest is built empty and you add all of the searches that you wish to execute to it:

MultiSearchRequest request = new MultiSearchRequest();    
SearchRequest firstSearchRequest = new SearchRequest();   
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
searchSourceBuilder.query(QueryBuilders.matchQuery("user", "kimchy"));
firstSearchRequest.source(searchSourceBuilder);
request.add(firstSearchRequest);                          
SearchRequest secondSearchRequest = new SearchRequest();  
searchSourceBuilder = new SearchSourceBuilder();
searchSourceBuilder.query(QueryBuilders.matchQuery("user", "luca"));
secondSearchRequest.source(searchSourceBuilder);
request.add(secondSearchRequest);

	Create an empty `MultiSearchRequest`.
	Create an empty `SearchRequest` and populate it just like you would for a regular `search`.
	Add the `SearchRequest` to the `MultiSearchRequest`.
	Build a second `SearchRequest` and add it to the `MultiSearchRequest`.

Optional arguments

edit

The SearchRequest`s inside of `MultiSearchRequest support all of search's optional arguments. For example:

SearchRequest searchRequest = new SearchRequest("posts"); 
searchRequest.types("doc");

	Restricts the request to an index
	Limits the request to a type

Synchronous Execution

edit

The multiSearch method executes `MultiSearchRequest`s synchronously:

MultiSearchResponse response = client.multiSearch(request);

Asynchronous Execution

edit

The multiSearchAsync method executes MultiSearchRequest`s asynchronously, calling the provided `ActionListener when the response is ready.

client.searchAsync(searchRequest, listener);

The MultiSearchRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns 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.

A typical listener for MultiSearchResponse looks like:

ActionListener<MultiSearchResponse> listener = new ActionListener<MultiSearchResponse>() {
    @Override
    public void onResponse(MultiSearchResponse response) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};

	Called when the execution is successfully completed.
	Called when the whole `SearchRequest` fails.

MultiSearchResponse

edit

The MultiSearchResponse that is returned by executing the multiSearch method contains a MultiSearchResponse.Item for each SearchRequest in the MultiSearchRequest. Each MultiSearchResponse.Item contains an exception in getFailure if the request failed or a SearchResponse in getResponse if the request succeeded:

MultiSearchResponse.Item firstResponse = response.getResponses()[0];   
assertNull(firstResponse.getFailure());                                
SearchResponse searchResponse = firstResponse.getResponse();           
assertEquals(3, searchResponse.getHits().getTotalHits());
MultiSearchResponse.Item secondResponse = response.getResponses()[1];  
assertNull(secondResponse.getFailure());
searchResponse = secondResponse.getResponse();
assertEquals(1, searchResponse.getHits().getTotalHits());

	The item for the first search.
	It succeeded so `getFailure` returns null.
	And there is a `SearchResponse` in `getResponse`.
	The item for the second search.

« Clear Scroll API Ranking Evaluation API »