docs/reference/elasticsearch/mapping-reference/aggregate-metric-double.md
Stores pre-aggregated numeric values for 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 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 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.
::::
PUT my-index
{
"mappings": {
"properties": {
"my-agg-metric-field": {
"type": "aggregate_metric_double",
"metrics": [ "min", "max", "sum", "value_count" ]
}
}
}
}
aggregate_metric_double fields [aggregate-metric-double-params]metrics
: (Required, array of strings) Array of metric sub-fields to store. Each value corresponds to a metric aggregation. Valid values are min, max, sum, and value_count. You must specify at least one value.
default_metric {applies_to}stack: deprecated 9.4 {applies_to}serverless: deprecated
: :::{admonition} Deprecated in 9.4
The default metric value depends on the number of sub-fields:
- When there are multiple sub-fields, the default is the average, calculated from sum and value_count.
- When there is only a single sub-field, that sub-field's value is used directly.
% (see deprecations for more information).
:::
(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.
time_series_metric
: (Optional, string) Marks the field as a time series metric. The value is the metric type. You can’t update this parameter for existing fields.
**Valid `time_series_metric` values for `aggregate_metric_double` fields**:
`gauge`
: A metric that represents a single numeric that can arbitrarily increase or decrease. For example, a temperature or available disk space.
`null` (Default)
: Not a time series metric.
In Query DSL, we designed aggregate_metric_double fields
for use with the following aggregations:
min aggregation returns the minimum value of all min sub-fields.max aggregation returns the maximum value of all max sub-fields.sum aggregation returns the sum of the values of all sum sub-fields.value_count aggregation returns the sum of the values of all value_count sub-fields.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.Running any other aggregation on an aggregate_metric_double field will fail with an "unsupported aggregation" error.
Finally, an aggregate_metric_double field supports the following queries, for which it behaves as a double:
To achieve that, it delegates its behavior as follows:
sum and value_count metrics exist, the average is used. {applies_to}stack: ga 9.4In ES|QL, we designed aggregate_metric_double fields
for use with the time series aggregations either natively using one of the sub-fields or by
delegating to the average using the sum and value_count metrics.
The following create index API request creates an index with an aggregate_metric_double field named agg_metric.
PUT stats-index
{
"mappings": {
"properties": {
"agg_metric": {
"type": "aggregate_metric_double",
"metrics": [ "min", "max", "sum", "value_count" ]
}
}
}
}
The following index API request adds documents with pre-aggregated data in the agg_metric field.
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.
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.
{
...
"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 average value.
GET stats-index/_search
{
"query": {
"term": {
"agg_metric": {
"value": 8
}
}
}
}
% TEST[continued]
The search returns the following hit. The average value of the agg_metric matches the query value.
{
...
"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
}
}
}
]
}
}
% TESTRESPONSE[s/.../"took": $body.took,"timed_out": false,"_shards": $body._shards,/]
_source [aggregate-metric-double-synthetic-source]For example:
$$$synthetic-source-aggregate-metric-double-example$$$
PUT idx
{
"settings": {
"index": {
"mapping": {
"source": {
"mode": "synthetic"
}
}
}
},
"mappings": {
"properties": {
"agg_metric": {
"type": "aggregate_metric_double",
"metrics": [ "min", "max", "sum", "value_count" ]
}
}
}
}
PUT idx/_doc/1
{
"agg_metric": {
"min": -302.50,
"max": 702.30,
"sum": 200.0,
"value_count": 25
}
}
% TEST[s/$/\nGET idx/_doc/1?filter_path=_source\n/]
Will become:
{
"agg_metric": {
"min": -302.50,
"max": 702.30,
"sum": 200.0,
"value_count": 25
}
}
% TEST[s/^/{"_source":/ s/\n$/}/]