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. resp = client.indices.create(
  2.     index="my-index",
  3.     mappings={
  4.         "properties": {
  5.             "my-agg-metric-field": {
  6.                 "type": "aggregate_metric_double",
  7.                 "metrics": [
  8.                     "min",
  9.                     "max",
  10.                     "sum",
  11.                     "value_count"
  12.                 ],
  13.                 "default_metric": "max"
  14.             }
  15.         }
  16.     },
  17. )
  18. print(resp)
  1. response = client.indices.create(
  2.   index: 'my-index',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         "my-agg-metric-field": {
  7.           type: 'aggregate_metric_double',
  8.           metrics: [
  9.             'min',
  10.             'max',
  11.             'sum',
  12.             'value_count'
  13.           ],
  14.           default_metric: 'max'
  15.         }
  16.       }
  17.     }
  18.   }
  19. )
  20. puts response
  1. const response = await client.indices.create({
  2.   index: "my-index",
  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. });
  13. console.log(response);
  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

(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.

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. resp = client.indices.create(
  2.     index="stats-index",
  3.     mappings={
  4.         "properties": {
  5.             "agg_metric": {
  6.                 "type": "aggregate_metric_double",
  7.                 "metrics": [
  8.                     "min",
  9.                     "max",
  10.                     "sum",
  11.                     "value_count"
  12.                 ],
  13.                 "default_metric": "max"
  14.             }
  15.         }
  16.     },
  17. )
  18. print(resp)
  1. response = client.indices.create(
  2.   index: 'stats-index',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         agg_metric: {
  7.           type: 'aggregate_metric_double',
  8.           metrics: [
  9.             'min',
  10.             'max',
  11.             'sum',
  12.             'value_count'
  13.           ],
  14.           default_metric: 'max'
  15.         }
  16.       }
  17.     }
  18.   }
  19. )
  20. puts response
  1. const response = await client.indices.create({
  2.   index: "stats-index",
  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. });
  13. console.log(response);
  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. resp = client.index(
  2.     index="stats-index",
  3.     id="1",
  4.     document={
  5.         "agg_metric": {
  6.             "min": -302.5,
  7.             "max": 702.3,
  8.             "sum": 200,
  9.             "value_count": 25
  10.         }
  11.     },
  12. )
  13. print(resp)
  15. resp1 = client.index(
  16.     index="stats-index",
  17.     id="2",
  18.     document={
  19.         "agg_metric": {
  20.             "min": -93,
  21.             "max": 1702.3,
  22.             "sum": 300,
  23.             "value_count": 25
  24.         }
  25.     },
  26. )
  27. print(resp1)
  1. response = client.index(
  2.   index: 'stats-index',
  3.   id: 1,
  4.   body: {
  5.     agg_metric: {
  6.       min: -302.5,
  7.       max: 702.3,
  8.       sum: 200,
  9.       value_count: 25
  10.     }
  11.   }
  12. )
  13. puts response
  15. response = client.index(
  16.   index: 'stats-index',
  17.   id: 2,
  18.   body: {
  19.     agg_metric: {
  20.       min: -93,
  21.       max: 1702.3,
  22.       sum: 300,
  23.       value_count: 25
  24.     }
  25.   }
  26. )
  27. puts response
  1. const response = await client.index({
  2.   index: "stats-index",
  3.   id: 1,
  4.   document: {
  5.     agg_metric: {
  6.       min: -302.5,
  7.       max: 702.3,
  8.       sum: 200,
  9.       value_count: 25,
  10.     },
  11.   },
  12. });
  13. console.log(response);
  15. const response1 = await client.index({
  16.   index: "stats-index",
  17.   id: 2,
  18.   document: {
  19.     agg_metric: {
  20.       min: -93,
  21.       max: 1702.3,
  22.       sum: 300,
  23.       value_count: 25,
  24.     },
  25.   },
  26. });
  27. console.log(response1);
  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. resp = client.search(
  2.     index="stats-index",
  3.     size="0",
  4.     aggs={
  5.         "metric_min": {
  6.             "min": {
  7.                 "field": "agg_metric"
  8.             }
  9.         },
  10.         "metric_max": {
  11.             "max": {
  12.                 "field": "agg_metric"
  13.             }
  14.         },
  15.         "metric_value_count": {
  16.             "value_count": {
  17.                 "field": "agg_metric"
  18.             }
  19.         },
  20.         "metric_sum": {
  21.             "sum": {
  22.                 "field": "agg_metric"
  23.             }
  24.         },
  25.         "metric_avg": {
  26.             "avg": {
  27.                 "field": "agg_metric"
  28.             }
  29.         }
  30.     },
  31. )
  32. print(resp)
  1. response = client.search(
  2.   index: 'stats-index',
  3.   size: 0,
  4.   body: {
  5.     aggregations: {
  6.       metric_min: {
  7.         min: {
  8.           field: 'agg_metric'
  9.         }
  10.       },
  11.       metric_max: {
  12.         max: {
  13.           field: 'agg_metric'
  14.         }
  15.       },
  16.       metric_value_count: {
  17.         value_count: {
  18.           field: 'agg_metric'
  19.         }
  20.       },
  21.       metric_sum: {
  22.         sum: {
  23.           field: 'agg_metric'
  24.         }
  25.       },
  26.       metric_avg: {
  27.         avg: {
  28.           field: 'agg_metric'
  29.         }
  30.       }
  31.     }
  32.   }
  33. )
  34. puts response
  1. const response = await client.search({
  2.   index: "stats-index",
  3.   size: 0,
  4.   aggs: {
  5.     metric_min: {
  6.       min: {
  7.         field: "agg_metric",
  8.       },
  9.     },
  10.     metric_max: {
  11.       max: {
  12.         field: "agg_metric",
  13.       },
  14.     },
  15.     metric_value_count: {
  16.       value_count: {
  17.         field: "agg_metric",
  18.       },
  19.     },
  20.     metric_sum: {
  21.       sum: {
  22.         field: "agg_metric",
  23.       },
  24.     },
  25.     metric_avg: {
  26.       avg: {
  27.         field: "agg_metric",
  28.       },
  29.     },
  30.   },
  31. });
  32. console.log(response);
  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. resp = client.search(
  2.     index="stats-index",
  3.     query={
  4.         "term": {
  5.             "agg_metric": {
  6.                 "value": 702.3
  7.             }
  8.         }
  9.     },
  10. )
  11. print(resp)
  1. response = client.search(
  2.   index: 'stats-index',
  3.   body: {
  4.     query: {
  5.       term: {
  6.         agg_metric: {
  7.           value: 702.3
  8.         }
  9.       }
  10.     }
  11.   }
  12. )
  13. puts response
  1. const response = await client.search({
  2.   index: "stats-index",
  3.   query: {
  4.     term: {
  5.       agg_metric: {
  6.         value: 702.3,
  7.       },
  8.     },
  9.   },
  10. });
  11. console.log(response);
  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.         "_id": "1",
  13.         "_score": 1.0,
  14.         "_source": {
  15.           "agg_metric": {
  16.             "min": -302.5,
  17.             "max": 702.3,
  18.             "sum": 200.0,
  19.             "value_count": 25
  20.           }
  21.         }
  22.       }
  23.     ]
  24.   }
  25. }

Synthetic _source

Synthetic _source is Generally Available only for TSDB indices (indices that have index.mode set to time_series). For other indices synthetic _source is in technical preview. Features in technical preview 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.

For example:

  1. resp = client.indices.create(
  2.     index="idx",
  3.     settings={
  4.         "index": {
  5.             "mapping": {
  6.                 "source": {
  7.                     "mode": "synthetic"
  8.                 }
  9.             }
  10.         }
  11.     },
  12.     mappings={
  13.         "properties": {
  14.             "agg_metric": {
  15.                 "type": "aggregate_metric_double",
  16.                 "metrics": [
  17.                     "min",
  18.                     "max",
  19.                     "sum",
  20.                     "value_count"
  21.                 ],
  22.                 "default_metric": "max"
  23.             }
  24.         }
  25.     },
  26. )
  27. print(resp)
  29. resp1 = client.index(
  30.     index="idx",
  31.     id="1",
  32.     document={
  33.         "agg_metric": {
  34.             "min": -302.5,
  35.             "max": 702.3,
  36.             "sum": 200,
  37.             "value_count": 25
  38.         }
  39.     },
  40. )
  41. print(resp1)
  1. const response = await client.indices.create({
  2.   index: "idx",
  3.   settings: {
  4.     index: {
  5.       mapping: {
  6.         source: {
  7.           mode: "synthetic",
  8.         },
  9.       },
  10.     },
  11.   },
  12.   mappings: {
  13.     properties: {
  14.       agg_metric: {
  15.         type: "aggregate_metric_double",
  16.         metrics: ["min", "max", "sum", "value_count"],
  17.         default_metric: "max",
  18.       },
  19.     },
  20.   },
  21. });
  22. console.log(response);
  24. const response1 = await client.index({
  25.   index: "idx",
  26.   id: 1,
  27.   document: {
  28.     agg_metric: {
  29.       min: -302.5,
  30.       max: 702.3,
  31.       sum: 200,
  32.       value_count: 25,
  33.     },
  34.   },
  35. });
  36. console.log(response1);
  1. PUT idx
  2. {
  3.   "settings": {
  4.     "index": {
  5.       "mapping": {
  6.         "source": {
  7.           "mode": "synthetic"
  8.         }
  9.       }
  10.     }
  11.   },
  12.   "mappings": {
  13.     "properties": {
  14.       "agg_metric": {
  15.         "type": "aggregate_metric_double",
  16.         "metrics": [ "min", "max", "sum", "value_count" ],
  17.         "default_metric": "max"
  18.       }
  19.     }
  20.   }
  21. }
  23. PUT idx/_doc/1
  24. {
  25.   "agg_metric": {
  26.     "min": -302.50,
  27.     "max": 702.30,
  28.     "sum": 200.0,
  29.     "value_count": 25
  30.   }
  31. }

Will become:

  1. {
  2.   "agg_metric": {
  3.     "min": -302.50,
  4.     "max": 702.30,
  5.     "sum": 200.0,
  6.     "value_count": 25
  7.   }
  8. }