From 5786e746cd31da1e8ec6545c420dbfde0c025bda Mon Sep 17 00:00:00 2001
From: Christos Soulios <1561376+csoulios@users.noreply.github.com>
Date: Tue, 15 Dec 2020 19:27:10 +0200
Subject: [PATCH 1/4] [DOCS] Added docs for aggregate_metric_double field
 (#66306)

Added documentation for the aggregate_metric_double field that was merged in #56745

Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
---
 docs/reference/mapping/types.asciidoc         |   5 +-
 .../types/aggregate-metric-double.asciidoc    | 227 ++++++++++++++++++
 2 files changed, 231 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/mapping/types/aggregate-metric-double.asciidoc

diff --git a/docs/reference/mapping/types.asciidoc b/docs/reference/mapping/types.asciidoc
index 69e1320418eb9..be148a4389237 100644
--- a/docs/reference/mapping/types.asciidoc
+++ b/docs/reference/mapping/types.asciidoc
@@ -61,7 +61,8 @@ values.
 [[aggregated-data-types]]
 ==== Aggregate data types
 
-<<histogram,`histogram`>>:: Pre-aggregated numerical values.
+<<aggregate-metric-double,`aggregate_metric_double`>>:: Pre-aggregated metric values.
+<<histogram,`histogram`>>:: Pre-aggregated numerical values in the form of a histogram.
 
 
 [discrete]
@@ -127,6 +128,8 @@ the <<analysis-standard-analyzer,`standard` analyzer>>, the
 This is the purpose of _multi-fields_. Most field types support multi-fields
 via the <<multi-fields>> parameter.
 
+include::types/aggregate-metric-double.asciidoc[]
+
 include::types/alias.asciidoc[]
 
 include::types/array.asciidoc[]
diff --git a/docs/reference/mapping/types/aggregate-metric-double.asciidoc b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
new file mode 100644
index 0000000000000..5e2d2b6cc826a
--- /dev/null
+++ b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
@@ -0,0 +1,227 @@
+[role="xpack"]
+[testenv="basic"]
+[[aggregate-metric-double]]
+=== Aggregate metric field type
+++++
+<titleabbrev>Aggregate metric</titleabbrev>
+++++
+
+Stores pre-aggregated numeric values for <<search-aggregations-metrics,metric
+aggregations>>. An `aggregate_metric_double` field is an object containing one
+or more of the following metric sub-fields: `min`, `max`, `sum`, and
+`value_count`.
+
+When you run certain metric aggregations on an `aggregate_metric_double` field,
+the aggregation uses the related sub-field's values. For example, a
+<<search-aggregations-metrics-min-aggregation, `min`>> aggregation on an
+`aggregate_metric_double` field returns the minimum value of all `min`
+sub-fields.
+
+
+IMPORTANT: An `aggregate_metric_double` field stores a single numeric
+<<doc-values,doc value>> for each metric sub-field. Array values are not
+supported.  `min`, `max`, and `sum` values are `double` numbers. `value_count`
+is a positive `long` number.
+
+[source,console]
+----
+PUT my-index
+  "mappings": {
+    "properties": {
+      "my-agg-metric-field": {
+        "type": "aggregate_metric_double",
+        "metrics": [ "min", "max", "sum", "value_count"],
+        "default_metric": "max"
+      }
+    }
+  }
+}
+----
+
+[[aggregate-metric-double-params]]
+==== Parameters for `aggregate_metric_double` fields
+
+`metrics`::
+(Required, array of strings)
+Array of metric sub-fields to store. Each value corresponds to a
+<<search-aggregations-metrics,metric aggregation>>. Valid values are
+<<search-aggregations-metrics-min-aggregation,`min`>>,
+<<search-aggregations-metrics-max-aggregation,`max`>>,
+<<search-aggregations-metrics-sum-aggregation,`sum`>>, and
+<<search-aggregations-metrics-valuecount-aggregation,`value_count`>>. You must
+specify at least one value.
+
+`default_metric`::
+(Required, string)
+Default metric sub-field to use for queries, scripts, and aggregations that
+don't use a sub-field. Must be a value from the `metrics` array.
+
+
+[[aggregate-metric-double-uses]]
+==== Uses
+
+We designed `aggregate_metric_double` fields for use with the following aggregations:
+
+* A <<search-aggregations-metrics-min-aggregation,`min`>> aggregation returns the
+minimum value of all `min` sub-fields.
+
+* A <<search-aggregations-metrics-max-aggregation,`max`>> aggregation returns the
+maximum value of all `max` sub-fields.
+
+* A <<search-aggregations-metrics-sum-aggregation,`sum`>> aggregation returns the
+sum of the values of all `sum` sub-fields.
+
+*A  <<search-aggregations-metrics-valuecount-aggregation,`value_count`>>
+aggregation returns the sum of the values of all `value_count` sub-fields.
+
+* A <<search-aggregations-metrics-avg-aggregation,`avg`>> aggregation. There is no
+`avg` sub-field; the result of the `avg` aggregation is computed using the `sum`
+and `value_count` metrics. To run an `avg` aggregation, the field must contain
+both `sum` and `value_count` metric sub-field.
+
+
+If you use an `aggregate_metric_double` field with other aggregations, the field
+uses the `default_metric` value, which behaves as a `double` field. The
+`default_metric` is also used in scripts and the following queries:
+
+* <<query-dsl-exists-query,`exists`>>
+* <<query-dsl-range-query,`range`>>
+* <<query-dsl-term-query,`term`>>
+* <<query-dsl-terms-query,`terms`>>
+
+[[aggregate-metric-double-example]]
+==== Examples
+
+The following <<indices-create-index, create index>> API request creates an
+index with an `aggregate_metric_double` field named `agg_metric`. The request
+sets `max` as the field's `default_metric`.
+
+[source,console]
+--------------------------------------------------
+PUT stats-index
+{
+  "mappings": {
+    "properties": {
+      "agg_metric": {
+        "type": "aggregate_metric_double",
+        "metrics": [ "min", "max", "sum", "value_count"],
+        "default_metric": "max"
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+The following <<docs-index_,index>> API request adds documents with
+pre-aggregated data in the `agg_metric` field.
+
+[source,console]
+--------------------------------------------------
+PUT stats-index/_doc/1
+{
+    "agg_metric": {
+        "min": -302.50,
+        "max": 702.30,
+        "sum": 200.0,
+        "value_count": 25
+    }
+}
+
+PUT stats-index/_doc/2
+{
+    "agg_metric": {
+        "min": -93.00,
+        "max": 1702.30,
+        "sum": 300.00,
+        "value_count": 25
+    }
+}
+--------------------------------------------------
+
+You can run `min`, `max`, `sum`, `value_count`, and `avg` aggregations on a
+`agg_metric` field.
+
+[source,console]
+--------------------------------------------------
+POST stats-index/_search?size=0
+{
+    "aggs" : {
+        "metric_min" : { "min" : { "field" : "agg_metric" } },
+        "metric_max" : { "max" : { "field" : "agg_metric" } },
+        "metric_value_count" : { "value_count" : { "field" : "agg_metric" } },
+        "metric_sum" : { "sum" : { "field" : "agg_metric" } },
+        "metric_avg" : { "avg" : { "field" : "agg_metric" } }
+    }
+}
+--------------------------------------------------
+
+The aggregation results are based on related metric sub-field values.
+
+[source,console-result]
+--------------------------------------------------
+{
+...
+  "aggregations" : {
+    "metric_min" : {
+      "value" : -302.5
+    },
+    "metric_max" : {
+      "value" : 1702.3
+    },
+    "metric_value_count" : {
+      "value" : 50
+    },
+    "metric_sum" : {
+      "value" : 500.0
+    },
+    "metric_avg" : {
+      "value" : 10.0
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
+
+
+Queries on a `aggregate_metric_double` field use the `default_metric` value.
+
+[source,console]
+--------------------------------------------------
+GET stats-index/_search
+{
+  "query": {
+    "term": {
+      "agg_metric": {
+        "value": 702.30
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+The search returns the following hit. The value of the `default_metric` field,
+`max`, matches the query value.
+
+[source,console-result]
+--------------------------------------------------
+{
+...
+    "hits" : [
+      {
+        "_index" : "stats-index",
+        "_id" : "1",
+        "_score" : 1.0,
+        "_source" : {
+          "agg_metric" : {
+            "min" : -302.5,
+            "max" : 702.3,
+            "sum" : 200.0,
+            "value_count" : 25
+          }
+        }
+      }
+    ]
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

From da50ea6a9cfbff4d003fa2ebf9da36cf6621758f Mon Sep 17 00:00:00 2001
From: Christos Soulios <csoulios@gmail.com>
Date: Tue, 15 Dec 2020 19:47:43 +0200
Subject: [PATCH 2/4] Fix DOC build error

---
 docs/reference/mapping/types/aggregate-metric-double.asciidoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/reference/mapping/types/aggregate-metric-double.asciidoc b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
index 5e2d2b6cc826a..11be9b9f7fcd3 100644
--- a/docs/reference/mapping/types/aggregate-metric-double.asciidoc
+++ b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
@@ -26,6 +26,7 @@ is a positive `long` number.
 [source,console]
 ----
 PUT my-index
+{
   "mappings": {
     "properties": {
       "my-agg-metric-field": {

From c11e27e8ffc9aa64c25400c2d9ad63d12987e744 Mon Sep 17 00:00:00 2001
From: Christos Soulios <csoulios@gmail.com>
Date: Tue, 15 Dec 2020 20:54:42 +0200
Subject: [PATCH 3/4] Fix DOC build error

---
 .../mapping/types/aggregate-metric-double.asciidoc          | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/reference/mapping/types/aggregate-metric-double.asciidoc b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
index 11be9b9f7fcd3..f23246f9663ad 100644
--- a/docs/reference/mapping/types/aggregate-metric-double.asciidoc
+++ b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
@@ -112,6 +112,7 @@ PUT stats-index
   }
 }
 --------------------------------------------------
+// TEST
 
 The following <<docs-index_,index>> API request adds documents with
 pre-aggregated data in the `agg_metric` field.
@@ -138,6 +139,7 @@ PUT stats-index/_doc/2
     }
 }
 --------------------------------------------------
+// TEST[continued]
 
 You can run `min`, `max`, `sum`, `value_count`, and `avg` aggregations on a
 `agg_metric` field.
@@ -155,6 +157,7 @@ POST stats-index/_search?size=0
     }
 }
 --------------------------------------------------
+// TEST[continued]
 
 The aggregation results are based on related metric sub-field values.
 
@@ -199,6 +202,7 @@ GET stats-index/_search
   }
 }
 --------------------------------------------------
+// TEST[continued]
 
 The search returns the following hit. The value of the `default_metric` field,
 `max`, matches the query value.
@@ -225,4 +229,4 @@ The search returns the following hit. The value of the `default_metric` field,
   }
 }
 --------------------------------------------------
-// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,/]

From 1564d7febb0bae17b408d2ddd12977b5e5ae3127 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 15 Dec 2020 13:57:42 -0500
Subject: [PATCH 4/4] [DOCS] Fix docs integ tests for agg metric field docs
 (#66397)

---
 .../types/aggregate-metric-double.asciidoc    | 122 +++++++++---------
 1 file changed, 63 insertions(+), 59 deletions(-)

diff --git a/docs/reference/mapping/types/aggregate-metric-double.asciidoc b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
index f23246f9663ad..e9e82d10a211e 100644
--- a/docs/reference/mapping/types/aggregate-metric-double.asciidoc
+++ b/docs/reference/mapping/types/aggregate-metric-double.asciidoc
@@ -31,7 +31,7 @@ PUT my-index
     "properties": {
       "my-agg-metric-field": {
         "type": "aggregate_metric_double",
-        "metrics": [ "min", "max", "sum", "value_count"],
+        "metrics": [ "min", "max", "sum", "value_count" ],
         "default_metric": "max"
       }
     }
@@ -57,7 +57,6 @@ specify at least one value.
 Default metric sub-field to use for queries, scripts, and aggregations that
 don't use a sub-field. Must be a value from the `metrics` array.
 
-
 [[aggregate-metric-double-uses]]
 ==== Uses
 
@@ -80,7 +79,6 @@ aggregation returns the sum of the values of all `value_count` sub-fields.
 and `value_count` metrics. To run an `avg` aggregation, the field must contain
 both `sum` and `value_count` metric sub-field.
 
-
 If you use an `aggregate_metric_double` field with other aggregations, the field
 uses the `default_metric` value, which behaves as a `double` field. The
 `default_metric` is also used in scripts and the following queries:
@@ -98,99 +96,98 @@ index with an `aggregate_metric_double` field named `agg_metric`. The request
 sets `max` as the field's `default_metric`.
 
 [source,console]
---------------------------------------------------
+----
 PUT stats-index
 {
   "mappings": {
     "properties": {
       "agg_metric": {
         "type": "aggregate_metric_double",
-        "metrics": [ "min", "max", "sum", "value_count"],
+        "metrics": [ "min", "max", "sum", "value_count" ],
         "default_metric": "max"
       }
     }
   }
 }
---------------------------------------------------
-// TEST
+----
 
 The following <<docs-index_,index>> API request adds documents with
 pre-aggregated data in the `agg_metric` field.
 
 [source,console]
---------------------------------------------------
+----
 PUT stats-index/_doc/1
 {
-    "agg_metric": {
-        "min": -302.50,
-        "max": 702.30,
-        "sum": 200.0,
-        "value_count": 25
-    }
+  "agg_metric": {
+    "min": -302.50,
+    "max": 702.30,
+    "sum": 200.0,
+    "value_count": 25
+  }
 }
 
 PUT stats-index/_doc/2
 {
-    "agg_metric": {
-        "min": -93.00,
-        "max": 1702.30,
-        "sum": 300.00,
-        "value_count": 25
-    }
+  "agg_metric": {
+    "min": -93.00,
+    "max": 1702.30,
+    "sum": 300.00,
+    "value_count": 25
+  }
 }
---------------------------------------------------
+----
 // TEST[continued]
+// TEST[s/_doc\/2/_doc\/2?refresh=wait_for/]
 
 You can run `min`, `max`, `sum`, `value_count`, and `avg` aggregations on a
 `agg_metric` field.
 
 [source,console]
---------------------------------------------------
+----
 POST stats-index/_search?size=0
 {
-    "aggs" : {
-        "metric_min" : { "min" : { "field" : "agg_metric" } },
-        "metric_max" : { "max" : { "field" : "agg_metric" } },
-        "metric_value_count" : { "value_count" : { "field" : "agg_metric" } },
-        "metric_sum" : { "sum" : { "field" : "agg_metric" } },
-        "metric_avg" : { "avg" : { "field" : "agg_metric" } }
-    }
+  "aggs": {
+    "metric_min": { "min": { "field": "agg_metric" } },
+    "metric_max": { "max": { "field": "agg_metric" } },
+    "metric_value_count": { "value_count": { "field": "agg_metric" } },
+    "metric_sum": { "sum": { "field": "agg_metric" } },
+    "metric_avg": { "avg": { "field": "agg_metric" } }
+  }
 }
---------------------------------------------------
+----
 // TEST[continued]
 
 The aggregation results are based on related metric sub-field values.
 
 [source,console-result]
---------------------------------------------------
+----
 {
 ...
-  "aggregations" : {
-    "metric_min" : {
-      "value" : -302.5
+  "aggregations": {
+    "metric_min": {
+      "value": -302.5
     },
-    "metric_max" : {
-      "value" : 1702.3
+    "metric_max": {
+      "value": 1702.3
     },
-    "metric_value_count" : {
-      "value" : 50
+    "metric_value_count": {
+      "value": 50
     },
-    "metric_sum" : {
-      "value" : 500.0
+    "metric_sum": {
+      "value": 500.0
     },
-    "metric_avg" : {
-      "value" : 10.0
+    "metric_avg": {
+      "value": 10.0
     }
   }
 }
---------------------------------------------------
+----
 // TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
 
-
 Queries on a `aggregate_metric_double` field use the `default_metric` value.
 
 [source,console]
---------------------------------------------------
+----
 GET stats-index/_search
 {
   "query": {
@@ -201,32 +198,39 @@ GET stats-index/_search
     }
   }
 }
---------------------------------------------------
+----
 // TEST[continued]
 
 The search returns the following hit. The value of the `default_metric` field,
 `max`, matches the query value.
 
 [source,console-result]
---------------------------------------------------
+----
 {
-...
-    "hits" : [
+  ...
+    "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": 1.0,
+    "hits": [
       {
-        "_index" : "stats-index",
-        "_id" : "1",
-        "_score" : 1.0,
-        "_source" : {
-          "agg_metric" : {
-            "min" : -302.5,
-            "max" : 702.3,
-            "sum" : 200.0,
-            "value_count" : 25
+        "_index": "stats-index",
+        "_type": "_doc",
+        "_id": "1",
+        "_score": 1.0,
+        "_source": {
+          "agg_metric": {
+            "min": -302.5,
+            "max": 702.3,
+            "sum": 200.0,
+            "value_count": 25
           }
         }
       }
     ]
   }
 }
---------------------------------------------------
+----
 // TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,/]