elasticsearch/docs/reference/rollup/apis/rollup-index-caps.asciidoc

ifdef::permanently-unreleased-branch[]

[role="xpack"]
[testenv="basic"]
[[rollup-get-rollup-index-caps]]
=== Get legacy rollup index capabilities API
++++
<titleabbrev>Get legacy rollup index caps</titleabbrev>
++++

include::put-job.asciidoc[tag=legacy-rollup-admon]

Returns the capabilities of rollup jobs for a legacy rollup index.

endif::[]
ifndef::permanently-unreleased-branch[]

[role="xpack"]
[testenv="basic"]
[[rollup-get-rollup-index-caps]]
=== Get rollup index capabilities API
++++
<titleabbrev>Get rollup index caps</titleabbrev>
++++

Returns the rollup capabilities of all jobs inside of a rollup index (e.g. the
index where rollup data is stored).

experimental[]

endif::[]

[[rollup-get-rollup-index-caps-request]]
==== {api-request-title}

`GET <target>/_rollup/data`

[[rollup-get-rollup-index-caps-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `read` index
privilege on the index that stores the rollup results. For more information, see
<<security-privileges>>.

[[rollup-get-rollup-index-caps-desc]]
==== {api-description-title}

A single rollup index may store the data for multiple {rollup-jobs}, and may
have a variety of capabilities depending on those jobs.

This API will allow you to determine:

1. What jobs are stored in an index (or indices specified via a pattern)?
2. What target indices were rolled up, what fields were used in those rollups
and what aggregations can be performed on each job?

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

`<target>`::
(Required, string) Data stream or index to check for rollup capabilities.
Wildcard (`*`) expressions are supported.

[[rollup-get-rollup-index-caps-example]]
==== {api-examples-title}

Imagine we have an index named `sensor-1` full of raw data.  We know that the
data will grow over time, so there will be a `sensor-2`, `sensor-3`, etc. 
Let's create a {rollup-job} that stores its data in `sensor_rollup`:

[source,console]
--------------------------------------------------
PUT _rollup/job/sensor
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": {
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [
    {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}
--------------------------------------------------
// TEST[setup:sensor_index]

If at a later date, we'd like to determine what jobs and capabilities were
stored in the `sensor_rollup` index, we can use the get rollup index API:

[source,console]
--------------------------------------------------
GET /sensor_rollup/_rollup/data
--------------------------------------------------
// TEST[continued]

Note how we are requesting the concrete rollup index name (`sensor_rollup`) as
the first part of the URL. This  will yield the following response:

[source,console-result]
----
{
  "sensor_rollup" : {
    "rollup_jobs" : [
      {
        "job_id" : "sensor",
        "rollup_index" : "sensor_rollup",
        "index_pattern" : "sensor-*",
        "fields" : {
          "node" : [
            {
              "agg" : "terms"
            }
          ],
          "temperature" : [
            {
              "agg" : "min"
            },
            {
              "agg" : "max"
            },
            {
              "agg" : "sum"
            }
          ],
          "timestamp" : [
            {
              "agg" : "date_histogram",
              "time_zone" : "UTC",
              "fixed_interval" : "1h",
              "delay": "7d"
            }
          ],
          "voltage" : [
            {
              "agg" : "avg"
            }
          ]
        }
      }
    ]
  }
}
----


The response that is returned contains information that is similar to the
original rollup configuration, but formatted differently. First, there are some
house-keeping details: the {rollup-job} ID, the index that holds the rolled data,
the index pattern that the job was targeting.

Next it shows a list of fields that contain data eligible for rollup searches. 
Here we see four fields: `node`, `temperature`, `timestamp` and `voltage`. Each
of these fields list the aggregations that are possible. For example, you can
use a min, max, or sum aggregation on the `temperature` field, but only a
`date_histogram` on `timestamp`.

Note that the `rollup_jobs` element is an array; there can be multiple,
independent jobs configured for a single index or index pattern. Each of these
jobs may have different configurations, so the API returns a list of all the
various configurations available.

Like other APIs that interact with indices, you can specify index patterns
instead of explicit indices:

[source,console]
--------------------------------------------------
GET /*_rollup/_rollup/data
--------------------------------------------------
// TEST[continued]