Rollup APIedit

Aggregates an index’s time series data and stores the results in a new read-only index. For example, you can roll up hourly data into daily or weekly summaries.

POST /my-index-000001/_rollup/rollup-my-index-000001
{
  "groups": {
    "date_histogram": {
      "field": "@timestamp",
      "calendar_interval": "1d"
    },
    "terms": {
      "fields": [
        "my-keyword-field",
        "my-other-keyword-field"
      ]
    }
  },
  "metrics": [
    {
      "field": "my-numeric-field",
      "metrics": [
        "min",
        "max",
        "avg"
      ]
    }
  ]
}

Requestedit

PUT /<index>/_rollup/<rollup-index>

Prerequisitesedit

  • You can only roll up an index that contains:

  • If the Elasticsearch security features are enabled, you must have the manage index privilege for the index you roll up.

Path parametersedit

<index>
(Required, string) Index to roll up. Cannot be a data stream or index alias. Does not support multi-target syntax or wildcards (*).
<rollup-index>

(Required, string) New index that stores the rollup results. Cannot be an existing index, a data stream, or an index alias.

The request creates this index with index.blocks.write set to true. If the source <index> is a backing index for a data stream, this index is a backing index for the same stream.

Request bodyedit

groups

(Required, object) Aggregates and stores fields in the rollup.

Properties of groups
date_histogram

(Required, date_histogram aggregation object) Groups documents based on a provided time interval.

Properties of date_histogram
field
(Required, string) date or date_nanos field containing a timestamp. If you’re rolling up a backing index or using the Elastic Common Schema (ECS), we recommend using @timestamp.
calendar_interval or fixed_interval

(Required, time units) Time interval used to group documents. For differences between calendar_interval and fixed_interval, see Calendar and fixed intervals.

Choose this value carefully. You won’t be able to use a smaller interval later. For example, you can’t aggregate daily rollups into hourly summaries. However, smaller time intervals can greatly increase the size of the resulting rollup index.

time_zone
(Optional, string) Time zone for the field. Valid values are ISO 8601 UTC offsets, such as +01:00 or -08:00, and IANA time zone IDs, such as America/Los_Angeles. Defaults to +00:00 (UTC).
histogram

(Optional, histogram aggregation object) Groups and stores numeric field values based on a provided interval.

Properties of histogram
fields

(Required*, string or array of strings) Numeric fields to group. If you specify a histogram object, this property is required.

Do not use the same fields in histogram and metrics. If you specify the same field in both histogram and metrics, the rollup attempt will fail.

interval
(Required*, integer) Numeric interval used to group the fields. If you specify a histogram object, this property is required.
terms

(Optional, terms aggregation object) Stores values for keyword family and numeric fields.

Properties of terms
fields

(Required*, string or array of strings) Keyword family and numeric fields to store. If you specify a terms object, this property is required.

Avoid storing high-cardinality fields. High-cardinality fields can greatly increase the size of the resulting rollup index.

metrics

(Required, object or array of objects) Collects and stores metrics for numeric fields. You must specify at least one metrics object.

Properties of metrics objects
field

(Required, string) Numeric field to collect metrics for.

Do not use the same fields in histogram and metrics. If you specify the same field in both histogram and metrics, the rollup attempt will fail.

metrics

(Required, string or array of strings) Metrics to collect. Each value corresponds to a metric aggregation. Valid values are min, max, sum, avg, and value_count. You must specify at least one value.

The rollup index stores these metrics in an aggregate_metric_double field. The avg metric stores both the sum and value_count values. This lets you accurately average rollups over larger time intervals. For example, you can accurately roll up hourly averages into daily averages.

page_size

(Optional, integer) Maximum number of rollup results to process at once. Defaults to 1000. Larger values run faster but require more memory.

This argument only affects the speed and memory usage of the rollup operation. It does not affect the rollup results.

timeout
(Optional, time value) Time to wait for the request to complete. Defaults to 20s (20 seconds).