[7.x] [DOCS] Added docs for aggregate_metric_double field (#66306)

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[]

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

@@ -0,0 +1,236 @@
+[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
+  }
+}
+----
+// 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" } }
+  }
+}
+----
+// TEST[continued]
+
+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
+      }
+    }
+  }
+}
+----
+// TEST[continued]
+
+The search returns the following hit. The value of the `default_metric` field,
+`max`, matches the query value.
+
+[source,console-result]
+----
+{
+  ...
+    "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": 1.0,
+    "hits": [
+      {
+        "_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,/]