elasticsearch/docs/reference/indices/downsample-data-stream.asciidoc

[role="xpack"]
[[indices-downsample-data-stream]]
=== Downsample index API
++++
<titleabbrev>Downsample</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-data-stream[Data stream APIs].
--

Aggregates a time series (TSDS) index and stores
pre-computed statistical summaries (`min`, `max`, `sum`, `value_count` and
`avg`) for each metric field grouped by a configured time interval. For example,
a TSDS index that contains metrics sampled every 10 seconds can be downsampled
to an hourly index. All documents within an hour interval are summarized and
stored as a single document in the downsample index.

// tag::downsample-example[]
////
[source,console]
----
PUT /my-time-series-index
{
    "settings": {
        "index": {
            "mode": "time_series",
            "time_series": {
                "start_time": "2022-06-10T00:00:00Z",
                "end_time": "2022-06-30T23:59:59Z"
            },
            "routing_path": [
                "test.namespace"
            ],
            "number_of_replicas": 0,
            "number_of_shards": 2
        }
    },
    "mappings": {
        "properties": {
            "@timestamp": {
                "type": "date"
            },
            "metric": {
                "type": "long",
                "time_series_metric": "gauge"
            },
            "dimension": {
                "type": "keyword",
                "time_series_dimension": true
            }
        }
    }
}

PUT /my-time-series-index/_block/write

----
// TEST
////

[source,console]
----
POST /my-time-series-index/_downsample/my-downsampled-time-series-index
{
    "fixed_interval": "1d"
}
----
// TEST[continued]

////
[source,console]
----
DELETE /my-time-series-index*
DELETE _data_stream/*
DELETE _index_template/*
----
// TEST[continued]
////
// end::downsample-example[]

Check the <<downsampling,Downsampling>> documentation for an overview, details about the downsampling process, and examples of running downsampling manually and as part of an ILM policy.

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

`POST /<source-index>/_downsample/<output-downsampled-index>`

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

* Only indices in a <<tsds,time series data stream>> are supported.

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

* Neither <<field-and-document-access-control,field nor document level security>> can be defined on the source index.

* The source index must be read only (`index.blocks.write: true`).

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

`<source-index>`::
(Optional, string) Name of the time series index to downsample.

`<output-downsampled_index>`::
+
--
(Required, string) Name of the index to create. 

include::{es-ref-dir}/indices/create-index.asciidoc[tag=index-name-reqs]
--

[role="child_attributes"]
[[downsample-api-query-parms]]
==== {api-query-parms-title}

`fixed_interval`:: (Required, <<time-units,time units>>) The interval at which
to aggregate the original time series index. For example, `60m` produces a
document for each 60 minute (hourly) interval. This follows standard time
formatting syntax as used elsewhere in {es}.
+
NOTE: Smaller, more granular intervals take up proportionally more space.