From a9535c0b5af52b6ef33d3dabc4ade1ba9c539929 Mon Sep 17 00:00:00 2001
From: Dimitris Athanasiou <dimitris@elastic.co>
Date: Fri, 8 Dec 2017 16:03:51 +0000
Subject: [PATCH] [ML][DOCS] Correct get-overall-buckets API example
 (elastic/x-pack-elasticsearch#3269)

Also fixes the score filters explanation for the results APIs.

Original commit: elastic/x-pack-elasticsearch@18cb31ab56e15ad7af69d6a82213dde73e053cae
---
 docs/en/rest-api/ml/get-bucket.asciidoc       |  2 +-
 docs/en/rest-api/ml/get-influencer.asciidoc   |  2 +-
 .../rest-api/ml/get-overall-buckets.asciidoc  | 54 +++++++++++++++++--
 docs/en/rest-api/ml/get-record.asciidoc       |  2 +-
 4 files changed, 53 insertions(+), 7 deletions(-)

diff --git a/docs/en/rest-api/ml/get-bucket.asciidoc b/docs/en/rest-api/ml/get-bucket.asciidoc
index 34f5bad2c4b..4c7f3eb7f6e 100644
--- a/docs/en/rest-api/ml/get-bucket.asciidoc
+++ b/docs/en/rest-api/ml/get-bucket.asciidoc
@@ -31,7 +31,7 @@ This API presents a chronological view of the records, grouped by bucket.
 ==== Request Body
 
 `anomaly_score`::
-  (double) Returns buckets with anomaly scores higher than this value.
+  (double) Returns buckets with anomaly scores greater or equal than this value.
 
 `desc`::
   (boolean) If true, the buckets are sorted in descending order.
diff --git a/docs/en/rest-api/ml/get-influencer.asciidoc b/docs/en/rest-api/ml/get-influencer.asciidoc
index f7a5d87adc2..d8fe87d11ed 100644
--- a/docs/en/rest-api/ml/get-influencer.asciidoc
+++ b/docs/en/rest-api/ml/get-influencer.asciidoc
@@ -30,7 +30,7 @@ influencers.
   By default, interim results are included.
 
 `influencer_score`::
-  (double) Returns influencers with anomaly scores higher than this value.
+  (double) Returns influencers with anomaly scores greater or equal than this value.
 
 `page`::
 `from`:::
diff --git a/docs/en/rest-api/ml/get-overall-buckets.asciidoc b/docs/en/rest-api/ml/get-overall-buckets.asciidoc
index 5ced48c12bd..e2ced2989f3 100644
--- a/docs/en/rest-api/ml/get-overall-buckets.asciidoc
+++ b/docs/en/rest-api/ml/get-overall-buckets.asciidoc
@@ -63,7 +63,7 @@ overall buckets with a span equal to the largest job's `bucket_span`.
   By default, interim results are included.
 
 `overall_score`::
-  (double) Returns overall buckets with overall scores higher than this value.
+  (double) Returns overall buckets with overall scores greater or equal than this value.
 
 `start`::
   (string) Returns overall buckets with timestamps after this time.
@@ -101,7 +101,7 @@ The following example gets overall buckets for jobs with IDs matching `job-*`:
 --------------------------------------------------
 GET _xpack/ml/anomaly_detectors/job-*/results/overall_buckets
 {
-  "overall_score": 90,
+  "overall_score": 80,
   "start": "1403532000000"
 }
 --------------------------------------------------
@@ -109,7 +109,8 @@ GET _xpack/ml/anomaly_detectors/job-*/results/overall_buckets
 // TEST[skip:todo]
 
 In this example, the API returns a single result that matches the specified
-score and time constraints:
+score and time constraints. The `overall_score` is the max job score as
+`top_n` defaults to 1 when not specified:
 [source,js]
 ----
 {
@@ -118,7 +119,52 @@ score and time constraints:
     {
       "timestamp" : 1403532000000,
       "bucket_span" : 3600,
-      "overall_score" : 40.0,
+      "overall_score" : 80.0,
+      "jobs" : [
+        {
+          "job_id" : "job-1",
+          "max_anomaly_score" : 30.0
+        },
+        {
+          "job_id" : "job-2",
+          "max_anomaly_score" : 10.0
+        },
+        {
+          "job_id" : "job-3",
+          "max_anomaly_score" : 80.0
+        }
+      ],
+      "is_interim" : false,
+      "result_type" : "overall_bucket"
+    }
+  ]
+}
+----
+
+The next example is similar but this time `top_n` is set to `2`:
+
+[source,js]
+--------------------------------------------------
+GET _xpack/ml/anomaly_detectors/job-*/results/overall_buckets
+{
+  "top_n": 2,
+  "overall_score": 50.0,
+  "start": "1403532000000"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:todo]
+
+Note how the `overall_score` is now the average of the top 2 job scores:
+[source,js]
+----
+{
+  "count": 1,
+  "overall_buckets": [
+    {
+      "timestamp" : 1403532000000,
+      "bucket_span" : 3600,
+      "overall_score" : 55.0,
       "jobs" : [
         {
           "job_id" : "job-1",
diff --git a/docs/en/rest-api/ml/get-record.asciidoc b/docs/en/rest-api/ml/get-record.asciidoc
index 24c4aeca797..f35fea7d68b 100644
--- a/docs/en/rest-api/ml/get-record.asciidoc
+++ b/docs/en/rest-api/ml/get-record.asciidoc
@@ -36,7 +36,7 @@ The get records API enables you to retrieve anomaly records for a job.
   (integer) Specifies the maximum number of records to obtain.
 
 `record_score`::
-  (double) Returns records with anomaly scores higher than this value.
+  (double) Returns records with anomaly scores greater or equal than this value.
 
 `sort`::
   (string) Specifies the sort field for the requested records.