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]
// TEST[s/my-keyword-field/http.request.method/]
// TEST[s/my-other-keyword-field/user.id/]
// TEST[s/my-numeric-field/http.response.bytes/]


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

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

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

* You can only roll up an index that contains:

** A <<date,`date`>> or <<date_nanos,`date_nanos`>> timestamp field.
** At least one metric to roll up. This field must be a <<number,numeric>>,
  `date`, or `date_nanos` field other than the timestamp field. This field
  cannot be an `unsigned_long`.

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-indices,index privilege>> for the index you roll up.

[[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}

// tag::rollup-config[]
`groups`::
(Required, object)
Aggregates and groups documents 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`.
+
WARNING: Do not use this field in `metrics`. If you do, the rollup attempt will
fail.

`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 documents based on a numeric interval.
+
.Properties of `histogram`
[%collapsible%open]
======
`fields`::
(Required*, string or array of strings)
<<number,Numeric>> fields to group. `unsigned_long` fields are not supported. If
you specify a `histogram` object, this property is required.
+
WARNING: Do not use these fields in `metrics`. If you do, 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, <<search-aggregations-bucket-terms-aggregation,`terms`
aggregation>> object)
Groups documents based on unique field values.
+
.Properties of `terms`
[%collapsible%open]
======
`fields`::
+
--
(Required*, string or array of strings)
Fields to store unique values for. Supports the following field types:

* <<keyword,Keyword family>> types
* <<number,Numeric>> types, excluding `unsigned_long`
* <<text,`text`>> fields with <<fielddata-mapping-param,`fielddata`>> enabled

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`::
(Required, object or array of objects)
Collects and stores metrics for fields. You must specify at least one `metrics`
object.
+
.Properties of `metrics` objects
[%collapsible%open]
=====
`field`::
(Required, string)
<<number,Numeric>>, <<date,`date`>>, or <<date_nanos,`date_nanos`>> field to
collect metrics for. `unsigned_long` fields are not supported.
+
WARNING: Do not use fields specified in `histogram` or `date_histogram`. If you
do, the rollup attempt will fail.

`metrics`::
(Required, string or array of strings)
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`>>. <<date,`date`>> and <<date_nanos,`date_nanos`>>
fields only support the `max`, `min`, and `value_count` metrics. You must specify
at least one value.
+
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.
=====
// end::rollup-config[]

`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).