Aggregate metric field type

Aggregate metric field type

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.

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.

  1. PUT my-index
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "my-agg-metric-field": {
  6.         "type": "aggregate_metric_double",
  7.         "metrics": [ "min", "max", "sum", "value_count" ],
  8.         "default_metric": "max"
  9.       }
  10.     }
  11.   }
  12. }

Parameters for aggregate_metric_double fields

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

(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

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. (Optional, string)

For internal use by Elastic only.

Marks the field as a time series metric. The value is the metric type. Defaults to null (Not a time series metric).

For aggregate_metric_double fields, this parameter accepts counter, gauge, and summary. You can’t update this parameter for existing fields.

Uses

We designed aggregate_metric_double fields for use with the following aggregations:

  • A min aggregation returns the minimum value of all min sub-fields.
  • A max aggregation returns the maximum value of all max sub-fields.
  • A sum aggregation returns the sum of the values of all sum sub-fields.
  • A value_count aggregation returns the sum of the values of all value_count sub-fields.
  • A 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 by delegating its behavior to its default_metric sub-field:

Examples

The following 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.

  1. PUT stats-index
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "agg_metric": {
  6.         "type": "aggregate_metric_double",
  7.         "metrics": [ "min", "max", "sum", "value_count" ],
  8.         "default_metric": "max"
  9.       }
  10.     }
  11.   }
  12. }

The following index API request adds documents with pre-aggregated data in the agg_metric field.

  1. PUT stats-index/_doc/1
  2. {
  3.   "agg_metric": {
  4.     "min": -302.50,
  5.     "max": 702.30,
  6.     "sum": 200.0,
  7.     "value_count": 25
  8.   }
  9. }
  11. PUT stats-index/_doc/2
  12. {
  13.   "agg_metric": {
  14.     "min": -93.00,
  15.     "max": 1702.30,
  16.     "sum": 300.00,
  17.     "value_count": 25
  18.   }
  19. }

You can run min, max, sum, value_count, and avg aggregations on a agg_metric field.

  1. POST stats-index/_search?size=0
  2. {
  3.   "aggs": {
  4.     "metric_min": { "min": { "field": "agg_metric" } },
  5.     "metric_max": { "max": { "field": "agg_metric" } },
  6.     "metric_value_count": { "value_count": { "field": "agg_metric" } },
  7.     "metric_sum": { "sum": { "field": "agg_metric" } },
  8.     "metric_avg": { "avg": { "field": "agg_metric" } }
  9.   }
  10. }

The aggregation results are based on related metric sub-field values.

  1. {
  2. ...
  3.   "aggregations": {
  4.     "metric_min": {
  5.       "value": -302.5
  6.     },
  7.     "metric_max": {
  8.       "value": 1702.3
  9.     },
  10.     "metric_value_count": {
  11.       "value": 50
  12.     },
  13.     "metric_sum": {
  14.       "value": 500.0
  15.     },
  16.     "metric_avg": {
  17.       "value": 10.0
  18.     }
  19.   }
  20. }

Queries on a aggregate_metric_double field use the default_metric value.

  1. GET stats-index/_search
  2. {
  3.   "query": {
  4.     "term": {
  5.       "agg_metric": {
  6.         "value": 702.30
  7.       }
  8.     }
  9.   }
  10. }

The search returns the following hit. The value of the default_metric field, max, matches the query value.

  1. {
  2.   ...
  3.     "hits": {
  4.     "total": {
  5.       "value": 1,
  6.       "relation": "eq"
  7.     },
  8.     "max_score": 1.0,
  9.     "hits": [
  10.       {
  11.         "_index": "stats-index",
  12.         "_type": "_doc",
  13.         "_id": "1",
  14.         "_score": 1.0,
  15.         "_source": {
  16.           "agg_metric": {
  17.             "min": -302.5,
  18.             "max": 702.3,
  19.             "sum": 200.0,
  20.             "value_count": 25
  21.           }
  22.         }
  23.       }
  24.     ]
  25.   }
  26. }