Skip to content

Commit 7a7248d

Browse files
nik9000nik9000
committed
Docs: HighLevelRestClient#multiGet (#29095)
Add documentation for HighLevelRestClient#multiGet. Relates to #28389.
1 parent a1f7087 commit 7a7248d

File tree

3 files changed

+377
-1
lines changed

3 files changed

+377
-1
lines changed

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java‎

Lines changed: 207 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,14 @@
3737
import org.elasticsearch.action.delete.DeleteResponse;
3838
import org.elasticsearch.action.get.GetRequest;
3939
import org.elasticsearch.action.get.GetResponse;
40+
import org.elasticsearch.action.get.MultiGetItemResponse;
41+
import org.elasticsearch.action.get.MultiGetRequest;
42+
import org.elasticsearch.action.get.MultiGetResponse;
4043
import org.elasticsearch.action.index.IndexRequest;
4144
import org.elasticsearch.action.index.IndexResponse;
4245
import org.elasticsearch.action.support.ActiveShardCount;
4346
import org.elasticsearch.action.support.WriteRequest;
47+
import org.elasticsearch.action.support.WriteRequest.RefreshPolicy;
4448
import org.elasticsearch.action.support.replication.ReplicationResponse;
4549
import org.elasticsearch.action.update.UpdateRequest;
4650
import org.elasticsearch.action.update.UpdateResponse;
@@ -68,6 +72,11 @@
6872
import java.util.concurrent.CountDownLatch;
6973
import java.util.concurrent.TimeUnit;
7074

75+
import static org.hamcrest.Matchers.arrayWithSize;
76+
import static org.hamcrest.Matchers.hasEntry;
77+
import static org.hamcrest.Matchers.containsString;
78+
import static org.hamcrest.Matchers.hasKey;
79+
import static org.hamcrest.Matchers.not;
7180
import static java.util.Collections.emptyMap;
7281
import static java.util.Collections.singletonMap;
7382

@@ -809,7 +818,7 @@ public void testGet() throws Exception {
809818
{
810819
GetRequest request = new GetRequest("posts", "doc", "1");
811820
//tag::get-request-no-source
812-
request.fetchSourceContext(new FetchSourceContext(false)); // <1>
821+
request.fetchSourceContext(FetchSourceContext.DO_NOT_FETCH_SOURCE); // <1>
813822
//end::get-request-no-source
814823
GetResponse getResponse = client.get(request);
815824
assertNull(getResponse.getSourceInternal());
@@ -1066,4 +1075,201 @@ public void afterBulk(long executionId, BulkRequest request, Throwable failure)
10661075
// end::bulk-processor-options
10671076
}
10681077
}
1078+
1079+
public void testMultiGet() throws Exception {
1080+
RestHighLevelClient client = highLevelClient();
1081+
1082+
{
1083+
String mappings = "{\n" +
1084+
" \"mappings\" : {\n" +
1085+
" \"type\" : {\n" +
1086+
" \"properties\" : {\n" +
1087+
" \"foo\" : {\n" +
1088+
" \"type\": \"text\",\n" +
1089+
" \"store\": true\n" +
1090+
" }\n" +
1091+
" }\n" +
1092+
" }\n" +
1093+
" }\n" +
1094+
"}";
1095+
1096+
NStringEntity entity = new NStringEntity(mappings, ContentType.APPLICATION_JSON);
1097+
Response response = client().performRequest("PUT", "/index", Collections.emptyMap(), entity);
1098+
assertEquals(200, response.getStatusLine().getStatusCode());
1099+
}
1100+
1101+
Map<String, Object> source = new HashMap<>();
1102+
source.put("foo", "val1");
1103+
source.put("bar", "val2");
1104+
source.put("baz", "val3");
1105+
client.index(new IndexRequest("index", "type", "example_id")
1106+
.source(source)
1107+
.setRefreshPolicy(RefreshPolicy.IMMEDIATE));
1108+
1109+
{
1110+
// tag::multi-get-request
1111+
MultiGetRequest request = new MultiGetRequest();
1112+
request.add(new MultiGetRequest.Item(
1113+
"index", // <1>
1114+
"type", // <2>
1115+
"example_id")); // <3>
1116+
request.add(new MultiGetRequest.Item("index", "type", "another_id")); // <4>
1117+
// end::multi-get-request
1118+
1119+
// Add a missing index so we can test it.
1120+
request.add(new MultiGetRequest.Item("missing_index", "type", "id"));
1121+
1122+
// tag::multi-get-request-item-extras
1123+
request.add(new MultiGetRequest.Item("index", "type", "with_routing")
1124+
.routing("some_routing")); // <1>
1125+
request.add(new MultiGetRequest.Item("index", "type", "with_parent")
1126+
.parent("some_parent")); // <2>
1127+
request.add(new MultiGetRequest.Item("index", "type", "with_version")
1128+
.versionType(VersionType.EXTERNAL) // <3>
1129+
.version(10123L)); // <4>
1130+
// end::multi-get-request-item-extras
1131+
// tag::multi-get-request-top-level-extras
1132+
request.preference("some_preference"); // <1>
1133+
request.realtime(false); // <2>
1134+
request.refresh(true); // <3>
1135+
// end::multi-get-request-top-level-extras
1136+
1137+
// tag::multi-get-execute
1138+
MultiGetResponse response = client.multiGet(request);
1139+
// end::multi-get-execute
1140+
1141+
// tag::multi-get-response
1142+
MultiGetItemResponse firstItem = response.getResponses()[0];
1143+
assertNull(firstItem.getFailure()); // <1>
1144+
GetResponse firstGet = firstItem.getResponse(); // <2>
1145+
String index = firstItem.getIndex();
1146+
String type = firstItem.getType();
1147+
String id = firstItem.getId();
1148+
if (firstGet.isExists()) {
1149+
long version = firstGet.getVersion();
1150+
String sourceAsString = firstGet.getSourceAsString(); // <3>
1151+
Map<String, Object> sourceAsMap = firstGet.getSourceAsMap(); // <4>
1152+
byte[] sourceAsBytes = firstGet.getSourceAsBytes(); // <5>
1153+
} else {
1154+
// <6>
1155+
}
1156+
// end::multi-get-response
1157+
1158+
assertTrue(firstGet.isExists());
1159+
assertEquals(source, firstGet.getSource());
1160+
1161+
MultiGetItemResponse missingIndexItem = response.getResponses()[2];
1162+
// tag::multi-get-indexnotfound
1163+
assertNull(missingIndexItem.getResponse()); // <1>
1164+
Exception e = missingIndexItem.getFailure().getFailure(); // <2>
1165+
ElasticsearchException ee = (ElasticsearchException) e; // <3>
1166+
// TODO status is broken! fix in a followup
1167+
// assertEquals(RestStatus.NOT_FOUND, ee.status()); // <4>
1168+
assertThat(e.getMessage(),
1169+
containsString("reason=no such index")); // <5>
1170+
// end::multi-get-indexnotfound
1171+
1172+
// tag::multi-get-execute-listener
1173+
ActionListener<MultiGetResponse> listener = new ActionListener<MultiGetResponse>() {
1174+
@Override
1175+
public void onResponse(MultiGetResponse response) {
1176+
// <1>
1177+
}
1178+
1179+
@Override
1180+
public void onFailure(Exception e) {
1181+
// <2>
1182+
}
1183+
};
1184+
// end::multi-get-execute-listener
1185+
1186+
// Replace the empty listener by a blocking listener in test
1187+
final CountDownLatch latch = new CountDownLatch(1);
1188+
listener = new LatchedActionListener<>(listener, latch);
1189+
1190+
// tag::multi-get-execute-async
1191+
client.multiGetAsync(request, listener); // <1>
1192+
// end::multi-get-execute-async
1193+
1194+
assertTrue(latch.await(30L, TimeUnit.SECONDS));
1195+
}
1196+
{
1197+
MultiGetRequest request = new MultiGetRequest();
1198+
// tag::multi-get-request-no-source
1199+
request.add(new MultiGetRequest.Item("index", "type", "example_id")
1200+
.fetchSourceContext(FetchSourceContext.DO_NOT_FETCH_SOURCE)); // <1>
1201+
// end::multi-get-request-no-source
1202+
MultiGetItemResponse item = unwrapAndAssertExample(client.multiGet(request));
1203+
assertNull(item.getResponse().getSource());
1204+
}
1205+
{
1206+
MultiGetRequest request = new MultiGetRequest();
1207+
// tag::multi-get-request-source-include
1208+
String[] includes = new String[] {"foo", "*r"};
1209+
String[] excludes = Strings.EMPTY_ARRAY;
1210+
FetchSourceContext fetchSourceContext =
1211+
new FetchSourceContext(true, includes, excludes);
1212+
request.add(new MultiGetRequest.Item("index", "type", "example_id")
1213+
.fetchSourceContext(fetchSourceContext)); // <1>
1214+
// end::multi-get-request-source-include
1215+
MultiGetItemResponse item = unwrapAndAssertExample(client.multiGet(request));
1216+
assertThat(item.getResponse().getSource(), hasEntry("foo", "val1"));
1217+
assertThat(item.getResponse().getSource(), hasEntry("bar", "val2"));
1218+
assertThat(item.getResponse().getSource(), not(hasKey("baz")));
1219+
}
1220+
{
1221+
MultiGetRequest request = new MultiGetRequest();
1222+
// tag::multi-get-request-source-exclude
1223+
String[] includes = Strings.EMPTY_ARRAY;
1224+
String[] excludes = new String[] {"foo", "*r"};
1225+
FetchSourceContext fetchSourceContext =
1226+
new FetchSourceContext(true, includes, excludes);
1227+
request.add(new MultiGetRequest.Item("index", "type", "example_id")
1228+
.fetchSourceContext(fetchSourceContext)); // <1>
1229+
// end::multi-get-request-source-exclude
1230+
MultiGetItemResponse item = unwrapAndAssertExample(client.multiGet(request));
1231+
assertThat(item.getResponse().getSource(), not(hasKey("foo")));
1232+
assertThat(item.getResponse().getSource(), not(hasKey("bar")));
1233+
assertThat(item.getResponse().getSource(), hasEntry("baz", "val3"));
1234+
}
1235+
{
1236+
MultiGetRequest request = new MultiGetRequest();
1237+
// tag::multi-get-request-stored
1238+
request.add(new MultiGetRequest.Item("index", "type", "example_id")
1239+
.storedFields("foo")); // <1>
1240+
MultiGetResponse response = client.multiGet(request);
1241+
MultiGetItemResponse item = response.getResponses()[0];
1242+
String value = item.getResponse().getField("foo").getValue(); // <2>
1243+
// end::multi-get-request-stored
1244+
assertNull(item.getResponse().getSource());
1245+
assertEquals("val1", value);
1246+
}
1247+
{
1248+
// tag::multi-get-conflict
1249+
MultiGetRequest request = new MultiGetRequest();
1250+
request.add(new MultiGetRequest.Item("index", "type", "example_id")
1251+
.version(1000L));
1252+
MultiGetResponse response = client.multiGet(request);
1253+
MultiGetItemResponse item = response.getResponses()[0];
1254+
assertNull(item.getResponse()); // <1>
1255+
Exception e = item.getFailure().getFailure(); // <2>
1256+
ElasticsearchException ee = (ElasticsearchException) e; // <3>
1257+
// TODO status is broken! fix in a followup
1258+
// assertEquals(RestStatus.CONFLICT, ee.status()); // <4>
1259+
assertThat(e.getMessage(),
1260+
containsString("version conflict, current version [1] is "
1261+
+ "different than the one provided [1000]")); // <5>
1262+
// end::multi-get-conflict
1263+
}
1264+
1265+
}
1266+
1267+
private MultiGetItemResponse unwrapAndAssertExample(MultiGetResponse response) {
1268+
assertThat(response.getResponses(), arrayWithSize(1));
1269+
MultiGetItemResponse item = response.getResponses()[0];
1270+
assertEquals("index", item.getIndex());
1271+
assertEquals("type", item.getType());
1272+
assertEquals("example_id", item.getId());
1273+
return item;
1274+
}
10691275
}

0 commit comments

Comments
 (0)