IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Field data types Alias field type »
Elastic Docs ›Elasticsearch Guide [8.8] ›Mapping ›Field data types

Aggregate metric field type

edit

Aggregate metric field type

edit

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.

response = client.indices.create(
  index: 'my-index',
  body: {
    mappings: {
      properties: {
        "my-agg-metric-field": {
          type: 'aggregate_metric_double',
          metrics: [
            'min',
            'max',
            'sum',
            'value_count'
          ],
          default_metric: 'max'
        }
      }
    }
  }
)
puts response
PUT my-index
{
  "mappings": {
    "properties": {
      "my-agg-metric-field": {
        "type": "aggregate_metric_double",
        "metrics": [ "min", "max", "sum", "value_count" ],
        "default_metric": "max"
      }
    }
  }
}

Parameters for aggregate_metric_double fields

edit
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

edit

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

edit

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.

response = client.indices.create(
  index: 'stats-index',
  body: {
    mappings: {
      properties: {
        agg_metric: {
          type: 'aggregate_metric_double',
          metrics: [
            'min',
            'max',
            'sum',
            'value_count'
          ],
          default_metric: 'max'
        }
      }
    }
  }
)
puts response
PUT stats-index
{
  "mappings": {
    "properties": {
      "agg_metric": {
        "type": "aggregate_metric_double",
        "metrics": [ "min", "max", "sum", "value_count" ],
        "default_metric": "max"
      }
    }
  }
}

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

response = client.index(
  index: 'stats-index',
  id: 1,
  body: {
    agg_metric: {
      min: -302.5,
      max: 702.3,
      sum: 200,
      value_count: 25
    }
  }
)
puts response

response = client.index(
  index: 'stats-index',
  id: 2,
  body: {
    agg_metric: {
      min: -93,
      max: 1702.3,
      sum: 300,
      value_count: 25
    }
  }
)
puts response
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
  }
}

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

response = client.search(
  index: 'stats-index',
  size: 0,
  body: {
    aggregations: {
      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'
        }
      }
    }
  }
)
puts response
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 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
    }
  }
}

Queries on a aggregate_metric_double field use the default_metric value.

response = client.search(
  index: 'stats-index',
  body: {
    query: {
      term: {
        agg_metric: {
          value: 702.3
        }
      }
    }
  }
)
puts response
GET stats-index/_search
{
  "query": {
    "term": {
      "agg_metric": {
        "value": 702.30
      }
    }
  }
}

The search returns the following hit. The value of the default_metric field, max, 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
          }
        }
      }
    ]
  }
}

Synthetic _source

edit

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 apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

aggregate_metric-double fields support synthetic _source in their default configuration. Synthetic _source cannot be used together with ignore_malformed.

For example:

PUT idx
{
  "mappings": {
    "_source": { "mode": "synthetic" },
    "properties": {
      "agg_metric": {
        "type": "aggregate_metric_double",
        "metrics": [ "min", "max", "sum", "value_count" ],
        "default_metric": "max"
      }
    }
  }
}

PUT idx/_doc/1
{
  "agg_metric": {
    "min": -302.50,
    "max": 702.30,
    "sum": 200.0,
    "value_count": 25
  }
}

Will become:

{
  "agg_metric": {
    "min": -302.50,
    "max": 702.30,
    "sum": 200.0,
    "value_count": 25
  }
}
« Field data types Alias field type »