New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Ranking Evaluation API Count API »
Elastic Docs ›Java REST Client [7.10] ›Java High Level REST Client ›Search APIs

Explain API

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

Explain API

edit

The explain api computes a score explanation for a query and a specific document. This can give useful feedback whether a document matches or didn’t match a specific query.

Explain Request

edit

An ExplainRequest expects an index and an id to specify a certain document, and a query represented by QueryBuilder to run against it (the way of building queries).

ExplainRequest request = new ExplainRequest("contributors", "1");
request.query(QueryBuilders.termQuery("user", "tanguy"));

Optional arguments

edit
request.routing("routing");

Set a routing parameter

 
request.preference("_local");

Use the preference parameter e.g. to execute the search to prefer local shards. The default is to randomize across shards.

 
request.fetchSourceContext(new FetchSourceContext(true, new String[]{"user"}, null));

Set to true to retrieve the _source of the document explained. You can also retrieve part of the document by using _source_include & _source_exclude (see Get API for more details)

 
request.storedFields(new String[]{"user"});

Allows to control which stored fields to return as part of the document explained (requires the field to be stored separately in the mappings).

Synchronous Execution

edit

The explain method executes the request synchronously:

ExplainResponse response = client.explain(request, RequestOptions.DEFAULT);

Asynchronous Execution

edit

The explainAsync method executes the request asynchronously, calling the provided ActionListener when the response is ready:

client.explainAsync(request, RequestOptions.DEFAULT, listener);

The ExplainRequest to execute and the ActionListener to use when the execution completes.

The asynchronous method does not block and returns immediately. Once the request completes, 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 ExplainResponse is constructed as follows:

ActionListener<ExplainResponse> listener = new ActionListener<ExplainResponse>() {
    @Override
    public void onResponse(ExplainResponse explainResponse) {
        
    }

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

Called when the execution is successfully completed.

Called when the whole ExplainRequest fails.

ExplainResponse

edit

The ExplainResponse contains the following information:

String index = response.getIndex(); 
String id = response.getId(); 
boolean exists = response.isExists(); 
boolean match = response.isMatch(); 
boolean hasExplanation = response.hasExplanation(); 
Explanation explanation = response.getExplanation(); 
GetResult getResult = response.getGetResult();

The index name of the explained document.

The id of the explained document.

Indicates whether or not the explained document exists.

Indicates whether or not there is a match between the explained document and the provided query (the match is retrieved from the lucene Explanation behind the scenes if the lucene Explanation models a match, it returns true, otherwise it returns false).

Indicates whether or not there exists a lucene Explanation for this request.

Get the lucene Explanation object if there exists.

Get the GetResult object if the _source or the stored fields are retrieved.

The GetResult contains two maps internally to store the fetched _source and stored fields. You can use the following methods to get them:

Map<String, Object> source = getResult.getSource(); 
Map<String, DocumentField> fields = getResult.getFields();

Retrieve the _source as a map.

Retrieve the specified stored fields as a map.
« Ranking Evaluation API Count API »