Explain API

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 »