0
# Request and Response API
1

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

4
## Core Classes
5

6
### RankEvalRequest
7

8
Main request class for ranking evaluation operations.
9

10
```java { .api }
11
public class RankEvalRequest extends ActionRequest implements IndicesRequest.Replaceable {
12
    // Constructors
13
    public RankEvalRequest(RankEvalSpec rankingEvaluationSpec, String[] indices);
14
    RankEvalRequest(); // package-private
15
    
16
    // Evaluation specification methods
17
    public RankEvalSpec getRankEvalSpec();
18
    public void setRankEvalSpec(RankEvalSpec task);
19
    
20
    // Index targeting methods
21
    public RankEvalRequest indices(String... indices);
22
    public String[] indices();
23
    
24
    // Options and configuration
25
    public IndicesOptions indicesOptions();
26
    public void indicesOptions(IndicesOptions indicesOptions);
27
    public SearchType searchType();
28
    public void searchType(SearchType searchType);
29
    
30
    // Validation
31
    public ActionRequestValidationException validate();
32
}
33
```
34

35
**Usage:**
36
```java
37
// Create evaluation specification
38
RankEvalSpec spec = new RankEvalSpec(ratedRequests, metric);
39

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

43
// Configure search options
44
request.searchType(SearchType.DFS_QUERY_THEN_FETCH);
45
request.indicesOptions(IndicesOptions.strictExpandOpen());
46
```
47

48
### RankEvalResponse
49

50
Response containing evaluation results and per-query details.
51

52
```java { .api }
53
public class RankEvalResponse extends ActionResponse implements ToXContentObject {
54
    // Constructor
55
    public RankEvalResponse(double metricScore, Map<String, EvalQueryQuality> partialResults, Map<String, Exception> failures);
56
    
57
    // Result access methods
58
    public double getMetricScore();
59
    public Map<String, EvalQueryQuality> getPartialResults();
60
    public Map<String, Exception> getFailures();
61
    
62
    // Serialization
63
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
64
    public static RankEvalResponse fromXContent(XContentParser parser) throws IOException;
65
}
66
```
67

68
**Usage:**
69
```java
70
// Execute request and access results
71
RankEvalResponse response = client.execute(RankEvalAction.INSTANCE, request).get();
72

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

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

85
// Check for failures
86
Map<String, Exception> failures = response.getFailures();
87
if (!failures.isEmpty()) {
88
    System.out.println("Failed queries: " + failures.keySet());
89
}
90
```
91

92
### RankEvalSpec
93

94
Specification containing the complete evaluation configuration.
95

96
```java { .api }
97
public class RankEvalSpec implements Writeable, ToXContentObject {
98
    // Constructors
99
    public RankEvalSpec(List<RatedRequest> ratedRequests, EvaluationMetric metric);
100
    public RankEvalSpec(List<RatedRequest> ratedRequests, EvaluationMetric metric, Collection<ScriptWithId> templates);
101
    
102
    // Core configuration access
103
    public EvaluationMetric getMetric();
104
    public List<RatedRequest> getRatedRequests();
105
    public Map<String, Script> getTemplates();
106
    
107
    // Concurrency control
108
    public int getMaxConcurrentSearches();
109
    public void setMaxConcurrentSearches(int maxConcurrentSearches);
110
    
111
    // Parsing and serialization
112
    public static RankEvalSpec parse(XContentParser parser);
113
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
114
}
115
```
116

117
**Usage:**
118
```java
119
// Create basic specification
120
RankEvalSpec spec = new RankEvalSpec(ratedRequests, new PrecisionAtK());
121

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

128
// Configure concurrency
129
spec.setMaxConcurrentSearches(5);
130
```
131

132
### RankEvalRequestBuilder
133

134
Builder class for constructing rank evaluation requests.
135

136
```java { .api }
137
public class RankEvalRequestBuilder extends ActionRequestBuilder<RankEvalRequest, RankEvalResponse> {
138
    // Constructor
139
    public RankEvalRequestBuilder(ElasticsearchClient client, ActionType<RankEvalResponse> action, RankEvalRequest request);
140
    
141
    // Request access and modification
142
    public RankEvalRequest request();
143
    public void setRankEvalSpec(RankEvalSpec spec);
144
    public RankEvalSpec getRankEvalSpec();
145
}
146
```
147

148
**Usage:**
149
```java
150
// Using request builder
151
RankEvalRequestBuilder builder = new RankEvalRequestBuilder(client, RankEvalAction.INSTANCE, new RankEvalRequest());
152
builder.setRankEvalSpec(spec);
153
RankEvalResponse response = builder.execute().actionGet();
154
```
155

156
### RatedRequest
157

158
Individual query with its rated documents for evaluation.
159

160
```java { .api }
161
public class RatedRequest implements Writeable, ToXContentObject {
162
    // Core properties access
163
    public String getId();
164
    public SearchSourceBuilder getEvaluationRequest();
165
    public List<RatedDocument> getRatedDocs();
166
    
167
    // Template-based evaluation
168
    public String getTemplateId(); 
169
    public Map<String, Object> getParams();
170
    
171
    // Serialization
172
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
173
    public static RatedRequest fromXContent(XContentParser parser) throws IOException;
174
}
175
```
176

177
**Usage:**
178
```java
179
// Create search request
180
SearchSourceBuilder searchSource = SearchSourceBuilder.searchSource()
181
    .query(QueryBuilders.multiMatchQuery("smartphone", "title", "description"))
182
    .size(50);
183

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

191
// Create rated request  
192
RatedRequest ratedRequest = new RatedRequest(
193
    "smartphone_search",           // query identifier
194
    Arrays.asList("products"),     // target indices
195
    searchSource,                  // search request
196
    ratedDocs                      // document ratings
197
);
198
```
199

200
### RatedDocument
201

202
Document with its relevance rating for a specific query.
203

204
```java { .api }
205
public class RatedDocument implements Writeable, ToXContentObject {
206
    // Constructor
207
    public RatedDocument(String index, String id, int rating);
208
    
209
    // Property access
210
    public DocumentKey getKey();
211
    public int getRating();
212
    
213
    // Serialization
214
    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
215
    public static RatedDocument fromXContent(XContentParser parser) throws IOException;
216
    
217
    // Nested DocumentKey class
218
    public static class DocumentKey {
219
        public DocumentKey(String index, String id);
220
        public String getIndex();
221
        public String getId();
222
    }
223
}
224
```
225

226
**Usage:**
227
```java
228
// Create rated documents with different relevance levels
229
List<RatedDocument> ratedDocs = Arrays.asList(
230
    new RatedDocument("articles", "elasticsearch_guide", 3),  // perfect match
231
    new RatedDocument("articles", "search_basics", 2),        // good match
232
    new RatedDocument("articles", "database_intro", 1),       // marginal relevance
233
    new RatedDocument("articles", "cooking_tips", 0)          // not relevant
234
);
235

236
// Access document properties
237
for (RatedDocument doc : ratedDocs) {
238
    DocumentKey key = doc.getKey();
239
    int rating = doc.getRating();
240
    System.out.println("Document " + key.getId() + " in " + key.getIndex() + ": rating " + rating);
241
}
242
```
243

244
## Request Execution Patterns
245

246
### Synchronous Execution
247

248
```java
249
// Direct execution using transport client
250
RankEvalRequest request = new RankEvalRequest(spec, indices);
251
RankEvalResponse response = client.execute(RankEvalAction.INSTANCE, request).get();
252
```
253

254
### Asynchronous Execution
255

256
```java
257
// Async execution with callback
258
client.execute(RankEvalAction.INSTANCE, request, new ActionListener<RankEvalResponse>() {
259
    @Override
260
    public void onResponse(RankEvalResponse response) {
261
        double score = response.getMetricScore();
262
        // Process results
263
    }
264
    
265
    @Override
266
    public void onFailure(Exception e) {
267
        // Handle failure
268
    }
269
});
270
```
271

272
### Template-Based Evaluation
273

274
```java
275
// Create template script
276
Script template = new Script(
277
    ScriptType.INLINE,
278
    "mustache", 
279
    "{\"query\": {\"match\": {\"{{field}}\": \"{{query}}\"}}}",
280
    Collections.emptyMap()
281
);
282

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

286
// Create rated request using template
287
RatedRequest templateRequest = new RatedRequest(
288
    "templated_query",
289
    "search_template",
290
    Map.of("field", "title", "query", "elasticsearch"),
291
    ratedDocs
292
);
293

294
// Include in specification
295
RankEvalSpec spec = new RankEvalSpec(
296
    Arrays.asList(templateRequest),
297
    metric,
298
    Arrays.asList(scriptWithId)
299
);
300
```
301

302
## Error Handling
303

304
```java
305
try {
306
    RankEvalResponse response = client.execute(RankEvalAction.INSTANCE, request).get();
307
    
308
    // Check for partial failures
309
    Map<String, Exception> failures = response.getFailures();
310
    if (!failures.isEmpty()) {
311
        for (Map.Entry<String, Exception> failure : failures.entrySet()) {
312
            System.err.println("Query " + failure.getKey() + " failed: " + failure.getValue().getMessage());
313
        }
314
    }
315
    
316
} catch (ExecutionException e) {
317
    if (e.getCause() instanceof ElasticsearchException) {
318
        ElasticsearchException esException = (ElasticsearchException) e.getCause();
319
        System.err.println("Elasticsearch error: " + esException.getMessage());
320
    }
321
} catch (InterruptedException e) {
322
    Thread.currentThread().interrupt();
323
    System.err.println("Request interrupted");
324
}
325
```