elasticsearch/docs/reference/rollup/apis/rollup-api.asciidoc

[role="xpack"]
[testenv="basic"]
[[rollup-api]]
=== Rollup API
++++
<titleabbrev>Rollup</titleabbrev>
++++

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.

[source,console]
----
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"
      ]
    }
  ]
}
----
// TEST[setup:my_index]


[[rollup-api-request]]
==== {api-request-title}

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

[[rollup-api-prereqs]]
==== {api-prereq-title}

If the {es} {security-features} are enabled, you must have the `manage` or
`manage_rollup` cluster privilege to use this API. See <<security-privileges>>.

[[rollup-api-path-params]]
==== {api-path-parms-title}

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

`<rollup-index>`::
(Required, string)
New index that stores the rollup results. Cannot be an existing index,
a <<data-streams,data stream>>, or an <<indices-aliases,index alias>>.
+
The request creates this index with
<<index-modules-blocks,`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.

[role="child_attributes"]
[[rollup-api-request-body]]
==== {api-request-body-title}

`groups`::
(Required, object)
Aggregates and stores fields in the rollup.
+
.Properties of `groups`
[%collapsible%open]
=====
`date_histogram`::
(Required,
<<search-aggregations-bucket-datehistogram-aggregation,`date_histogram`
aggregation>> object)
Groups documents based on a provided time interval.
+
.Properties of `date_histogram`
[%collapsible%open]
======
`field`::
(Required, string)
<<date,`date`>> or <<date_nanos,`date_nanos`>> field containing a timestamp. If
you're rolling up a backing index or using the {ecs-ref}[Elastic Common Schema
(ECS)], we recommend using `@timestamp`.

`calendar_interval` or `fixed_interval`::
(Required, <<time-units,time units>>)
Time interval used to group documents. For differences between
`calendar_interval` and `fixed_interval`, see <<calendar_and_fixed_intervals>>.
+
TIP: 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, <<search-aggregations-bucket-histogram-aggregation,`histogram`
aggregation>> object)
Groups and stores <<number,numeric>> field values based on a provided interval.
+
.Properties of `histogram`
[%collapsible%open]
======
`fields`::
(Required*, array of strings)
Array of <<number,numeric>> fields to group. If you specify a `histogram`
object, this property is required.

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

`terms`::
(Optional, <<search-aggregations-bucket-terms-aggregation,`terms`
aggregation>> object)
Stores values for <<keyword,keyword family>> and <<number,numeric>> fields.
+
.Properties of `terms`
[%collapsible%open]
======
`fields`::
(Required*, array of strings)
Array of <<keyword,keyword family>> and <<number,numeric>> fields to store. If
you specify a `terms` object, this property is required.
+
TIP: Avoid storing high-cardinality fields. High-cardinality fields can greatly
increase the size of the resulting rollup index.
======
=====

`metrics`::
(Optional, array of objects)
Collects and stores metrics for <<number,numeric>> fields.
+
.Properties of `metrics` objects
[%collapsible%open]
=====
`field`::
(Required*, string)
<<number,Numeric>> field to collect metrics for. If you specify a `metrics`
object, this property is required.

`metrics`::
(Required*, array of strings)
Array of metrics to collect. Each value corresponds to a
<<search-aggregations-metrics,metric aggregation>>. Valid values are
<<search-aggregations-metrics-min-aggregation,`min`>>,
<<search-aggregations-metrics-max-aggregation,`max`>>,
<<search-aggregations-metrics-sum-aggregation,`sum`>>,
<<search-aggregations-metrics-avg-aggregation,`avg`>>, and
<<search-aggregations-metrics-valuecount-aggregation,`value_count`>>. You must
specify at least one value. If you specify a `metrics` object, this property is
required.
+
NOTE: The rollup index stores these metrics in an
<<aggregate-metric-double,`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.
+
NOTE: This argument only affects the speed and memory usage of the rollup
operation. It does not affect the rollup results.

`timeout`::
(Optional, <<time-units,time value>>)
Time to wait for the request to complete. Defaults to `20s` (20 seconds).