From 4b6284fd610d7ee408c514ac463a358036553214 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 8 Jan 2025 10:14:57 -0800 Subject: [PATCH] Add rollup API examples (#3455) (cherry picked from commit 2390b022f2701a765ca957fb37f108be525a19c8) --- output/openapi/elasticsearch-openapi.json | 25 ++- output/schema/schema.json | 142 ++++++++++++++---- specification/_doc_ids/table.csv | 2 + .../delete_job/DeleteRollupJobRequest.ts | 2 + .../DeleteRollupJobResponseExample1.yaml | 5 + .../rollup/get_jobs/GetRollupJobRequest.ts | 2 + .../GetRollupJobResponseExample1.yaml | 23 +++ specification/rollup/get_jobs/types.ts | 11 ++ .../GetRollupCapabilitiesRequest.ts | 2 + ...GetRollupCapabilitiesResponseExample1.yaml | 21 +++ specification/rollup/get_rollup_caps/types.ts | 3 + .../GetRollupIndexCapabilitiesRequest.ts | 2 + ...llupIndexCapabilitiesResponseExample1.yaml | 21 +++ .../rollup/put_job/CreateRollupJobRequest.ts | 2 + .../CreateRollupJobRequestExample1.yaml | 17 +++ .../CreateRollupJobResponseExample1.yaml | 5 + .../rollup_search/RollupSearchRequest.ts | 50 +++++- .../request/RollupSearchRequestExample1.yaml | 7 + .../RollupSearchResponseExample1.yaml | 12 ++ .../rollup/start_job/StartRollupJobRequest.ts | 2 + .../StartRollupJobResponseExample1.yaml | 5 + .../rollup/stop_job/StopRollupJobRequest.ts | 14 ++ 22 files changed, 336 insertions(+), 39 deletions(-) create mode 100644 specification/rollup/delete_job/examples/response/DeleteRollupJobResponseExample1.yaml create mode 100644 specification/rollup/get_jobs/examples/response/GetRollupJobResponseExample1.yaml create mode 100644 specification/rollup/get_rollup_caps/examples/response/GetRollupCapabilitiesResponseExample1.yaml create mode 100644 specification/rollup/get_rollup_index_caps/examples/response/GetRollupIndexCapabilitiesResponseExample1.yaml create mode 100644 specification/rollup/put_job/examples/request/CreateRollupJobRequestExample1.yaml create mode 100644 specification/rollup/put_job/examples/response/CreateRollupJobResponseExample1.yaml create mode 100644 specification/rollup/rollup_search/examples/request/RollupSearchRequestExample1.yaml create mode 100644 specification/rollup/rollup_search/examples/response/RollupSearchResponseExample1.yaml create mode 100644 specification/rollup/start_job/examples/response/StartRollupJobResponseExample1.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index f46241fee5..e022d7ead7 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -25982,6 +25982,7 @@ "$ref": "#/components/responses/rollup.get_jobs#200" } }, + "deprecated": true, "x-state": "Technical preview" }, "put": { @@ -26066,6 +26067,7 @@ } } }, + "deprecated": true, "x-state": "Technical preview" }, "delete": { @@ -26114,6 +26116,7 @@ } } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26130,6 +26133,7 @@ "$ref": "#/components/responses/rollup.get_jobs#200" } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26151,6 +26155,7 @@ "$ref": "#/components/responses/rollup.get_rollup_caps#200" } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26167,6 +26172,7 @@ "$ref": "#/components/responses/rollup.get_rollup_caps#200" } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26206,6 +26212,7 @@ } } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26215,7 +26222,7 @@ "rollup" ], "summary": "Search rolled-up data", - "description": "The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.", + "description": "The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.\n\nThe request body supports a subset of features from the regular search API.\nThe following functionality is not available:\n\n`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.\n`highlighter`, `suggestors`, `post_filter`, `profile`, `explain`: These are similarly disallowed.\n\n**Searching both historical rollup and non-rollup data**\n\nThe rollup search API has the capability to search across both \"live\" non-rollup data and the aggregated rollup data.\nThis is done by simply adding the live indices to the URI. For example:\n\n```\nGET sensor-1,sensor_rollup/_rollup_search\n{\n \"size\": 0,\n \"aggregations\": {\n \"max_temperature\": {\n \"max\": {\n \"field\": \"temperature\"\n }\n }\n }\n}\n```\n\nThe rollup search endpoint does two things when the search runs:\n\n* The original request is sent to the non-rollup index unaltered.\n* A rewritten version of the original request is sent to the rollup index.\n\nWhen the two responses are received, the endpoint rewrites the rollup response and merges the two together.\nDuring the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.", "operationId": "rollup-rollup-search", "parameters": [ { @@ -26236,6 +26243,7 @@ "$ref": "#/components/responses/rollup.rollup_search#200" } }, + "deprecated": true, "x-state": "Technical preview" }, "post": { @@ -26243,7 +26251,7 @@ "rollup" ], "summary": "Search rolled-up data", - "description": "The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.", + "description": "The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.\n\nThe request body supports a subset of features from the regular search API.\nThe following functionality is not available:\n\n`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.\n`highlighter`, `suggestors`, `post_filter`, `profile`, `explain`: These are similarly disallowed.\n\n**Searching both historical rollup and non-rollup data**\n\nThe rollup search API has the capability to search across both \"live\" non-rollup data and the aggregated rollup data.\nThis is done by simply adding the live indices to the URI. For example:\n\n```\nGET sensor-1,sensor_rollup/_rollup_search\n{\n \"size\": 0,\n \"aggregations\": {\n \"max_temperature\": {\n \"max\": {\n \"field\": \"temperature\"\n }\n }\n }\n}\n```\n\nThe rollup search endpoint does two things when the search runs:\n\n* The original request is sent to the non-rollup index unaltered.\n* A rewritten version of the original request is sent to the rollup index.\n\nWhen the two responses are received, the endpoint rewrites the rollup response and merges the two together.\nDuring the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.", "operationId": "rollup-rollup-search-1", "parameters": [ { @@ -26264,6 +26272,7 @@ "$ref": "#/components/responses/rollup.rollup_search#200" } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26308,6 +26317,7 @@ } } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -26317,7 +26327,7 @@ "rollup" ], "summary": "Stop rollup jobs", - "description": "If you try to stop a job that does not exist, an exception occurs.\nIf you try to stop a job that is already stopped, nothing happens.", + "description": "If you try to stop a job that does not exist, an exception occurs.\nIf you try to stop a job that is already stopped, nothing happens.\n\nSince only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped.\nThis is accomplished with the `wait_for_completion` query parameter, and optionally a timeout. For example:\n\n```\nPOST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s\n```\nThe parameter blocks the API call from returning until either the job has moved to STOPPED or the specified time has elapsed.\nIf the specified time elapses without the job moving to STOPPED, a timeout exception occurs.", "operationId": "rollup-stop-job", "parameters": [ { @@ -26334,7 +26344,7 @@ { "in": "query", "name": "timeout", - "description": "If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop.\nIf more than `timeout` time has passed, the API throws a timeout exception.", + "description": "If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop.\nIf more than `timeout` time has passed, the API throws a timeout exception.\nNOTE: Even if a timeout occurs, the stop request is still processing and eventually moves the job to STOPPED.\nThe timeout simply means the API call itself timed out while waiting for the status change.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -26372,6 +26382,7 @@ } } }, + "deprecated": true, "x-state": "Technical preview" } }, @@ -83595,6 +83606,7 @@ "type": "object", "properties": { "rollup_jobs": { + "description": "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.", "type": "array", "items": { "$ref": "#/components/schemas/rollup.get_rollup_caps:RollupCapabilitySummary" @@ -102705,7 +102717,7 @@ "rollup.rollup_search#index": { "in": "path", "name": "index", - "description": "Enables searching rolled-up data using the standard Query DSL.", + "description": "A comma-separated list of data streams and indices used to limit the request.\nThis parameter has the following rules:\n\n* 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.\n* Multiple non-rollup indices may be specified.\n* Only one rollup index may be specified. If more than one are supplied, an exception occurs.\n* 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.", "required": true, "deprecated": false, "schema": { @@ -106652,6 +106664,9 @@ "type": "object", "properties": { "aggregations": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/rollup-agg-limitations.html" + }, "description": "Specifies aggregations.", "type": "object", "additionalProperties": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 8e236a902f..9fec766617 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -14535,8 +14535,13 @@ "stability": "experimental" } }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Delete a rollup job.\n\nA job must be stopped before it can be deleted.\nIf you attempt to delete a started job, an error occurs.\nSimilarly, if you attempt to delete a nonexistent job, an exception occurs.\n\nIMPORTANT: When you delete a job, you remove only the process that is actively monitoring and rolling up data.\nThe API does not delete any previously rolled up data.\nThis is by design; a user may wish to roll up a static data set.\nBecause the data set is static, after it has been fully rolled up there is no need to keep the indexing rollup job around (as there will be no new data).\nThus the job can be deleted, leaving behind the rolled up data for analysis.\nIf you wish to also remove the rollup data and the rollup index contains the data for only a single job, you can delete the whole rollup index.\nIf the rollup index stores data from several jobs, you must issue a delete-by-query that targets the rollup job's identifier in the rollup index. For example:\n\n```\nPOST my_rollup_index/_delete_by_query\n{\n \"query\": {\n \"term\": {\n \"_rollup.id\": \"the_rollup_job_id\"\n }\n }\n}\n```", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-delete-job.html", + "docId": "rollup-delete-job", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-delete-job.html", "name": "rollup.delete_job", "privileges": { "cluster": [ @@ -14571,8 +14576,13 @@ "stability": "experimental" } }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Get rollup job information.\nGet the configuration, stats, and status of rollup jobs.\n\nNOTE: This API returns only active (both `STARTED` and `STOPPED`) jobs.\nIf a job was created, ran for a while, then was deleted, the API does not return any details about it.\nFor details about a historical rollup job, the rollup capabilities API may be more useful.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-get-job.html", + "docId": "rollup-get-job", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-job.html", "name": "rollup.get_jobs", "privileges": { "cluster": [ @@ -14613,8 +14623,13 @@ "stability": "experimental" } }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Get the rollup job capabilities.\nGet the capabilities of any rollup jobs that have been configured for a specific index or index pattern.\n\nThis API is useful because a rollup job is often configured to rollup only a subset of fields from the source index.\nFurthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration.\nThis API enables you to inspect an index and determine:\n\n1. Does this index have associated rollup data somewhere in the cluster?\n2. If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live?", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-get-rollup-caps.html", + "docId": "rollup-get-rollup-caps", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-rollup-caps.html", "name": "rollup.get_rollup_caps", "privileges": { "cluster": [ @@ -14655,8 +14670,13 @@ "stability": "experimental" } }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Get the rollup index capabilities.\nGet the rollup capabilities of all jobs inside of a rollup index.\nA single rollup index may store the data for multiple rollup jobs and may have a variety of capabilities depending on those jobs. This API enables you to determine:\n\n* What jobs are stored in an index (or indices specified via a pattern)?\n* What target indices were rolled up, what fields were used in those rollups, and what aggregations can be performed on each job?", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-get-rollup-index-caps.html", + "docId": "rollup-get-rollup-index-caps", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-rollup-index-caps.html", "name": "rollup.get_rollup_index_caps", "privileges": { "index": [ @@ -14691,8 +14711,13 @@ "stability": "experimental" } }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Create a rollup job.\n\nWARNING: From 8.15.0, calling this API in a cluster with no rollup usage will fail with a message about the deprecation and planned removal of rollup features. A cluster needs to contain either a rollup job or a rollup index in order for this API to be allowed to run.\n\nThe rollup job configuration contains all the details about how the job should run, when it indexes documents, and what future queries will be able to run against the rollup index.\n\nThere are three main sections to the job configuration: the logistical details about the job (for example, the cron schedule), the fields that are used for grouping, and what metrics to collect for each group.\n\nJobs are created in a `STOPPED` state. You can start them with the start rollup jobs API.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-put-job.html", + "docId": "rollup-put-job", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-put-job.html", "name": "rollup.put_job", "privileges": { "cluster": [ @@ -14731,8 +14756,13 @@ "stability": "experimental" } }, - "description": "Search rolled-up data.\nThe rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-search.html", + "deprecation": { + "description": "", + "version": "8.11.0" + }, + "description": "Search rolled-up data.\nThe rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.\n\nThe request body supports a subset of features from the regular search API.\nThe following functionality is not available:\n\n`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.\n`highlighter`, `suggestors`, `post_filter`, `profile`, `explain`: These are similarly disallowed.\n\n**Searching both historical rollup and non-rollup data**\n\nThe rollup search API has the capability to search across both \"live\" non-rollup data and the aggregated rollup data.\nThis is done by simply adding the live indices to the URI. For example:\n\n```\nGET sensor-1,sensor_rollup/_rollup_search\n{\n \"size\": 0,\n \"aggregations\": {\n \"max_temperature\": {\n \"max\": {\n \"field\": \"temperature\"\n }\n }\n }\n}\n```\n\nThe rollup search endpoint does two things when the search runs:\n\n* The original request is sent to the non-rollup index unaltered.\n* A rewritten version of the original request is sent to the rollup index.\n\nWhen the two responses are received, the endpoint rewrites the rollup response and merges the two together.\nDuring the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.", + "docId": "rollup-search", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-search.html", "name": "rollup.rollup_search", "request": { "name": "Request", @@ -14766,8 +14796,13 @@ "stability": "experimental" } }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Start rollup jobs.\nIf you try to start a job that does not exist, an exception occurs.\nIf you try to start a job that is already started, nothing happens.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-start-job.html", + "docId": "rollup-start-job", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-start-job.html", "name": "rollup.start_job", "privileges": { "cluster": [ @@ -14802,8 +14837,13 @@ "stability": "experimental" } }, - "description": "Stop rollup jobs.\nIf you try to stop a job that does not exist, an exception occurs.\nIf you try to stop a job that is already stopped, nothing happens.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-stop-job.html", + "deprecation": { + "description": "", + "version": "8.11.0" + }, + "description": "Stop rollup jobs.\nIf you try to stop a job that does not exist, an exception occurs.\nIf you try to stop a job that is already stopped, nothing happens.\n\nSince only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped.\nThis is accomplished with the `wait_for_completion` query parameter, and optionally a timeout. For example:\n\n```\nPOST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s\n```\nThe parameter blocks the API call from returning until either the job has moved to STOPPED or the specified time has elapsed.\nIf the specified time elapses without the job moving to STOPPED, a timeout exception occurs.", + "docId": "rollup-stop-job", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-stop-job.html", "name": "rollup.stop_job", "privileges": { "cluster": [ @@ -187438,6 +187478,10 @@ "body": { "kind": "no_body" }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Delete a rollup job.\n\nA job must be stopped before it can be deleted.\nIf you attempt to delete a started job, an error occurs.\nSimilarly, if you attempt to delete a nonexistent job, an exception occurs.\n\nIMPORTANT: When you delete a job, you remove only the process that is actively monitoring and rolling up data.\nThe API does not delete any previously rolled up data.\nThis is by design; a user may wish to roll up a static data set.\nBecause the data set is static, after it has been fully rolled up there is no need to keep the indexing rollup job around (as there will be no new data).\nThus the job can be deleted, leaving behind the rolled up data for analysis.\nIf you wish to also remove the rollup data and the rollup index contains the data for only a single job, you can delete the whole rollup index.\nIf the rollup index stores data from several jobs, you must issue a delete-by-query that targets the rollup job's identifier in the rollup index. For example:\n\n```\nPOST my_rollup_index/_delete_by_query\n{\n \"query\": {\n \"term\": {\n \"_rollup.id\": \"the_rollup_job_id\"\n }\n }\n}\n```", "inherits": { "type": { @@ -187464,7 +187508,7 @@ } ], "query": [], - "specLocation": "rollup/delete_job/DeleteRollupJobRequest.ts#L23-L59" + "specLocation": "rollup/delete_job/DeleteRollupJobRequest.ts#L23-L61" }, { "kind": "response", @@ -187527,7 +187571,7 @@ "name": "IndexingJobState", "namespace": "rollup.get_jobs" }, - "specLocation": "rollup/get_jobs/types.ts#L66-L72" + "specLocation": "rollup/get_jobs/types.ts#L77-L83" }, { "kind": "request", @@ -187537,6 +187581,10 @@ "body": { "kind": "no_body" }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Get rollup job information.\nGet the configuration, stats, and status of rollup jobs.\n\nNOTE: This API returns only active (both `STARTED` and `STOPPED`) jobs.\nIf a job was created, ran for a while, then was deleted, the API does not return any details about it.\nFor details about a historical rollup job, the rollup capabilities API may be more useful.", "inherits": { "type": { @@ -187563,7 +187611,7 @@ } ], "query": [], - "specLocation": "rollup/get_jobs/GetRollupJobRequest.ts#L23-L42" + "specLocation": "rollup/get_jobs/GetRollupJobRequest.ts#L23-L44" }, { "kind": "response", @@ -187600,6 +187648,7 @@ }, "properties": [ { + "description": "The rollup job configuration.", "name": "config", "required": true, "type": { @@ -187611,6 +187660,7 @@ } }, { + "description": "Transient statistics about the rollup job, such as how many documents have been processed and how many rollup summary docs have been indexed.\nThese stats are not persisted.\nIf a node is restarted, these stats are reset.", "name": "stats", "required": true, "type": { @@ -187622,6 +187672,7 @@ } }, { + "description": "The current status of the indexer for the rollup job.", "name": "status", "required": true, "type": { @@ -187633,7 +187684,7 @@ } } ], - "specLocation": "rollup/get_jobs/types.ts#L28-L32" + "specLocation": "rollup/get_jobs/types.ts#L28-L43" }, { "kind": "interface", @@ -187734,7 +187785,7 @@ } } ], - "specLocation": "rollup/get_jobs/types.ts#L34-L43" + "specLocation": "rollup/get_jobs/types.ts#L45-L54" }, { "kind": "interface", @@ -187903,7 +187954,7 @@ } } ], - "specLocation": "rollup/get_jobs/types.ts#L45-L58" + "specLocation": "rollup/get_jobs/types.ts#L56-L69" }, { "kind": "interface", @@ -187953,7 +188004,7 @@ } } ], - "specLocation": "rollup/get_jobs/types.ts#L60-L64" + "specLocation": "rollup/get_jobs/types.ts#L71-L75" }, { "kind": "request", @@ -187963,6 +188014,10 @@ "body": { "kind": "no_body" }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Get the rollup job capabilities.\nGet the capabilities of any rollup jobs that have been configured for a specific index or index pattern.\n\nThis API is useful because a rollup job is often configured to rollup only a subset of fields from the source index.\nFurthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration.\nThis API enables you to inspect an index and determine:\n\n1. Does this index have associated rollup data somewhere in the cluster?\n2. If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live?", "inherits": { "type": { @@ -187989,7 +188044,7 @@ } ], "query": [], - "specLocation": "rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts#L23-L45" + "specLocation": "rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts#L23-L47" }, { "kind": "response", @@ -188028,6 +188083,7 @@ }, "properties": [ { + "description": "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.", "name": "rollup_jobs", "required": true, "type": { @@ -188042,7 +188098,7 @@ } } ], - "specLocation": "rollup/get_rollup_caps/types.ts#L24-L26" + "specLocation": "rollup/get_rollup_caps/types.ts#L24-L29" }, { "kind": "interface", @@ -188110,7 +188166,7 @@ } } ], - "specLocation": "rollup/get_rollup_caps/types.ts#L28-L33" + "specLocation": "rollup/get_rollup_caps/types.ts#L31-L36" }, { "kind": "interface", @@ -188153,7 +188209,7 @@ } } ], - "specLocation": "rollup/get_rollup_caps/types.ts#L35-L39" + "specLocation": "rollup/get_rollup_caps/types.ts#L38-L42" }, { "kind": "interface", @@ -188187,6 +188243,10 @@ "body": { "kind": "no_body" }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Get the rollup index capabilities.\nGet the rollup capabilities of all jobs inside of a rollup index.\nA single rollup index may store the data for multiple rollup jobs and may have a variety of capabilities depending on those jobs. This API enables you to determine:\n\n* What jobs are stored in an index (or indices specified via a pattern)?\n* What target indices were rolled up, what fields were used in those rollups, and what aggregations can be performed on each job?", "inherits": { "type": { @@ -188213,7 +188273,7 @@ } ], "query": [], - "specLocation": "rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts#L23-L42" + "specLocation": "rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts#L23-L44" }, { "kind": "response", @@ -188464,6 +188524,10 @@ } ] }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Create a rollup job.\n\nWARNING: From 8.15.0, calling this API in a cluster with no rollup usage will fail with a message about the deprecation and planned removal of rollup features. A cluster needs to contain either a rollup job or a rollup index in order for this API to be allowed to run.\n\nThe rollup job configuration contains all the details about how the job should run, when it indexes documents, and what future queries will be able to run against the rollup index.\n\nThere are three main sections to the job configuration: the logistical details about the job (for example, the cron schedule), the fields that are used for grouping, and what metrics to collect for each group.\n\nJobs are created in a `STOPPED` state. You can start them with the start rollup jobs API.", "inherits": { "type": { @@ -188490,7 +188554,7 @@ } ], "query": [], - "specLocation": "rollup/put_job/CreateRollupJobRequest.ts#L27-L97" + "specLocation": "rollup/put_job/CreateRollupJobRequest.ts#L27-L99" }, { "kind": "response", @@ -188523,6 +188587,8 @@ "aggs" ], "description": "Specifies aggregations.", + "extDocId": "rollup-agg-limitations", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-agg-limitations.html", "name": "aggregations", "required": false, "type": { @@ -188545,7 +188611,9 @@ } }, { - "description": "Specifies a DSL query.", + "description": "Specifies a DSL query that is subject to some limitations.", + "extDocId": "rollup-search-limitations", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-search-limitations.html", "name": "query", "required": false, "type": { @@ -188570,7 +188638,11 @@ } ] }, - "description": "Search rolled-up data.\nThe rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.", + "deprecation": { + "description": "", + "version": "8.11.0" + }, + "description": "Search rolled-up data.\nThe rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data.\nIt 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.\n\nThe request body supports a subset of features from the regular search API.\nThe following functionality is not available:\n\n`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.\n`highlighter`, `suggestors`, `post_filter`, `profile`, `explain`: These are similarly disallowed.\n\n**Searching both historical rollup and non-rollup data**\n\nThe rollup search API has the capability to search across both \"live\" non-rollup data and the aggregated rollup data.\nThis is done by simply adding the live indices to the URI. For example:\n\n```\nGET sensor-1,sensor_rollup/_rollup_search\n{\n \"size\": 0,\n \"aggregations\": {\n \"max_temperature\": {\n \"max\": {\n \"field\": \"temperature\"\n }\n }\n }\n}\n```\n\nThe rollup search endpoint does two things when the search runs:\n\n* The original request is sent to the non-rollup index unaltered.\n* A rewritten version of the original request is sent to the rollup index.\n\nWhen the two responses are received, the endpoint rewrites the rollup response and merges the two together.\nDuring the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.", "inherits": { "type": { "name": "RequestBase", @@ -188583,7 +188655,7 @@ }, "path": [ { - "description": "Enables searching rolled-up data using the standard Query DSL.", + "description": "A comma-separated list of data streams and indices used to limit the request.\nThis parameter has the following rules:\n\n* 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.\n* Multiple non-rollup indices may be specified.\n* Only one rollup index may be specified. If more than one are supplied, an exception occurs.\n* 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.", "name": "index", "required": true, "type": { @@ -188621,7 +188693,7 @@ } } ], - "specLocation": "rollup/rollup_search/RollupSearchRequest.ts#L27-L59" + "specLocation": "rollup/rollup_search/RollupSearchRequest.ts#L27-L103" }, { "kind": "response", @@ -188736,6 +188808,10 @@ "body": { "kind": "no_body" }, + "deprecation": { + "description": "", + "version": "8.11.0" + }, "description": "Start rollup jobs.\nIf you try to start a job that does not exist, an exception occurs.\nIf you try to start a job that is already started, nothing happens.", "inherits": { "type": { @@ -188762,7 +188838,7 @@ } ], "query": [], - "specLocation": "rollup/start_job/StartRollupJobRequest.ts#L23-L38" + "specLocation": "rollup/start_job/StartRollupJobRequest.ts#L23-L40" }, { "kind": "response", @@ -188796,7 +188872,11 @@ "body": { "kind": "no_body" }, - "description": "Stop rollup jobs.\nIf you try to stop a job that does not exist, an exception occurs.\nIf you try to stop a job that is already stopped, nothing happens.", + "deprecation": { + "description": "", + "version": "8.11.0" + }, + "description": "Stop rollup jobs.\nIf you try to stop a job that does not exist, an exception occurs.\nIf you try to stop a job that is already stopped, nothing happens.\n\nSince only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped.\nThis is accomplished with the `wait_for_completion` query parameter, and optionally a timeout. For example:\n\n```\nPOST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s\n```\nThe parameter blocks the API call from returning until either the job has moved to STOPPED or the specified time has elapsed.\nIf the specified time elapses without the job moving to STOPPED, a timeout exception occurs.", "inherits": { "type": { "name": "RequestBase", @@ -188823,7 +188903,7 @@ ], "query": [ { - "description": "If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop.\nIf more than `timeout` time has passed, the API throws a timeout exception.", + "description": "If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop.\nIf more than `timeout` time has passed, the API throws a timeout exception.\nNOTE: Even if a timeout occurs, the stop request is still processing and eventually moves the job to STOPPED.\nThe timeout simply means the API call itself timed out while waiting for the status change.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -188849,7 +188929,7 @@ } } ], - "specLocation": "rollup/stop_job/StopRollupJobRequest.ts#L24-L53" + "specLocation": "rollup/stop_job/StopRollupJobRequest.ts#L24-L67" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 3dc01b9567..2dc98b5983 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -476,12 +476,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 index eef578b63d..ca4d5af84a 100644 --- 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/examples/response/DeleteRollupJobResponseExample1.yaml b/specification/rollup/delete_job/examples/response/DeleteRollupJobResponseExample1.yaml new file mode 100644 index 0000000000..9f0f6242f6 --- /dev/null +++ b/specification/rollup/delete_job/examples/response/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 index 6e69d18a09..0be2b0b156 100644 --- 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/examples/response/GetRollupJobResponseExample1.yaml b/specification/rollup/get_jobs/examples/response/GetRollupJobResponseExample1.yaml new file mode 100644 index 0000000000..fc41b704f4 --- /dev/null +++ b/specification/rollup/get_jobs/examples/response/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 index 405ba2b34e..e8d87f07ba 100644 --- 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 index d579f5ae9a..07c86b1052 100644 --- 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/examples/response/GetRollupCapabilitiesResponseExample1.yaml b/specification/rollup/get_rollup_caps/examples/response/GetRollupCapabilitiesResponseExample1.yaml new file mode 100644 index 0000000000..b9d56cf47c --- /dev/null +++ b/specification/rollup/get_rollup_caps/examples/response/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 index 45a867207b..0bbe82dd38 100644 --- 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 index 4ff08efcf4..c9c22dcead 100644 --- 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/examples/response/GetRollupIndexCapabilitiesResponseExample1.yaml b/specification/rollup/get_rollup_index_caps/examples/response/GetRollupIndexCapabilitiesResponseExample1.yaml new file mode 100644 index 0000000000..485eb10400 --- /dev/null +++ b/specification/rollup/get_rollup_index_caps/examples/response/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 index b16206b85d..664bebbc24 100644 --- 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/examples/request/CreateRollupJobRequestExample1.yaml b/specification/rollup/put_job/examples/request/CreateRollupJobRequestExample1.yaml new file mode 100644 index 0000000000..3d84f2cfbe --- /dev/null +++ b/specification/rollup/put_job/examples/request/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/examples/response/CreateRollupJobResponseExample1.yaml b/specification/rollup/put_job/examples/response/CreateRollupJobResponseExample1.yaml new file mode 100644 index 0000000000..d9d263c01f --- /dev/null +++ b/specification/rollup/put_job/examples/response/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 index 4261604f07..5b3cf3a177 100644 --- 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 /** - * 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/examples/request/RollupSearchRequestExample1.yaml b/specification/rollup/rollup_search/examples/request/RollupSearchRequestExample1.yaml new file mode 100644 index 0000000000..142d241aec --- /dev/null +++ b/specification/rollup/rollup_search/examples/request/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/examples/response/RollupSearchResponseExample1.yaml b/specification/rollup/rollup_search/examples/response/RollupSearchResponseExample1.yaml new file mode 100644 index 0000000000..cc8717ada1 --- /dev/null +++ b/specification/rollup/rollup_search/examples/response/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 index 229aa2a56f..8560e72ada 100644 --- 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/examples/response/StartRollupJobResponseExample1.yaml b/specification/rollup/start_job/examples/response/StartRollupJobResponseExample1.yaml new file mode 100644 index 0000000000..0c48123d6f --- /dev/null +++ b/specification/rollup/start_job/examples/response/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 index 88541dea0c..f51f8dd146 100644 --- 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