Add rollup API examples

lcawl · lcawl · commit 16997d70fb8b · 2025-01-06T23:29:57.000-08:00
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
@@ -475,12 +475,14 @@ reroute-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branc
 render-search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/render-search-template-api.html
 reset-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reset-transform.html
 restore-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-restore-snapshot.html
+rollup-agg-limitations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-agg-limitations.html
 rollup-delete-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-delete-job.html
 rollup-get-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-job.html
 rollup-get-rollup-caps,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-rollup-caps.html
 rollup-get-rollup-index-caps,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-rollup-index-caps.html
 rollup-put-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-put-job.html
 rollup-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-search.html
+rollup-search-limitations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-search-limitations.html
 rollup-start-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-start-job.html
 rollup-stop-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-stop-job.html
 routing,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing
diff --git a/specification/rollup/delete_job/DeleteRollupJobRequest.ts b/specification/rollup/delete_job/DeleteRollupJobRequest.ts
@@ -47,7 +47,9 @@ import { Id } from '@_types/common'
  * ```
  * @rest_spec_name rollup.delete_job
  * @availability stack since=6.3.0 stability=experimental
+ * @deprecated 8.11.0
  * @cluster_privileges manage_rollup
+ * @doc_id rollup-delete-job
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/rollup/delete_job/DeleteRollupJobResponseExample1.yaml b/specification/rollup/delete_job/DeleteRollupJobResponseExample1.yaml
@@ -0,0 +1,5 @@
+# summary:
+description: A successful response from `DELETE _rollup/job/sensor`.
+# type: response
+# response_code: ''
+value: "{\n  \"acknowledged\": true\n}"
diff --git a/specification/rollup/get_jobs/GetRollupJobRequest.ts b/specification/rollup/get_jobs/GetRollupJobRequest.ts
@@ -30,6 +30,8 @@ import { Id } from '@_types/common'
  * @rest_spec_name rollup.get_jobs
  * @availability stack since=6.3.0 stability=experimental
  * @cluster_privileges monitor_rollup
+ * @deprecated 8.11.0
+ * @doc_id rollup-get-job
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/rollup/get_jobs/GetRollupJobResponseExample1.yaml b/specification/rollup/get_jobs/GetRollupJobResponseExample1.yaml
@@ -0,0 +1,23 @@
+# summary:
+description: A successful response from `GET _rollup/job/sensor`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"jobs\": [\n    {\n      \"config\": {\n        \"id\": \"sensor\",\n\
+  \        \"index_pattern\": \"sensor-*\",\n        \"rollup_index\": \"sensor_rollup\"\
+  ,\n        \"cron\": \"*/30 * * * * ?\",\n        \"groups\": {\n          \"date_histogram\"\
+  : {\n            \"fixed_interval\": \"1h\",\n            \"delay\": \"7d\",\n \
+  \           \"field\": \"timestamp\",\n            \"time_zone\": \"UTC\"\n    \
+  \      },\n          \"terms\": {\n            \"fields\": [\n              \"node\"\
+  \n            ]\n          }\n        },\n        \"metrics\": [\n          {\n\
+  \            \"field\": \"temperature\",\n            \"metrics\": [\n         \
+  \     \"min\",\n              \"max\",\n              \"sum\"\n            ]\n \
+  \         },\n          {\n            \"field\": \"voltage\",\n            \"metrics\"\
+  : [\n              \"avg\"\n            ]\n          }\n        ],\n        \"timeout\"\
+  : \"20s\",\n        \"page_size\": 1000\n      },\n      \"status\": {\n       \
+  \ \"job_state\": \"stopped\"\n      },\n      \"stats\": {\n        \"pages_processed\"\
+  : 0,\n        \"documents_processed\": 0,\n        \"rollups_indexed\": 0,\n   \
+  \     \"trigger_count\": 0,\n        \"index_failures\": 0,\n        \"index_time_in_ms\"\
+  : 0,\n        \"index_total\": 0,\n        \"search_failures\": 0,\n        \"search_time_in_ms\"\
+  : 0,\n        \"search_total\": 0,\n        \"processing_time_in_ms\": 0,\n    \
+  \    \"processing_total\": 0\n      }\n    }\n  ]\n}"
diff --git a/specification/rollup/get_jobs/types.ts b/specification/rollup/get_jobs/types.ts
@@ -26,8 +26,19 @@ import { long } from '@_types/Numeric'
 import { Duration, DurationValue, UnitMillis } from '@_types/Time'
 
 export class RollupJob {
+  /**
+   * The rollup job configuration.
+   */
   config: RollupJobConfiguration
+  /**
+   * Transient statistics about the rollup job, such as how many documents have been processed and how many rollup summary docs have been indexed.
+   * These stats are not persisted.
+   * If a node is restarted, these stats are reset.
+   */
   stats: RollupJobStats
+  /**
+   * The current status of the indexer for the rollup job.
+   */
   status: RollupJobStatus
 }
 
diff --git a/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts b/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts
@@ -33,6 +33,8 @@ import { Id } from '@_types/common'
  * @rest_spec_name rollup.get_rollup_caps
  * @availability stack since=6.3.0 stability=experimental
  * @cluster_privileges monitor_rollup
+ * @deprecated 8.11.0
+ * @doc_id rollup-get-rollup-caps
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/rollup/get_rollup_caps/GetRollupCapabilitiesResponseExample1.yaml b/specification/rollup/get_rollup_caps/GetRollupCapabilitiesResponseExample1.yaml
@@ -0,0 +1,21 @@
+# summary:
+description: >
+  A successful response from `GET _rollup/data/sensor-*` for a rollup job that targets the index pattern `sensor-*`.
+  The response contains the rollup job ID, the index that holds the rolled data, and the index pattern that the job was targeting.
+  It also shows a list of fields that contain data eligible for rollup searches.
+  For example, you can use a `min`, `max`, or `sum` aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"sensor-*\" : {\n    \"rollup_jobs\" : [\n      {\n        \"job_id\"\
+  \ : \"sensor\",\n        \"rollup_index\" : \"sensor_rollup\",\n        \"index_pattern\"\
+  \ : \"sensor-*\",\n        \"fields\" : {\n          \"node\" : [\n            {\n\
+  \              \"agg\" : \"terms\"\n            }\n          ],\n          \"temperature\"\
+  \ : [\n            {\n              \"agg\" : \"min\"\n            },\n        \
+  \    {\n              \"agg\" : \"max\"\n            },\n            {\n       \
+  \       \"agg\" : \"sum\"\n            }\n          ],\n          \"timestamp\"\
+  \ : [\n            {\n              \"agg\" : \"date_histogram\",\n            \
+  \  \"time_zone\" : \"UTC\",\n              \"fixed_interval\" : \"1h\",\n      \
+  \        \"delay\": \"7d\"\n            }\n          ],\n          \"voltage\" :\
+  \ [\n            {\n              \"agg\" : \"avg\"\n            }\n          ]\n\
+  \        }\n      }\n    ]\n  }\n}"
diff --git a/specification/rollup/get_rollup_caps/types.ts b/specification/rollup/get_rollup_caps/types.ts
@@ -22,6 +22,9 @@ import { Field } from '@_types/common'
 import { Duration, TimeZone } from '@_types/Time'
 
 export class RollupCapabilities {
+  /**
+   * 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.
+   */
   rollup_jobs: RollupCapabilitySummary[]
 }
 
diff --git a/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts b/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts
@@ -30,6 +30,8 @@ import { Ids } from '@_types/common'
  * @rest_spec_name rollup.get_rollup_index_caps
  * @availability stack since=6.4.0 stability=experimental
  * @index_privileges read
+ * @deprecated 8.11.0
+ * @doc_id rollup-get-rollup-index-caps
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesResponseExample1.yaml b/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesResponseExample1.yaml
@@ -0,0 +1,21 @@
+# summary:
+description: >
+  A successful response from `GET /sensor_rollup/_rollup/data`.
+  The response contains the rollup job ID, the index that holds the rolled data, and the index pattern that the job was targeting.
+  It also shows a list of fields that contain data eligible for rollup searches.
+  For example, you can use a `min`, `max`, or `sum` aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"sensor_rollup\" : {\n    \"rollup_jobs\" : [\n      {\n        \"job_id\"\
+  \ : \"sensor\",\n        \"rollup_index\" : \"sensor_rollup\",\n        \"index_pattern\"\
+  \ : \"sensor-*\",\n        \"fields\" : {\n          \"node\" : [\n            {\n\
+  \              \"agg\" : \"terms\"\n            }\n          ],\n          \"temperature\"\
+  \ : [\n            {\n              \"agg\" : \"min\"\n            },\n        \
+  \    {\n              \"agg\" : \"max\"\n            },\n            {\n       \
+  \       \"agg\" : \"sum\"\n            }\n          ],\n          \"timestamp\"\
+  \ : [\n            {\n              \"agg\" : \"date_histogram\",\n            \
+  \  \"time_zone\" : \"UTC\",\n              \"fixed_interval\" : \"1h\",\n      \
+  \        \"delay\": \"7d\"\n            }\n          ],\n          \"voltage\" :\
+  \ [\n            {\n              \"agg\" : \"avg\"\n            }\n          ]\n\
+  \        }\n      }\n    ]\n  }\n}"
diff --git a/specification/rollup/put_job/CreateRollupJobRequest.ts b/specification/rollup/put_job/CreateRollupJobRequest.ts
@@ -37,6 +37,8 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name rollup.put_job
  * @availability stack since=6.3.0 stability=experimental
  * @cluster_privileges manage, manage_rollup
+ * @deprecated 8.11.0
+ * @doc_id rollup-put-job
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/rollup/put_job/CreateRollupJobRequestExample1.yaml b/specification/rollup/put_job/CreateRollupJobRequestExample1.yaml
@@ -0,0 +1,17 @@
+# summary:
+# method_request: PUT _rollup/job/sensor
+description: >
+  Run `PUT _rollup/job/sensor` to create a rollup job that targets the `sensor-*` index pattern.
+  This configuration enables date histograms to be used on the `timestamp` field and terms aggregations to be used on the `node` field.
+  This configuration defines metrics over two fields: `temperature` and `voltage`.
+  For the `temperature` field, it collects the `min`, `max`, and `sum` of the temperature.
+  For `voltage`, it collects the `average`.
+# type: request
+value:
+  "{\n  \"index_pattern\": \"sensor-*\",\n  \"rollup_index\": \"sensor_rollup\"\
+  ,\n  \"cron\": \"*/30 * * * * ?\",\n  \"page_size\": 1000,\n  \"groups\": {\n  \
+  \  \"date_histogram\": {\n      \"field\": \"timestamp\",\n      \"fixed_interval\"\
+  : \"1h\",\n      \"delay\": \"7d\"\n    },\n    \"terms\": {\n      \"fields\":\
+  \ [ \"node\" ]\n    }\n  },\n  \"metrics\": [\n      {\n      \"field\": \"temperature\"\
+  ,\n      \"metrics\": [ \"min\", \"max\", \"sum\" ]\n    },\n    {\n      \"field\"\
+  : \"voltage\",\n      \"metrics\": [ \"avg\" ]\n    }\n  ]\n}"
diff --git a/specification/rollup/put_job/CreateRollupJobResponseExample1.yaml b/specification/rollup/put_job/CreateRollupJobResponseExample1.yaml
@@ -0,0 +1,5 @@
+# summary:
+# description: ''
+# type: response
+# response_code: ''
+value: "{\n  \"acknowledged\": true\n}"
diff --git a/specification/rollup/rollup_search/RollupSearchRequest.ts b/specification/rollup/rollup_search/RollupSearchRequest.ts
@@ -28,13 +28,54 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
  * Search rolled-up data.
  * The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.
  * It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given the original query.
+ *
+ * The request body supports a subset of features from the regular search API.
+ * The following functionality is not available:
+ *
+ * `size`: Because rollups work on pre-aggregated data, no search hits can be returned and so size must be set to zero or omitted entirely.
+ * `highlighter`, `suggestors`, `post_filter`, `profile`, `explain`: These are similarly disallowed.
+ *
+ * **Searching both historical rollup and non-rollup data**
+ *
+ * The rollup search API has the capability to search across both "live" non-rollup data and the aggregated rollup data.
+ * This is done by simply adding the live indices to the URI. For example:
+ *
+ * ```
+ * GET sensor-1,sensor_rollup/_rollup_search
+ * {
+ *   "size": 0,
+ *   "aggregations": {
+ *      "max_temperature": {
+ *       "max": {
+ *         "field": "temperature"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The rollup search endpoint does two things when the search runs:
+ *
+ * * The original request is sent to the non-rollup index unaltered.
+ * * A rewritten version of the original request is sent to the rollup index.
+ *
+ * When the two responses are received, the endpoint rewrites the rollup response and merges the two together.
+ * During the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.
  * @rest_spec_name rollup.rollup_search
  * @availability stack since=6.3.0 stability=experimental
+ * @deprecated 8.11.0
+ * @doc_id rollup-search
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Enables searching rolled-up data using the standard Query DSL.
+     * A comma-separated list of data streams and indices used to limit the request.
+     * This parameter has the following rules:
+     *
+     * * At least one data stream, index, or wildcard expression must be specified. This target can include a rollup or non-rollup index. For data streams, the stream's backing indices can only serve as non-rollup indices. Omitting the parameter or using `_all` are not permitted.
+     * * Multiple non-rollup indices may be specified.
+     * * Only one rollup index may be specified. If more than one are supplied, an exception occurs.
+     * * Wildcard expressions (`*`) may be used. If they match more than one rollup index, an exception occurs. However, you can use an expression to match multiple non-rollup indices or data streams.
      */
     index: Indices
   }
@@ -45,10 +86,13 @@ export interface Request extends RequestBase {
   body: {
     /**
      * Specifies aggregations.
-     * @aliases aggs */
+     * @aliases aggs
+     * @ext_doc_id rollup-agg-limitations
+     */
     aggregations?: Dictionary<string, AggregationContainer>
     /**
-     * Specifies a DSL query.
+     * Specifies a DSL query that is subject to some limitations.
+     * @ext_doc_id rollup-search-limitations
      */
     query?: QueryContainer
     /**
diff --git a/specification/rollup/rollup_search/RollupSearchRequestExample1.yaml b/specification/rollup/rollup_search/RollupSearchRequestExample1.yaml
@@ -0,0 +1,7 @@
+# summary:
+# method_request: GET /sensor_rollup/_rollup_search
+description: Search rolled up data stored in `sensor_rollup` with `GET /sensor_rollup/_rollup_search`
+# type: request
+value:
+  "{\n  \"size\": 0,\n  \"aggregations\": {\n    \"max_temperature\": {\n   \
+  \   \"max\": {\n        \"field\": \"temperature\"\n      }\n    }\n  }\n}"
diff --git a/specification/rollup/rollup_search/RollupSearchResponseExample1.yaml b/specification/rollup/rollup_search/RollupSearchResponseExample1.yaml
@@ -0,0 +1,12 @@
+# summary:
+description: >
+  An abbreviated response from `GET /sensor_rollup/_rollup_search` with a `max` aggregation on a `temperature` field.
+  The response provides some metadata about the request (`took`, `_shards`), the search hits (which is always empty for rollup searches), and the aggregation response.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"took\" : 102,\n  \"timed_out\" : false,\n  \"terminated_early\" : false,\n\
+  \  \"_shards\" : {} ,\n  \"hits\" : {\n    \"total\" : {\n        \"value\": 0,\n\
+  \        \"relation\": \"eq\"\n    },\n    \"max_score\" : 0.0,\n    \"hits\" :\
+  \ [ ]\n  },\n  \"aggregations\" : {\n    \"max_temperature\" : {\n      \"value\"\
+  \ : 202.0\n    }\n  }\n}"
diff --git a/specification/rollup/start_job/StartRollupJobRequest.ts b/specification/rollup/start_job/StartRollupJobRequest.ts
@@ -27,6 +27,8 @@ import { Id } from '@_types/common'
  * @rest_spec_name rollup.start_job
  * @availability stack since=6.3.0 stability=experimental
  * @cluster_privileges manage_rollup
+ * @deprecated 8.11.0
+ * @doc_id rollup-start-job
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/rollup/start_job/StartRollupJobResponseExample1.yaml b/specification/rollup/start_job/StartRollupJobResponseExample1.yaml
@@ -0,0 +1,5 @@
+# summary:
+description: A successful response from `POST _rollup/job/sensor/_start`.
+# type: response
+# response_code: ''
+value: "{\n  \"started\": true\n}"
diff --git a/specification/rollup/stop_job/StopRollupJobRequest.ts b/specification/rollup/stop_job/StopRollupJobRequest.ts
@@ -25,9 +25,21 @@ import { Duration } from '@_types/Time'
  * Stop rollup jobs.
  * If you try to stop a job that does not exist, an exception occurs.
  * If you try to stop a job that is already stopped, nothing happens.
+ *
+ * Since only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped.
+ * This is accomplished with the `wait_for_completion` query parameter, and optionally a timeout. For example:
+ *
+ * ```
+ * POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s
+ * ```
+ * The parameter blocks the API call from returning until either the job has moved to STOPPED or the specified time has elapsed.
+ * If the specified time elapses without the job moving to STOPPED, a timeout exception occurs.
  * @rest_spec_name rollup.stop_job
  * @availability stack since=6.3.0 stability=experimental
  * @cluster_privileges manage_rollup
+ * @deprecated 8.11.0
+ * @doc_id rollup-stop-job
+ *
  */
 export interface Request extends RequestBase {
   path_parts: {
@@ -40,6 +52,8 @@ export interface Request extends RequestBase {
     /**
      * If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop.
      * If more than `timeout` time has passed, the API throws a timeout exception.
+     * NOTE: Even if a timeout occurs, the stop request is still processing and eventually moves the job to STOPPED.
+     * The timeout simply means the API call itself timed out while waiting for the status change.
      * @server_default 30s
      */
     timeout?: Duration

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,9 @@ import { Field } from '@_types/common'`
`22`	`22`	`import { Duration, TimeZone } from '@_types/Time'`
`23`	`23`
`24`	`24`	`export class RollupCapabilities {`
	`25`	`+ /**`
	`26`	`+ * 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.`
	`27`	`+ */`
`25`	`28`	`rollup_jobs: RollupCapabilitySummary[]`
`26`	`29`	`}`
`27`	`30`