Get rollup index capabilities API

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

This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.

Request

GET <target>/_rollup/data

Prerequisites

  • If the Elasticsearch 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.

Description

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?

Path parameters

<target>

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

Examples

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:

  1. PUT _rollup/job/sensor
  2. {
  3.   "index_pattern": "sensor-*",
  4.   "rollup_index": "sensor_rollup",
  5.   "cron": "*/30 * * * * ?",
  6.   "page_size": 1000,
  7.   "groups": {
  8.     "date_histogram": {
  9.       "field": "timestamp",
  10.       "fixed_interval": "1h",
  11.       "delay": "7d"
  12.     },
  13.     "terms": {
  14.       "fields": [ "node" ]
  15.     }
  16.   },
  17.   "metrics": [
  18.     {
  19.       "field": "temperature",
  20.       "metrics": [ "min", "max", "sum" ]
  21.     },
  22.     {
  23.       "field": "voltage",
  24.       "metrics": [ "avg" ]
  25.     }
  26.   ]
  27. }

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:

  1. GET /sensor_rollup/_rollup/data

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:

  1. {
  2.   "sensor_rollup" : {
  3.     "rollup_jobs" : [
  4.       {
  5.         "job_id" : "sensor",
  6.         "rollup_index" : "sensor_rollup",
  7.         "index_pattern" : "sensor-*",
  8.         "fields" : {
  9.           "node" : [
  10.             {
  11.               "agg" : "terms"
  12.             }
  13.           ],
  14.           "temperature" : [
  15.             {
  16.               "agg" : "min"
  17.             },
  18.             {
  19.               "agg" : "max"
  20.             },
  21.             {
  22.               "agg" : "sum"
  23.             }
  24.           ],
  25.           "timestamp" : [
  26.             {
  27.               "agg" : "date_histogram",
  28.               "time_zone" : "UTC",
  29.               "fixed_interval" : "1h",
  30.               "delay": "7d"
  31.             }
  32.           ],
  33.           "voltage" : [
  34.             {
  35.               "agg" : "avg"
  36.             }
  37.           ]
  38.         }
  39.       }
  40.     ]
  41.   }
  42. }

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:

  1. GET /*_rollup/_rollup/data