Submit Async Search API

edit

Request

edit

A SubmitAsyncSearchRequest allows to submit an asynchronous search task to the cluster. Required arguments are the SearchSourceBuilder defining the search and the target indices:

SearchSourceBuilder searchSource = new SearchSourceBuilder()
        .query(QueryBuilders.matchAllQuery()); 
String[] indices = new String[] { "my-index" }; 
SubmitAsyncSearchRequest request
        = new SubmitAsyncSearchRequest(searchSource, indices);

The definition of the search to run

The target indices for the search

Optional arguments

edit

The following arguments can optionally be provided:

request.setWaitForCompletionTimeout(TimeValue.timeValueSeconds(30)); 
request.setKeepAlive(TimeValue.timeValueMinutes(15)); 
request.setKeepOnCompletion(false); 

The minimum time that the request should wait before returning a partial result (defaults to 1 second).

The expiration time of the request (defaults to 5 days).

Controls whether the results should be stored if the request completed within the provided wait_for_completion time (default: false)

Synchronous Execution

edit
AsyncSearchResponse response = client.asyncSearch()
        .submit(request, RequestOptions.DEFAULT); 

Execute the request and get back the response as an AsyncSearchResponse object.

Asynchronous Execution

edit

The asynchronous execution of a SubmitAsyncSearchRequest allows to use an ActionListener to be called back when the submit request returns. Note that this is does not concern the execution of the submitted search request, which always executes asynchronously. The listener, however, waits for the submit request itself to come back:

client.asyncSearch()
    .submitAsync(request, RequestOptions.DEFAULT, listener); 

The SubmitAsyncSearchRequest 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 AsyncSearchResponse looks like:

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

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

Called when the execution is successfully completed. The response is provided as an argument

Called in case of failure. The raised exception is provided as an argument

Response

edit

The returned AsyncSearchResponse allows to retrieve information about the executed operation as follows:

response.getSearchResponse(); 
response.getId(); 
response.isPartial(); 
response.isRunning(); 
response.getStartTime(); 
response.getExpirationTime(); 
response.getFailure(); 

The SearchResponse, or null if not available yet

The id of the async search request, null if the response isn’t stored

true when the response contains partial results

true when the search is still running

The time the response was created (millis since epoch)

The time the response expires (millis since epoch)

Get failure reasons or null for no failures