This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Field data types Alias field type »
Elastic Docs ›Elasticsearch Guide [8.x] ›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.

resp = client.indices.create(
    index="my-index",
    mappings={
        "properties": {
            "my-agg-metric-field": {
                "type": "aggregate_metric_double",
                "metrics": [
                    "min",
                    "max",
                    "sum",
                    "value_count"
                ],
                "default_metric": "max"
            }
        }
    },
)
print(resp)
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
const response = await client.indices.create({
  index: "my-index",
  mappings: {
    properties: {
      "my-agg-metric-field": {
        type: "aggregate_metric_double",
        metrics: ["min", "max", "sum", "value_count"],
        default_metric: "max",
      },
    },
  },
});
console.log(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.

resp = client.indices.create(
    index="stats-index",
    mappings={
        "properties": {
            "agg_metric": {
                "type": "aggregate_metric_double",
                "metrics": [
                    "min",
                    "max",
                    "sum",
                    "value_count"
                ],
                "default_metric": "max"
            }
        }
    },
)
print(resp)
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
const response = await client.indices.create({
  index: "stats-index",
  mappings: {
    properties: {
      agg_metric: {
        type: "aggregate_metric_double",
        metrics: ["min", "max", "sum", "value_count"],
        default_metric: "max",
      },
    },
  },
});
console.log(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.

resp = client.index(
    index="stats-index",
    id="1",
    document={
        "agg_metric": {
            "min": -302.5,
            "max": 702.3,
            "sum": 200,
            "value_count": 25
        }
    },
)
print(resp)

resp1 = client.index(
    index="stats-index",
    id="2",
    document={
        "agg_metric": {
            "min": -93,
            "max": 1702.3,
            "sum": 300,
            "value_count": 25
        }
    },
)
print(resp1)
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
const response = await client.index({
  index: "stats-index",
  id: 1,
  document: {
    agg_metric: {
      min: -302.5,
      max: 702.3,
      sum: 200,
      value_count: 25,
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "stats-index",
  id: 2,
  document: {
    agg_metric: {
      min: -93,
      max: 1702.3,
      sum: 300,
      value_count: 25,
    },
  },
});
console.log(response1);
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.

resp = client.search(
    index="stats-index",
    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"
            }
        }
    },
)
print(resp)
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
const response = await client.search({
  index: "stats-index",
  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",
      },
    },
  },
});
console.log(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.

resp = client.search(
    index="stats-index",
    query={
        "term": {
            "agg_metric": {
                "value": 702.3
            }
        }
    },
)
print(resp)
response = client.search(
  index: 'stats-index',
  body: {
    query: {
      term: {
        agg_metric: {
          value: 702.3
        }
      }
    }
  }
)
puts response
const response = await client.search({
  index: "stats-index",
  query: {
    term: {
      agg_metric: {
        value: 702.3,
      },
    },
  },
});
console.log(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 work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

For example:

const response = await client.indices.create({
  index: "idx",
  settings: {
    index: {
      mapping: {
        source: {
          mode: "synthetic",
        },
      },
    },
  },
  mappings: {
    properties: {
      agg_metric: {
        type: "aggregate_metric_double",
        metrics: ["min", "max", "sum", "value_count"],
        default_metric: "max",
      },
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "idx",
  id: 1,
  document: {
    agg_metric: {
      min: -302.5,
      max: 702.3,
      sum: 200,
      value_count: 25,
    },
  },
});
console.log(response1);
PUT idx
{
  "settings": {
    "index": {
      "mapping": {
        "source": {
          "mode": "synthetic"
        }
      }
    }
  },
  "mappings": {
    "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 »