HLRC: Add ML Get Records API (#33085)

Relates #29827

client/rest-high-level/src/main/java/org/elasticsearch/client/MLRequestConverters.java

@@ -28,6 +28,7 @@ import org.elasticsearch.client.ml.CloseJobRequest;
 import org.elasticsearch.client.ml.DeleteJobRequest;
 import org.elasticsearch.client.ml.GetBucketsRequest;
 import org.elasticsearch.client.ml.GetJobRequest;
+import org.elasticsearch.client.ml.GetRecordsRequest;
 import org.elasticsearch.client.ml.OpenJobRequest;
 import org.elasticsearch.client.ml.PutJobRequest;
 import org.elasticsearch.common.Strings;
@@ -124,4 +125,18 @@ final class MLRequestConverters {
         request.setEntity(createEntity(getBucketsRequest, REQUEST_BODY_CONTENT_TYPE));
         return request;
     }
+
+    static Request getRecords(GetRecordsRequest getRecordsRequest) throws IOException {
+        String endpoint = new EndpointBuilder()
+                .addPathPartAsIs("_xpack")
+                .addPathPartAsIs("ml")
+                .addPathPartAsIs("anomaly_detectors")
+                .addPathPart(getRecordsRequest.getJobId())
+                .addPathPartAsIs("results")
+                .addPathPartAsIs("records")
+                .build();
+        Request request = new Request(HttpGet.METHOD_NAME, endpoint);
+        request.setEntity(createEntity(getRecordsRequest, REQUEST_BODY_CONTENT_TYPE));
+        return request;
+    }
 }

client/rest-high-level/src/main/java/org/elasticsearch/client/MachineLearningClient.java

@@ -27,6 +27,8 @@ import org.elasticsearch.client.ml.GetBucketsRequest;
 import org.elasticsearch.client.ml.GetBucketsResponse;
 import org.elasticsearch.client.ml.GetJobRequest;
 import org.elasticsearch.client.ml.GetJobResponse;
+import org.elasticsearch.client.ml.GetRecordsRequest;
+import org.elasticsearch.client.ml.GetRecordsResponse;
 import org.elasticsearch.client.ml.OpenJobRequest;
 import org.elasticsearch.client.ml.OpenJobResponse;
 import org.elasticsearch.client.ml.PutJobRequest;
@@ -285,4 +287,40 @@ public final class MachineLearningClient {
                 listener,
                 Collections.emptySet());
      }
+
+    /**
+     * Gets the records for a Machine Learning Job.
+     * <p>
+     * For additional info
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-record.html">ML GET records documentation</a>
+     *
+     * @param request  the request
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     */
+    public GetRecordsResponse getRecords(GetRecordsRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request,
+                MLRequestConverters::getRecords,
+                options,
+                GetRecordsResponse::fromXContent,
+                Collections.emptySet());
+    }
+
+    /**
+     * Gets the records for a Machine Learning Job, notifies listener once the requested records are retrieved.
+     * <p>
+     * For additional info
+     * see <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-record.html">ML GET records documentation</a>
+     *
+     * @param request  the request
+     * @param options  Additional request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener Listener to be notified upon request completion
+     */
+    public void getRecordsAsync(GetRecordsRequest request, RequestOptions options, ActionListener<GetRecordsResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request,
+                MLRequestConverters::getRecords,
+                options,
+                GetRecordsResponse::fromXContent,
+                listener,
+                Collections.emptySet());
+    }
 }

client/rest-high-level/src/main/java/org/elasticsearch/client/ml/GetRecordsRequest.java

@@ -0,0 +1,222 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client.ml;
+
+import org.elasticsearch.client.Validatable;
+import org.elasticsearch.client.ml.job.config.Job;
+import org.elasticsearch.client.ml.job.util.PageParams;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ObjectParser;
+import org.elasticsearch.common.xcontent.ToXContentObject;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+
+import java.io.IOException;
+import java.util.Objects;
+
+/**
+ * A request to retrieve records of a given job
+ */
+public class GetRecordsRequest implements ToXContentObject, Validatable {
+
+    public static final ParseField EXCLUDE_INTERIM = new ParseField("exclude_interim");
+    public static final ParseField START = new ParseField("start");
+    public static final ParseField END = new ParseField("end");
+    public static final ParseField RECORD_SCORE = new ParseField("record_score");
+    public static final ParseField SORT = new ParseField("sort");
+    public static final ParseField DESCENDING = new ParseField("desc");
+
+    public static final ObjectParser<GetRecordsRequest, Void> PARSER = new ObjectParser<>("get_buckets_request", GetRecordsRequest::new);
+
+    static {
+        PARSER.declareString((request, jobId) -> request.jobId = jobId, Job.ID);
+        PARSER.declareBoolean(GetRecordsRequest::setExcludeInterim, EXCLUDE_INTERIM);
+        PARSER.declareStringOrNull(GetRecordsRequest::setStart, START);
+        PARSER.declareStringOrNull(GetRecordsRequest::setEnd, END);
+        PARSER.declareObject(GetRecordsRequest::setPageParams, PageParams.PARSER, PageParams.PAGE);
+        PARSER.declareDouble(GetRecordsRequest::setRecordScore, RECORD_SCORE);
+        PARSER.declareString(GetRecordsRequest::setSort, SORT);
+        PARSER.declareBoolean(GetRecordsRequest::setDescending, DESCENDING);
+    }
+
+    private String jobId;
+    private Boolean excludeInterim;
+    private String start;
+    private String end;
+    private PageParams pageParams;
+    private Double recordScore;
+    private String sort;
+    private Boolean descending;
+
+    private GetRecordsRequest() {}
+
+    /**
+     * Constructs a request to retrieve records of a given job
+     * @param jobId id of the job to retrieve records of
+     */
+    public GetRecordsRequest(String jobId) {
+        this.jobId = Objects.requireNonNull(jobId);
+    }
+
+    public String getJobId() {
+        return jobId;
+    }
+
+    public boolean isExcludeInterim() {
+        return excludeInterim;
+    }
+
+    /**
+     * Sets the value of "exclude_interim".
+     * When {@code true}, interim records will be filtered out.
+     * @param excludeInterim value of "exclude_interim" to be set
+     */
+    public void setExcludeInterim(boolean excludeInterim) {
+        this.excludeInterim = excludeInterim;
+    }
+
+    public String getStart() {
+        return start;
+    }
+
+    /**
+     * Sets the value of "start" which is a timestamp.
+     * Only records whose timestamp is on or after the "start" value will be returned.
+     * @param start value of "start" to be set
+     */
+    public void setStart(String start) {
+        this.start = start;
+    }
+
+    public String getEnd() {
+        return end;
+    }
+
+    /**
+     * Sets the value of "end" which is a timestamp.
+     * Only records whose timestamp is before the "end" value will be returned.
+     * @param end value of "end" to be set
+     */
+    public void setEnd(String end) {
+        this.end = end;
+    }
+
+    public PageParams getPageParams() {
+        return pageParams;
+    }
+
+    /**
+     * Sets the paging parameters
+     * @param pageParams The paging parameters
+     */
+    public void setPageParams(PageParams pageParams) {
+        this.pageParams = pageParams;
+    }
+
+    public Double getRecordScore() {
+        return recordScore;
+    }
+
+    /**
+     * Sets the value of "record_score".
+     * Only records with "record_score" equal or greater will be returned.
+     * @param recordScore value of "record_score".
+     */
+    public void setRecordScore(double recordScore) {
+        this.recordScore = recordScore;
+    }
+
+    public String getSort() {
+        return sort;
+    }
+
+    /**
+     * Sets the value of "sort".
+     * Specifies the bucket field to sort on.
+     * @param sort value of "sort".
+     */
+    public void setSort(String sort) {
+        this.sort = sort;
+    }
+
+    public boolean isDescending() {
+        return descending;
+    }
+
+    /**
+     * Sets the value of "desc".
+     * Specifies the sorting order.
+     * @param descending value of "desc"
+     */
+    public void setDescending(boolean descending) {
+        this.descending = descending;
+    }
+
+    @Override
+    public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
+        builder.startObject();
+        builder.field(Job.ID.getPreferredName(), jobId);
+        if (excludeInterim != null) {
+            builder.field(EXCLUDE_INTERIM.getPreferredName(), excludeInterim);
+        }
+        if (start != null) {
+            builder.field(START.getPreferredName(), start);
+        }
+        if (end != null) {
+            builder.field(END.getPreferredName(), end);
+        }
+        if (pageParams != null) {
+            builder.field(PageParams.PAGE.getPreferredName(), pageParams);
+        }
+        if (recordScore != null) {
+            builder.field(RECORD_SCORE.getPreferredName(), recordScore);
+        }
+        if (sort != null) {
+            builder.field(SORT.getPreferredName(), sort);
+        }
+        if (descending != null) {
+            builder.field(DESCENDING.getPreferredName(), descending);
+        }
+        builder.endObject();
+        return builder;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(jobId, excludeInterim, recordScore, pageParams, start, end, sort, descending);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        GetRecordsRequest other = (GetRecordsRequest) obj;
+        return Objects.equals(jobId, other.jobId) &&
+                Objects.equals(excludeInterim, other.excludeInterim) &&
+                Objects.equals(recordScore, other.recordScore) &&
+                Objects.equals(pageParams, other.pageParams) &&
+                Objects.equals(start, other.start) &&
+                Objects.equals(end, other.end) &&
+                Objects.equals(sort, other.sort) &&
+                Objects.equals(descending, other.descending);
+    }
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/ml/GetRecordsResponse.java

@@ -0,0 +1,78 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client.ml;
+
+import org.elasticsearch.client.ml.job.results.AnomalyRecord;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.XContentParser;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * A response containing the requested buckets
+ */
+public class GetRecordsResponse extends AbstractResultResponse<AnomalyRecord> {
+
+    public static final ParseField RECORDS = new ParseField("records");
+
+    @SuppressWarnings("unchecked")
+    public static final ConstructingObjectParser<GetRecordsResponse, Void> PARSER = new ConstructingObjectParser<>("get_records_response",
+            true, a -> new GetRecordsResponse((List<AnomalyRecord>) a[0], (long) a[1]));
+
+    static {
+        PARSER.declareObjectArray(ConstructingObjectParser.constructorArg(), AnomalyRecord.PARSER, RECORDS);
+        PARSER.declareLong(ConstructingObjectParser.constructorArg(), COUNT);
+    }
+
+    public static GetRecordsResponse fromXContent(XContentParser parser) throws IOException {
+        return PARSER.parse(parser, null);
+    }
+
+    GetRecordsResponse(List<AnomalyRecord> buckets, long count) {
+        super(RECORDS, buckets, count);
+    }
+
+    /**
+     * The retrieved records
+     * @return the retrieved records
+     */
+    public List<AnomalyRecord> records() {
+        return results;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(count, results);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        GetRecordsResponse other = (GetRecordsResponse) obj;
+        return count == other.count && Objects.equals(results, other.results);
+    }
+}

client/rest-high-level/src/test/java/org/elasticsearch/client/MachineLearningGetResultsIT.java

@@ -23,8 +23,11 @@ import org.elasticsearch.action.index.IndexRequest;
 import org.elasticsearch.action.support.WriteRequest;
 import org.elasticsearch.client.ml.GetBucketsRequest;
 import org.elasticsearch.client.ml.GetBucketsResponse;
+import org.elasticsearch.client.ml.GetRecordsRequest;
+import org.elasticsearch.client.ml.GetRecordsResponse;
 import org.elasticsearch.client.ml.PutJobRequest;
 import org.elasticsearch.client.ml.job.config.Job;
+import org.elasticsearch.client.ml.job.results.AnomalyRecord;
 import org.elasticsearch.client.ml.job.results.Bucket;
 import org.elasticsearch.client.ml.job.util.PageParams;
 import org.elasticsearch.common.xcontent.XContentType;
@@ -34,7 +37,10 @@ import org.junit.Before;
 import java.io.IOException;
 
 import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.greaterThan;
+import static org.hamcrest.Matchers.greaterThanOrEqualTo;
 import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.lessThan;
 import static org.hamcrest.Matchers.lessThanOrEqualTo;
 
 public class MachineLearningGetResultsIT extends ESRestHighLevelClientTestCase {
@@ -47,7 +53,8 @@ public class MachineLearningGetResultsIT extends ESRestHighLevelClientTestCase {
     // 2018-08-01T00:00:00Z
     private static final long START_TIME_EPOCH_MS = 1533081600000L;
 
-    private BucketStats bucketStats = new BucketStats();
+    private Stats bucketStats = new Stats();
+    private Stats recordStats = new Stats();
 
     @Before
     public void createJobAndIndexResults() throws IOException {
@@ -68,7 +75,7 @@ public class MachineLearningGetResultsIT extends ESRestHighLevelClientTestCase {
 
         // Also index an interim bucket
         addBucketIndexRequest(time, true, bulkRequest);
-        addRecordIndexRequests(time, true, bulkRequest);
+        addRecordIndexRequest(time, true, bulkRequest);
 
         highLevelClient().bulk(bulkRequest, RequestOptions.DEFAULT);
     }
@@ -91,16 +98,21 @@ public class MachineLearningGetResultsIT extends ESRestHighLevelClientTestCase {
         }
         int recordCount = randomIntBetween(1, 3);
         for (int i = 0; i < recordCount; ++i) {
-            IndexRequest indexRequest = new IndexRequest(RESULTS_INDEX, DOC);
+            addRecordIndexRequest(timestamp, isInterim, bulkRequest);
-            double recordScore = randomDoubleBetween(0.0, 100.0, true);
-            double p = randomDoubleBetween(0.0, 0.05, false);
-            indexRequest.source("{\"job_id\":\"" + JOB_ID + "\", \"result_type\":\"record\", \"timestamp\": " + timestamp + "," +
-                    "\"bucket_span\": 3600,\"is_interim\": " + isInterim + ", \"record_score\": " + recordScore + ", \"probability\": "
-                    + p + "}", XContentType.JSON);
-            bulkRequest.add(indexRequest);
         }
     }
 
+    private void addRecordIndexRequest(long timestamp, boolean isInterim, BulkRequest bulkRequest) {
+        IndexRequest indexRequest = new IndexRequest(RESULTS_INDEX, DOC);
+        double recordScore = randomDoubleBetween(0.0, 100.0, true);
+        recordStats.report(recordScore);
+        double p = randomDoubleBetween(0.0, 0.05, false);
+        indexRequest.source("{\"job_id\":\"" + JOB_ID + "\", \"result_type\":\"record\", \"timestamp\": " + timestamp + "," +
+                "\"bucket_span\": 3600,\"is_interim\": " + isInterim + ", \"record_score\": " + recordScore + ", \"probability\": "
+                + p + "}", XContentType.JSON);
+        bulkRequest.add(indexRequest);
+    }
+
     @After
     public void deleteJob() throws IOException {
         new MlRestTestStateCleaner(logger, client()).clearMlMetadata();
@@ -194,7 +206,73 @@ public class MachineLearningGetResultsIT extends ESRestHighLevelClientTestCase {
         }
     }
 
-    private static class BucketStats {
+    public void testGetRecords() throws IOException {
+        MachineLearningClient machineLearningClient = highLevelClient().machineLearning();
+
+        {
+            GetRecordsRequest request = new GetRecordsRequest(JOB_ID);
+
+            GetRecordsResponse response = execute(request, machineLearningClient::getRecords, machineLearningClient::getRecordsAsync);
+
+            assertThat(response.count(), greaterThan(0L));
+            assertThat(response.count(), equalTo(recordStats.totalCount()));
+        }
+        {
+            GetRecordsRequest request = new GetRecordsRequest(JOB_ID);
+            request.setRecordScore(50.0);
+
+            GetRecordsResponse response = execute(request, machineLearningClient::getRecords, machineLearningClient::getRecordsAsync);
+
+            long majorAndCriticalCount = recordStats.majorCount + recordStats.criticalCount;
+            assertThat(response.count(), equalTo(majorAndCriticalCount));
+            assertThat(response.records().size(), equalTo((int) Math.min(100, majorAndCriticalCount)));
+            assertThat(response.records().stream().anyMatch(r -> r.getRecordScore() < 50.0), is(false));
+        }
+        {
+            GetRecordsRequest request = new GetRecordsRequest(JOB_ID);
+            request.setExcludeInterim(true);
+
+            GetRecordsResponse response = execute(request, machineLearningClient::getRecords, machineLearningClient::getRecordsAsync);
+
+            assertThat(response.count(), equalTo(recordStats.totalCount() - 1));
+        }
+        {
+            long end = START_TIME_EPOCH_MS + 10 * 3600000;
+            GetRecordsRequest request = new GetRecordsRequest(JOB_ID);
+            request.setStart(String.valueOf(START_TIME_EPOCH_MS));
+            request.setEnd(String.valueOf(end));
+
+            GetRecordsResponse response = execute(request, machineLearningClient::getRecords, machineLearningClient::getRecordsAsync);
+
+            for (AnomalyRecord record : response.records()) {
+                assertThat(record.getTimestamp().getTime(), greaterThanOrEqualTo(START_TIME_EPOCH_MS));
+                assertThat(record.getTimestamp().getTime(), lessThan(end));
+            }
+        }
+        {
+            GetRecordsRequest request = new GetRecordsRequest(JOB_ID);
+            request.setPageParams(new PageParams(3, 3));
+
+            GetRecordsResponse response = execute(request, machineLearningClient::getRecords, machineLearningClient::getRecordsAsync);
+
+            assertThat(response.records().size(), equalTo(3));
+        }
+        {
+            GetRecordsRequest request = new GetRecordsRequest(JOB_ID);
+            request.setSort("probability");
+            request.setDescending(true);
+
+            GetRecordsResponse response = execute(request, machineLearningClient::getRecords, machineLearningClient::getRecordsAsync);
+
+            double previousProb = 1.0;
+            for (AnomalyRecord record : response.records()) {
+                assertThat(record.getProbability(), lessThanOrEqualTo(previousProb));
+                previousProb = record.getProbability();
+            }
+        }
+    }
+
+    private static class Stats {
         // score < 50.0
         private long minorCount;
 
@@ -204,14 +282,18 @@ public class MachineLearningGetResultsIT extends ESRestHighLevelClientTestCase {
         // score > 75.0
         private long criticalCount;
 
-        private void report(double anomalyScore) {
+        private void report(double score) {
-            if (anomalyScore < 50.0) {
+            if (score < 50.0) {
                 minorCount++;
-            } else if (anomalyScore < 75.0) {
+            } else if (score < 75.0) {
                 majorCount++;
             } else {
                 criticalCount++;
             }
         }
+
+        private long totalCount() {
+            return minorCount + majorCount + criticalCount;
+        }
     }
 }

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

@@ -35,6 +35,8 @@ import org.elasticsearch.client.ml.GetBucketsRequest;
 import org.elasticsearch.client.ml.GetBucketsResponse;
 import org.elasticsearch.client.ml.GetJobRequest;
 import org.elasticsearch.client.ml.GetJobResponse;
+import org.elasticsearch.client.ml.GetRecordsRequest;
+import org.elasticsearch.client.ml.GetRecordsResponse;
 import org.elasticsearch.client.ml.OpenJobRequest;
 import org.elasticsearch.client.ml.OpenJobResponse;
 import org.elasticsearch.client.ml.PutJobRequest;
@@ -43,6 +45,7 @@ import org.elasticsearch.client.ml.job.config.AnalysisConfig;
 import org.elasticsearch.client.ml.job.config.DataDescription;
 import org.elasticsearch.client.ml.job.config.Detector;
 import org.elasticsearch.client.ml.job.config.Job;
+import org.elasticsearch.client.ml.job.results.AnomalyRecord;
 import org.elasticsearch.client.ml.job.results.Bucket;
 import org.elasticsearch.client.ml.job.util.PageParams;
 import org.elasticsearch.common.unit.TimeValue;
@@ -454,4 +457,94 @@ public class MlClientDocumentationIT extends ESRestHighLevelClientTestCase {
             assertTrue(latch.await(30L, TimeUnit.SECONDS));
         }
     }
+
+    public void testGetRecords() throws IOException, InterruptedException {
+        RestHighLevelClient client = highLevelClient();
+
+        String jobId = "test-get-records";
+        Job job = MachineLearningIT.buildJob(jobId);
+        client.machineLearning().putJob(new PutJobRequest(job), RequestOptions.DEFAULT);
+
+        // Let us index a record
+        IndexRequest indexRequest = new IndexRequest(".ml-anomalies-shared", "doc");
+        indexRequest.setRefreshPolicy(WriteRequest.RefreshPolicy.IMMEDIATE);
+        indexRequest.source("{\"job_id\":\"test-get-records\", \"result_type\":\"record\", \"timestamp\": 1533081600000," +
+                "\"bucket_span\": 600,\"is_interim\": false, \"record_score\": 80.0}", XContentType.JSON);
+        client.index(indexRequest, RequestOptions.DEFAULT);
+
+        {
+            // tag::x-pack-ml-get-records-request
+            GetRecordsRequest request = new GetRecordsRequest(jobId); // <1>
+            // end::x-pack-ml-get-records-request
+
+            // tag::x-pack-ml-get-records-desc
+            request.setDescending(true); // <1>
+            // end::x-pack-ml-get-records-desc
+
+            // tag::x-pack-ml-get-records-end
+            request.setEnd("2018-08-21T00:00:00Z"); // <1>
+            // end::x-pack-ml-get-records-end
+
+            // tag::x-pack-ml-get-records-exclude-interim
+            request.setExcludeInterim(true); // <1>
+            // end::x-pack-ml-get-records-exclude-interim
+
+            // tag::x-pack-ml-get-records-page
+            request.setPageParams(new PageParams(100, 200)); // <1>
+            // end::x-pack-ml-get-records-page
+
+            // Set page params back to null so the response contains the record we indexed
+            request.setPageParams(null);
+
+            // tag::x-pack-ml-get-records-record-score
+            request.setRecordScore(75.0); // <1>
+            // end::x-pack-ml-get-records-record-score
+
+            // tag::x-pack-ml-get-records-sort
+            request.setSort("probability"); // <1>
+            // end::x-pack-ml-get-records-sort
+
+            // tag::x-pack-ml-get-records-start
+            request.setStart("2018-08-01T00:00:00Z"); // <1>
+            // end::x-pack-ml-get-records-start
+
+            // tag::x-pack-ml-get-records-execute
+            GetRecordsResponse response = client.machineLearning().getRecords(request, RequestOptions.DEFAULT);
+            // end::x-pack-ml-get-records-execute
+
+            // tag::x-pack-ml-get-records-response
+            long count = response.count(); // <1>
+            List<AnomalyRecord> records = response.records(); // <2>
+            // end::x-pack-ml-get-records-response
+            assertEquals(1, records.size());
+        }
+        {
+            GetRecordsRequest request = new GetRecordsRequest(jobId);
+
+            // tag::x-pack-ml-get-records-listener
+            ActionListener<GetRecordsResponse> listener =
+                    new ActionListener<GetRecordsResponse>() {
+                        @Override
+                        public void onResponse(GetRecordsResponse getRecordsResponse) {
+                            // <1>
+                        }
+
+                        @Override
+                        public void onFailure(Exception e) {
+                            // <2>
+                        }
+                    };
+            // end::x-pack-ml-get-records-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::x-pack-ml-get-records-execute-async
+            client.machineLearning().getRecordsAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            // end::x-pack-ml-get-records-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+    }
 }

client/rest-high-level/src/test/java/org/elasticsearch/client/ml/GetRecordsRequestTests.java

@@ -0,0 +1,72 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client.ml;
+
+import org.elasticsearch.client.ml.job.util.PageParams;
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.test.AbstractXContentTestCase;
+import org.elasticsearch.test.ESTestCase;
+
+import java.io.IOException;
+
+public class GetRecordsRequestTests extends AbstractXContentTestCase<GetRecordsRequest> {
+
+    @Override
+    protected GetRecordsRequest createTestInstance() {
+        GetRecordsRequest request = new GetRecordsRequest(ESTestCase.randomAlphaOfLengthBetween(1, 20));
+
+        if (ESTestCase.randomBoolean()) {
+            request.setStart(String.valueOf(ESTestCase.randomLong()));
+        }
+        if (ESTestCase.randomBoolean()) {
+            request.setEnd(String.valueOf(ESTestCase.randomLong()));
+        }
+        if (ESTestCase.randomBoolean()) {
+            request.setExcludeInterim(ESTestCase.randomBoolean());
+        }
+        if (ESTestCase.randomBoolean()) {
+            request.setRecordScore(ESTestCase.randomDouble());
+        }
+        if (ESTestCase.randomBoolean()) {
+            int from = ESTestCase.randomInt(10000);
+            int size = ESTestCase.randomInt(10000);
+            request.setPageParams(new PageParams(from, size));
+        }
+        if (ESTestCase.randomBoolean()) {
+            request.setSort("anomaly_score");
+        }
+        if (ESTestCase.randomBoolean()) {
+            request.setDescending(ESTestCase.randomBoolean());
+        }
+        if (ESTestCase.randomBoolean()) {
+            request.setExcludeInterim(ESTestCase.randomBoolean());
+        }
+        return request;
+    }
+
+    @Override
+    protected GetRecordsRequest doParseInstance(XContentParser parser) throws IOException {
+        return GetRecordsRequest.PARSER.apply(parser, null);
+    }
+
+    @Override
+    protected boolean supportsUnknownFields() {
+        return false;
+    }
+}

client/rest-high-level/src/test/java/org/elasticsearch/client/ml/GetRecordsResponseTests.java

@@ -0,0 +1,54 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.client.ml;
+
+import org.elasticsearch.client.ml.job.results.AnomalyRecord;
+import org.elasticsearch.client.ml.job.results.AnomalyRecordTests;
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.test.AbstractXContentTestCase;
+import org.elasticsearch.test.ESTestCase;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+public class GetRecordsResponseTests extends AbstractXContentTestCase<GetRecordsResponse> {
+
+    @Override
+    protected GetRecordsResponse createTestInstance() {
+        String jobId = ESTestCase.randomAlphaOfLength(20);
+        int listSize = ESTestCase.randomInt(10);
+        List<AnomalyRecord> records = new ArrayList<>(listSize);
+        for (int j = 0; j < listSize; j++) {
+            AnomalyRecord record = AnomalyRecordTests.createTestInstance(jobId);
+            records.add(record);
+        }
+        return new GetRecordsResponse(records, listSize);
+    }
+
+    @Override
+    protected GetRecordsResponse doParseInstance(XContentParser parser) throws IOException {
+        return GetRecordsResponse.fromXContent(parser);
+    }
+
+    @Override
+    protected boolean supportsUnknownFields() {
+        return true;
+    }
+}

client/rest-high-level/src/test/java/org/elasticsearch/client/ml/job/results/AnomalyRecordTests.java

@@ -33,7 +33,7 @@ public class AnomalyRecordTests extends AbstractXContentTestCase<AnomalyRecord>
         return createTestInstance("foo");
     }
 
-    public AnomalyRecord createTestInstance(String jobId) {
+    public static AnomalyRecord createTestInstance(String jobId) {
         AnomalyRecord anomalyRecord = new AnomalyRecord(jobId, new Date(randomNonNegativeLong()), randomNonNegativeLong());
         anomalyRecord.setActual(Collections.singletonList(randomDouble()));
         anomalyRecord.setTypical(Collections.singletonList(randomDouble()));

client/rest-high-level/src/test/java/org/elasticsearch/client/ml/job/results/BucketTests.java

@@ -70,7 +70,7 @@ public class BucketTests extends AbstractXContentTestCase<Bucket> {
             int size = randomInt(10);
             List<AnomalyRecord> records = new ArrayList<>(size);
             for (int i = 0; i < size; i++) {
-                AnomalyRecord anomalyRecord = new AnomalyRecordTests().createTestInstance(jobId);
+                AnomalyRecord anomalyRecord = AnomalyRecordTests.createTestInstance(jobId);
                 records.add(anomalyRecord);
             }
             bucket.setRecords(records);

docs/java-rest/high-level/ml/get-records.asciidoc

@@ -0,0 +1,113 @@
+[[java-rest-high-x-pack-ml-get-records]]
+=== Get Records API
+
+The Get Records API retrieves one or more record results.
+It accepts a `GetRecordsRequest` object and responds
+with a `GetRecordsResponse` object.
+
+[[java-rest-high-x-pack-ml-get-records-request]]
+==== Get Records Request
+
+A `GetRecordsRequest` object gets created with an existing non-null `jobId`.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-request]
+--------------------------------------------------
+<1> Constructing a new request referencing an existing `jobId`
+
+==== Optional Arguments
+The following arguments are optional:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-desc]
+--------------------------------------------------
+<1> If `true`, the records are sorted in descending order. Defaults to `false`.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-end]
+--------------------------------------------------
+<1> Records with timestamps earlier than this time will be returned.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-exclude-interim]
+--------------------------------------------------
+<1> If `true`, interim results will be excluded. Defaults to `false`.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-page]
+--------------------------------------------------
+<1> The page parameters `from` and `size`. `from` specifies the number of records to skip.
+`size` specifies the maximum number of records to get. Defaults to `0` and `100` respectively.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-record-score]
+--------------------------------------------------
+<1> Records with record_score greater or equal than this value will be returned.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-sort]
+--------------------------------------------------
+<1> The field to sort records on. Defaults to `influencer_score`.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-end]
+--------------------------------------------------
+<1> Records with timestamps on or after this time will be returned.
+
+[[java-rest-high-x-pack-ml-get-records-execution]]
+==== Execution
+
+The request can be executed through the `MachineLearningClient` contained
+in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-execute]
+--------------------------------------------------
+
+
+[[java-rest-high-x-pack-ml-get-records-execution-async]]
+==== Asynchronous Execution
+
+The request can also be executed asynchronously:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-execute-async]
+--------------------------------------------------
+<1> The `GetRecordsRequest` to execute and the `ActionListener` to use when
+the execution completes
+
+The asynchronous method does not block and returns immediately. Once it is
+completed the `ActionListener` is called back with the `onResponse` method
+if the execution is successful or the `onFailure` method if the execution
+failed.
+
+A typical listener for `GetRecordsResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-listener]
+--------------------------------------------------
+<1> `onResponse` is called back when the action is completed successfully
+<2> `onFailure` is called back when some unexpected error occurs
+
+[[java-rest-high-snapshot-ml-get-records-response]]
+==== Get Records Response
+
+The returned `GetRecordsResponse` contains the requested records:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-get-records-response]
+--------------------------------------------------
+<1> The count of records that were matched
+<2> The records retrieved

docs/java-rest/high-level/supported-apis.asciidoc

@@ -212,6 +212,7 @@ The Java High Level REST Client supports the following Machine Learning APIs:
 * <<java-rest-high-x-pack-ml-open-job>>
 * <<java-rest-high-x-pack-ml-close-job>>
 * <<java-rest-high-x-pack-ml-get-buckets>>
+* <<java-rest-high-x-pack-ml-get-records>>
 
 include::ml/put-job.asciidoc[]
 include::ml/get-job.asciidoc[]
@@ -219,6 +220,7 @@ include::ml/delete-job.asciidoc[]
 include::ml/open-job.asciidoc[]
 include::ml/close-job.asciidoc[]
 include::ml/get-buckets.asciidoc[]
+include::ml/get-records.asciidoc[]
 
 == Migration APIs