Multi-Get API

multiGet API並行地在單個http請求中執行多個get請求。

Multi-Get Request

MultiGetRequest構造函數爲空，須要你添加`MultiGetRequest.Item`來配置要獲取的內容：

        MultiGetRequest request = new MultiGetRequest();
        request.add(new MultiGetRequest.Item(
                "index", // Index
                "type",  // Type
                "example_id")); //Document id
        //再添加一個
        request.add(new MultiGetRequest.Item("index", "type", "another_id"));

可選參數

get API支持的可選參數，multiGet都支持。 您能夠在每一項上設置這些大部分可選參數，爲何是大部分，由於有的參數是設置在主請求上，而不是每一項上：

 　　　　//禁止獲取source，默認爲啓用
        request.add(new MultiGetRequest.Item("index", "type", "example_id")
                .fetchSourceContext(FetchSourceContext.DO_NOT_FETCH_SOURCE));

配置source包含指定的字段：

        String[] includes = new String[] {"foo", "*r"};
        String[] excludes = Strings.EMPTY_ARRAY;
        FetchSourceContext fetchSourceContext =
                new FetchSourceContext(true, includes, excludes);
        request.add(new MultiGetRequest.Item("index", "type", "example_id")
                .fetchSourceContext(fetchSourceContext));

配置source排除指定的字段：

        String[] includes1 = Strings.EMPTY_ARRAY;
        String[] excludes1 = new String[] {"foo", "*r"};
        FetchSourceContext fetchSourceContext1 =
                new FetchSourceContext(true, includes, excludes);
        request.add(new MultiGetRequest.Item("index", "type", "example_id")
                .fetchSourceContext(fetchSourceContext1));

        //配置獲取指定的stored字段，要求字段在mappings中是分開存儲的（stored存儲的原始字段，未通過分詞的）
        request.add(new MultiGetRequest.Item("index", "type", "example_id")
                .storedFields("foo"));
        MultiGetResponse response = client.multiGet(request);
        MultiGetItemResponse item = response.getResponses()[0];
        //獲取foo的stored字段，要求字段和mappings中是分開存儲的
        String value = item.getResponse().getField("foo").getValue();

       // Routing value
        request.add(new MultiGetRequest.Item("index", "type", "with_routing")
                .routing("some_routing"));
        // Parent value
        request.add(new MultiGetRequest.Item("index", "type", "with_parent")
                .parent("some_parent"));
        request.add(new MultiGetRequest.Item("index", "type", "with_version")
                .versionType(VersionType.EXTERNAL)// Version type
                .version(10123L));//Version 

preference, realtime 和 refresh能夠設置在主請求上，而不能設置在每項上

        request.preference("some_preference");//preference值
        request.realtime(false);//將realtime標誌設置爲false（默認爲true）
        request.refresh(true);//在檢索文檔以前執行刷新（默認爲false）

同步執行

        //構建MultiGetRequest後，您能夠用multiGet來同步執行：
        MultiGetResponse response1 = client.multiGet(request);

異步執行

異步執行多個get請求須要將MultiGetRequest實例和ActionListener實例傳遞給異步方法：

client.multiGetAsync(request, listener); //當MultiGetRequest執行完成時，ActionListener將被調用。

異步方法不會阻塞並會當即返回。 一旦請求完成，若是執行成功完成，則使用onResponse方法回調ActionListener，若是失敗則使用onFailure方法。

MultiGetResponse的典型監聽器以下所示：

        ActionListener<MultiGetResponse> listener = new ActionListener<MultiGetResponse>() {
            @Override
            public void onResponse(MultiGetResponse response) {
                //執行成功完成時調用。  response以參數的形式提供。
            }

            @Override
            public void onFailure(Exception e) {
                // 在失敗的狀況下調用。 引起的異常做爲參數提供。
            }
        };

Multi Get Response

返回的MultiGetResponse在getResponses中包含一個MultiGetItemResponse的列表，其順序與請求的順序相同。 若是獲取成功，MultiGetItemResponse包含GetResponse，若是失敗則包含MultiGetResponse.Failure。 成功看起來就像普通的GetResponse。

   MultiGetItemResponse firstItem = response.getResponses()[0];
        //assertNull(firstItem.getFailure());//getFailure返回null，因爲這沒有失敗。
        GetResponse firstGet = firstItem.getResponse();//getResponse返回GetResponse。
        String index = firstItem.getIndex();
        String type = firstItem.getType();
        String id = firstItem.getId();
        if (firstGet.isExists()) {
            long version = firstGet.getVersion();
            String sourceAsString = firstGet.getSourceAsString();//以字符串形式獲取文檔
            Map<String, Object> sourceAsMap = firstGet.getSourceAsMap();//以Map <String，Object>形式獲取文檔
            byte[] sourceAsBytes = firstGet.getSourceAsBytes();//以字節數組的形式檢索文檔
        } else {
            //處理未找到文檔的方案。 請注意，雖然返回的響應具備404狀態代碼，但仍返回有效的GetResponse而不是拋出異常。
            //此時此類響應不持有任何源文檔，而且其isExists方法返回false。
　　　　 }

當其中一個子請求執行不存在的索引時，getFailure將包含異常：

            MultiGetItemResponse missingIndexItem = response.getResponses()[0];
            assertNull(missingIndexItem.getResponse());//getResponse 是 null.
            //getFailure不爲null，而且包含Exception,該異常其實是一個ElasticsearchException
            Exception e = missingIndexItem.getFailure().getFailure();
            ElasticsearchException ee = (ElasticsearchException) e;
            // TODO status is broken! fix in a followup
            //此時它的狀態爲NOT_FOUND。 要不是這是一個multi get，它其實就是一個HTTP 404。
            assertEquals(RestStatus.NOT_FOUND, ee.status());
            //getMessage解釋了實際緣由，沒有這樣的索引。
            assertThat(e.getMessage(),containsString("reason=no such index"));

若是請求特定文檔版本，而且現有文檔具備不一樣的版本號，則會引起版本衝突：

　　　　　MultiGetRequest request2 = new MultiGetRequest();
        request2.add(new MultiGetRequest.Item("index", "type", "example_id")
                .version(1000L));
        MultiGetResponse response2 = client.multiGet(request2);
        MultiGetItemResponse item2 = response.getResponses()[0];
        assertNull(item.getResponse());//getResponse 是 null.
        //getFailure不爲null，而且包含Exception,該異常其實是一個ElasticsearchException
        Exception e = item.getFailure().getFailure();
        ElasticsearchException ee = (ElasticsearchException) e;
        // TODO status is broken! fix in a followup
        //此時它的狀態爲NOT_FOUND。 要不是這是一個multi get，它就是一個HTTP 409 。
        // assertEquals(RestStatus.CONFLICT, ee.status());
        //getMessage解釋了實際緣由，即版本衝突。
        assertThat(e.getMessage(),
        containsString("version conflict, current version [1] is "
                        + "different than the one provided [1000]"));

 

官方文檔：https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/java-rest-high-document-multi-get.html