Multi-Search API

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

Multi-Search Request

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

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

SearchRequest searchRequest = new SearchRequest("posts"); 

Restricts the request to an index

Synchronous Execution

The multiSearch method executes `MultiSearchRequest`s synchronously:

MultiSearchResponse response = client.msearch(request, RequestOptions.DEFAULT);

Asynchronous Execution

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

client.searchAsync(searchRequest, RequestOptions.DEFAULT, 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

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(4, searchResponse.getHits().getTotalHits().value);
MultiSearchResponse.Item secondResponse = response.getResponses()[1];  
assertNull(secondResponse.getFailure());
searchResponse = secondResponse.getResponse();
assertEquals(1, searchResponse.getHits().getTotalHits().value);

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.