[DOCS] Added docs for aggregate_metric_double field

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]
@@ -126,6 +127,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[]

docs/reference/mapping/types/aggregate-metric-double.asciidoc

@@ -0,0 +1,196 @@
+[role="xpack"]
+[testenv="basic"]
+[[aggregate-metric-double]]
+=== Aggregate metric field type
+++++
+<titleabbrev>Aggregate metric</titleabbrev>
+++++
+
+The `aggregate_metric_double` field stores pre-aggregated numeric values (`min`, `max`, `sum` and `value_count`) that can be directly
+accessed by metric aggregations. An `aggregate_metric_double` field is defined as an object with one ore more of the following sub-fields:
+`min`, `max`, `sum` and `value_count`.
+
+The power of the `aggregate_metric_double` field comes from the fact that when an `aggregate_metric_double` field
+participates in a metric aggregation, it returns the value of the associated sub-field for that aggregation.
+For example, an `aggregate_metric_double` field that stores `min` and `max` metrics will return the `min` metric when
+collected by a <<search-aggregations-metrics-min-aggregation,min>> aggregation and the `max` metric
+when participating in a <<search-aggregations-metrics-max-aggregation-histogram-fields,max>> aggregation.
+
+[IMPORTANT]
+========
+* An `aggregate_metric_double` field can only store a single value for each `metric` sub-field per document.
+Nested arrays are not supported.
+* The values of the `min`, `max`, `sum` can be any `double` numbers. The values of `value_count` can only be
+a positive long number.
+========
+
+[[aggregate-metric-double-uses]]
+==== Uses
+
+All metric sub-fields of the `aggregate_metric_double` fields are stored as numeric <<doc-values,doc values>>
+and are primarily intended for use with the following aggregations:
+
+* <<search-aggregations-metrics-min-aggregation,min>> aggregation returns the minimum value of all `min` sub-fields.
+* <<search-aggregations-metrics-max-aggregation,max>> aggregation returns the maximum value of all `max` sub-fields.
+* <<search-aggregations-metrics-sum-aggregation,sum>> aggregation returns the sum of the values of all `sum` sub-fields.
+* <<search-aggregations-metrics-valuecount-aggregation,value_count>> aggregation returns the sum of the values of all `value_count`
+sub-fields.
+* <<search-aggregations-metrics-avg-aggregation,avg>> aggregation. The result of the `avg` aggregation is computed using
+the `sum` and `value_count` metrics. Therefore, there is no `avg` metric. To support `avg` aggregations, both `sum` and
+`value_count` metrics must be present.
+
+[[aggregate-metric-double-default]]
+==== Default metric
+
+When an `aggregate_metric_double` field does not participate in any of the above aggregations,
+it behaves as a `double` numeric field. To achieve this, its mapping must contain a `default_metric` which can
+be one of its supported metrics. When an `aggregate_metric_double` field is accessed by a script or any
+of the following queries, it will delegate the operation to its `default_metric` sub-field:
+
+* <<query-dsl-exists-query,exists>> query.
+* <<query-dsl-range-query,range>> query.
+* <<query-dsl-term-query,term>> query.
+* <<query-dsl-terms-query,terms>> query.
+
+[[aggregate-metric-double-example]]
+==== Examples
+
+The following <<indices-create-index, create index>> API request creates a new index with an `aggregate_metric_double` field used
+to store aggregate metric data and sets the `max`:
+
+[source,console]
+--------------------------------------------------
+PUT stats-index
+{
+  "mappings": {
+    "properties": {
+      "agg_metric": {
+        "type": "aggregate_metric_double",
+        "metrics": [ "min", "max", "sum", "value_count"], <1>
+        "default_metric": "max" <2>
+      }
+    }
+  }
+}
+--------------------------------------------------
+<1> The metrics supported by this index are `min`, `max`, `sum`, `value_count`.
+<2> The `default_metric` is the `max` sub-field.
+
+The following <<docs-index_,index>> API requests store pre-aggregated data:
+
+[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
+    }
+}
+--------------------------------------------------
+
+The `agg_metric` field allows us to run (`min`, `max`, `sum`, `value_count`, `avg`) aggregations
+as in the following example:
+
+[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 above aggregations will compute results based on their associated metrics
+and will return the following output:
+
+[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,/]
+
+
+To give an example of how the `default_metric` is used in queries, let's see
+a `term` query on the `agg_metric` field:
+
+[source,console]
+--------------------------------------------------
+GET stats-index/_search
+{
+  "query": {
+    "term": {
+      "agg_metric": {
+        "value": 702.30,
+        "boost": 1.0
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+Running a `term` query for a specific value, will return all documents that have this value
+stored as the `default_metric` sub-field. From the result, we can see that the `aggregate_metric_double`
+field delegates the `term` query to its `max` sub-field.
+
+[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,/]