CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-elasticsearch-plugin--rank-eval-client

Elasticsearch plugin providing comprehensive ranking evaluation capabilities for search quality assessment.

—

Pending
Overview
Eval results
Files

request-response-api.mddocs/

Request and Response API

This section covers the core request and response classes for the Elasticsearch Rank Eval plugin, including request builders, response handling, and evaluation specifications.

Core Classes

RankEvalRequest

Main request class for ranking evaluation operations.

public class RankEvalRequest extends ActionRequest implements IndicesRequest.Replaceable {
    // Constructors
    public RankEvalRequest(RankEvalSpec rankingEvaluationSpec, String[] indices);
    RankEvalRequest(); // package-private
    
    // Evaluation specification methods
    public RankEvalSpec getRankEvalSpec();
    public void setRankEvalSpec(RankEvalSpec task);
    
    // Index targeting methods
    public RankEvalRequest indices(String... indices);
    public String[] indices();
    
    // Options and configuration
    public IndicesOptions indicesOptions();
    public void indicesOptions(IndicesOptions indicesOptions);
    public SearchType searchType();
    public void searchType(SearchType searchType);
    
    // Validation
    public ActionRequestValidationException validate();
}

Usage:

// Create evaluation specification
RankEvalSpec spec = new RankEvalSpec(ratedRequests, metric);

// Create request targeting specific indices
RankEvalRequest request = new RankEvalRequest(spec, new String[]{"products", "catalog"});

// Configure search options
request.searchType(SearchType.DFS_QUERY_THEN_FETCH);
request.indicesOptions(IndicesOptions.strictExpandOpen());

RankEvalResponse

Response containing evaluation results and per-query details.

public class RankEvalResponse extends ActionResponse implements ToXContentObject {
    // Constructor
    public RankEvalResponse(double metricScore, Map<String, EvalQueryQuality> partialResults, Map<String, Exception> failures);
    
    // Result access methods
    public double getMetricScore();
    public Map<String, EvalQueryQuality> getPartialResults();
    public Map<String, Exception> getFailures();
    
    // Serialization
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
    public static RankEvalResponse fromXContent(XContentParser parser) throws IOException;
}

Usage:

// Execute request and access results
RankEvalResponse response = client.execute(RankEvalAction.INSTANCE, request).get();

// Get overall evaluation score
double overallScore = response.getMetricScore();

// Access per-query results
Map<String, EvalQueryQuality> queryResults = response.getPartialResults();
for (Map.Entry<String, EvalQueryQuality> entry : queryResults.entrySet()) {
    String queryId = entry.getKey();
    EvalQueryQuality quality = entry.getValue();
    double queryScore = quality.metricScore();
    System.out.println("Query " + queryId + " score: " + queryScore);
}

// Check for failures
Map<String, Exception> failures = response.getFailures();
if (!failures.isEmpty()) {
    System.out.println("Failed queries: " + failures.keySet());
}

RankEvalSpec

Specification containing the complete evaluation configuration.

public class RankEvalSpec implements Writeable, ToXContentObject {
    // Constructors
    public RankEvalSpec(List<RatedRequest> ratedRequests, EvaluationMetric metric);
    public RankEvalSpec(List<RatedRequest> ratedRequests, EvaluationMetric metric, Collection<ScriptWithId> templates);
    
    // Core configuration access
    public EvaluationMetric getMetric();
    public List<RatedRequest> getRatedRequests();
    public Map<String, Script> getTemplates();
    
    // Concurrency control
    public int getMaxConcurrentSearches();
    public void setMaxConcurrentSearches(int maxConcurrentSearches);
    
    // Parsing and serialization
    public static RankEvalSpec parse(XContentParser parser);
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
}

Usage:

// Create basic specification
RankEvalSpec spec = new RankEvalSpec(ratedRequests, new PrecisionAtK());

// Create specification with templates
List<ScriptWithId> templates = Arrays.asList(
    new ScriptWithId("product_search", new Script("mustache", "{{query_string}}", templateParams))
);
RankEvalSpec specWithTemplates = new RankEvalSpec(ratedRequests, metric, templates);

// Configure concurrency
spec.setMaxConcurrentSearches(5);

RankEvalRequestBuilder

Builder class for constructing rank evaluation requests.

public class RankEvalRequestBuilder extends ActionRequestBuilder<RankEvalRequest, RankEvalResponse> {
    // Constructor
    public RankEvalRequestBuilder(ElasticsearchClient client, ActionType<RankEvalResponse> action, RankEvalRequest request);
    
    // Request access and modification
    public RankEvalRequest request();
    public void setRankEvalSpec(RankEvalSpec spec);
    public RankEvalSpec getRankEvalSpec();
}

Usage:

// Using request builder
RankEvalRequestBuilder builder = new RankEvalRequestBuilder(client, RankEvalAction.INSTANCE, new RankEvalRequest());
builder.setRankEvalSpec(spec);
RankEvalResponse response = builder.execute().actionGet();

RatedRequest

Individual query with its rated documents for evaluation.

public class RatedRequest implements Writeable, ToXContentObject {
    // Core properties access
    public String getId();
    public SearchSourceBuilder getEvaluationRequest();
    public List<RatedDocument> getRatedDocs();
    
    // Template-based evaluation
    public String getTemplateId(); 
    public Map<String, Object> getParams();
    
    // Serialization
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
    public static RatedRequest fromXContent(XContentParser parser) throws IOException;
}

Usage:

// Create search request
SearchSourceBuilder searchSource = SearchSourceBuilder.searchSource()
    .query(QueryBuilders.multiMatchQuery("smartphone", "title", "description"))
    .size(50);

// Create rated documents
List<RatedDocument> ratedDocs = Arrays.asList(
    new RatedDocument("products", "iphone_13", 3),      // highly relevant
    new RatedDocument("products", "samsung_s21", 2),    // relevant  
    new RatedDocument("products", "old_phone", 0)       // not relevant
);

// Create rated request  
RatedRequest ratedRequest = new RatedRequest(
    "smartphone_search",           // query identifier
    Arrays.asList("products"),     // target indices
    searchSource,                  // search request
    ratedDocs                      // document ratings
);

RatedDocument

Document with its relevance rating for a specific query.

public class RatedDocument implements Writeable, ToXContentObject {
    // Constructor
    public RatedDocument(String index, String id, int rating);
    
    // Property access
    public DocumentKey getKey();
    public int getRating();
    
    // Serialization
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
    public static RatedDocument fromXContent(XContentParser parser) throws IOException;
    
    // Nested DocumentKey class
    public static class DocumentKey {
        public DocumentKey(String index, String id);
        public String getIndex();
        public String getId();
    }
}

Usage:

// Create rated documents with different relevance levels
List<RatedDocument> ratedDocs = Arrays.asList(
    new RatedDocument("articles", "elasticsearch_guide", 3),  // perfect match
    new RatedDocument("articles", "search_basics", 2),        // good match
    new RatedDocument("articles", "database_intro", 1),       // marginal relevance
    new RatedDocument("articles", "cooking_tips", 0)          // not relevant
);

// Access document properties
for (RatedDocument doc : ratedDocs) {
    DocumentKey key = doc.getKey();
    int rating = doc.getRating();
    System.out.println("Document " + key.getId() + " in " + key.getIndex() + ": rating " + rating);
}

Request Execution Patterns

Synchronous Execution

// Direct execution using transport client
RankEvalRequest request = new RankEvalRequest(spec, indices);
RankEvalResponse response = client.execute(RankEvalAction.INSTANCE, request).get();

Asynchronous Execution

// Async execution with callback
client.execute(RankEvalAction.INSTANCE, request, new ActionListener<RankEvalResponse>() {
    @Override
    public void onResponse(RankEvalResponse response) {
        double score = response.getMetricScore();
        // Process results
    }
    
    @Override
    public void onFailure(Exception e) {
        // Handle failure
    }
});

Template-Based Evaluation

// Create template script
Script template = new Script(
    ScriptType.INLINE,
    "mustache", 
    "{\"query\": {\"match\": {\"{{field}}\": \"{{query}}\"}}}",
    Collections.emptyMap()
);

// Create template wrapper
ScriptWithId scriptWithId = new ScriptWithId("search_template", template);

// Create rated request using template
RatedRequest templateRequest = new RatedRequest(
    "templated_query",
    "search_template",
    Map.of("field", "title", "query", "elasticsearch"),
    ratedDocs
);

// Include in specification
RankEvalSpec spec = new RankEvalSpec(
    Arrays.asList(templateRequest),
    metric,
    Arrays.asList(scriptWithId)
);

Error Handling

try {
    RankEvalResponse response = client.execute(RankEvalAction.INSTANCE, request).get();
    
    // Check for partial failures
    Map<String, Exception> failures = response.getFailures();
    if (!failures.isEmpty()) {
        for (Map.Entry<String, Exception> failure : failures.entrySet()) {
            System.err.println("Query " + failure.getKey() + " failed: " + failure.getValue().getMessage());
        }
    }
    
} catch (ExecutionException e) {
    if (e.getCause() instanceof ElasticsearchException) {
        ElasticsearchException esException = (ElasticsearchException) e.getCause();
        System.err.println("Elasticsearch error: " + esException.getMessage());
    }
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
    System.err.println("Request interrupted");
}

Install with Tessl CLI

npx tessl i tessl/maven-org-elasticsearch-plugin--rank-eval-client

docs

configuration-utilities.md

evaluation-metrics.md

index.md

request-response-api.md

tile.json