From 658677a2cc98e46a90d1fbbcec0011979a50bdf0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 28 Aug 2023 17:30:06 +0200 Subject: [PATCH] [DOCS] Adds description to rollup APIs. --- output/schema/schema.json | 67 ++++++++++++------- specification/_doc_ids/table.csv | 1 + specification/rollup/_types/Groupings.ts | 50 ++++++++++++++ .../delete_job/DeleteRollupJobRequest.ts | 4 ++ .../rollup/get_jobs/GetRollupJobRequest.ts | 5 ++ .../GetRollupCapabilitiesRequest.ts | 5 ++ .../GetRollupIndexCapabilitiesRequest.ts | 5 ++ .../rollup/put_job/CreateRollupJobRequest.ts | 1 + .../rollup_search/RollupSearchRequest.ts | 15 ++++- .../rollup/start_job/StartRollupJobRequest.ts | 4 ++ .../rollup/stop_job/StopRollupJobRequest.ts | 14 ++++ 11 files changed, 145 insertions(+), 26 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index 537a826efa..e70a11d4a4 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -165572,6 +165572,7 @@ }, "properties": [ { + "description": "How long to wait before rolling up new documents.\nBy default, the indexer attempts to roll up all data that is available.\nHowever, it is not uncommon for data to arrive out of order.\nThe indexer is unable to deal with data that arrives after a time-span has been rolled up.\nYou need to specify a delay that matches the longest period of time you expect out-of-order data to arrive.", "name": "delay", "required": false, "type": { @@ -165583,6 +165584,7 @@ } }, { + "description": "The date field that is to be rolled up.", "name": "field", "required": true, "type": { @@ -165616,6 +165618,9 @@ } }, { + "description": "The interval of time buckets to be generated when rolling up.", + "docId": "calendar-and-fixed-intervals", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-datehistogram-aggregation.html#calendar_and_fixed_intervals", "name": "calendar_interval", "required": false, "type": { @@ -165627,6 +165632,9 @@ } }, { + "description": "The interval of time buckets to be generated when rolling up.", + "docId": "calendar-and-fixed-intervals", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-datehistogram-aggregation.html#calendar_and_fixed_intervals", "name": "fixed_interval", "required": false, "type": { @@ -165638,6 +165646,7 @@ } }, { + "description": "Defines what `time_zone` the rollup documents are stored as.\nUnlike raw data, which can shift timezones on the fly, rolled documents have to be stored with a specific timezone.\nBy default, rollup documents are stored in `UTC`.", "name": "time_zone", "required": false, "type": { @@ -165649,7 +165658,7 @@ } } ], - "specLocation": "rollup/_types/Groupings.ts#L30-L38" + "specLocation": "rollup/_types/Groupings.ts#L42-L73" }, { "kind": "interface", @@ -165696,6 +165705,7 @@ }, "properties": [ { + "description": "A date histogram group aggregates a date field into time-based buckets.\nThis group is mandatory; you currently cannot rollup documents without a timestamp and a `date_histogram` group.", "name": "date_histogram", "required": false, "type": { @@ -165707,6 +165717,7 @@ } }, { + "description": "The histogram group aggregates one or more numeric fields into numeric histogram intervals.", "name": "histogram", "required": false, "type": { @@ -165718,6 +165729,7 @@ } }, { + "description": "The terms group can be used on keyword or numeric fields to allow bucketing via the terms aggregation at a later point.\nThe indexer enumerates and stores all values of a field for each time-period.\nThis can be potentially costly for high-cardinality groups such as IP addresses, especially if the time-bucket is particularly sparse.", "name": "terms", "required": false, "type": { @@ -165729,7 +165741,7 @@ } } ], - "specLocation": "rollup/_types/Groupings.ts#L24-L28" + "specLocation": "rollup/_types/Groupings.ts#L24-L40" }, { "kind": "interface", @@ -165739,6 +165751,7 @@ }, "properties": [ { + "description": "The set of fields that you wish to build histograms for.\nAll fields specified must be some kind of numeric.\nOrder does not matter.", "name": "fields", "required": true, "type": { @@ -165750,6 +165763,7 @@ } }, { + "description": "The interval of histogram buckets to be generated when rolling up.\nFor example, a value of `5` creates buckets that are five units wide (`0-5`, `5-10`, etc).\nNote that only one interval can be specified in the histogram group, meaning that all fields being grouped via the histogram must share the same interval.", "name": "interval", "required": true, "type": { @@ -165761,7 +165775,7 @@ } } ], - "specLocation": "rollup/_types/Groupings.ts#L44-L47" + "specLocation": "rollup/_types/Groupings.ts#L84-L97" }, { "kind": "enum", @@ -165796,6 +165810,7 @@ }, "properties": [ { + "description": "The set of fields that you wish to collect terms for.\nThis array can contain fields that are both keyword and numerics.\nOrder does not matter.", "name": "fields", "required": true, "type": { @@ -165807,7 +165822,7 @@ } } ], - "specLocation": "rollup/_types/Groupings.ts#L40-L42" + "specLocation": "rollup/_types/Groupings.ts#L75-L82" }, { "attachedBehaviors": [ @@ -165830,7 +165845,7 @@ }, "path": [ { - "description": "The ID of the job to delete", + "description": "Identifier for the job.", "name": "id", "required": true, "type": { @@ -165843,7 +165858,7 @@ } ], "query": [], - "specLocation": "rollup/delete_job/DeleteRollupJobRequest.ts#L23-L31" + "specLocation": "rollup/delete_job/DeleteRollupJobRequest.ts#L23-L35" }, { "body": { @@ -165929,7 +165944,7 @@ }, "path": [ { - "description": "The ID of the job(s) to fetch. Accepts glob patterns, or left blank for all jobs", + "description": "Identifier for the rollup job.\nIf it is `_all` or omitted, the API returns all rollup jobs.", "name": "id", "required": false, "type": { @@ -165942,7 +165957,7 @@ } ], "query": [], - "specLocation": "rollup/get_jobs/GetRollupJobRequest.ts#L23-L31" + "specLocation": "rollup/get_jobs/GetRollupJobRequest.ts#L23-L36" }, { "body": { @@ -166355,7 +166370,7 @@ }, "path": [ { - "description": "The ID of the index to check rollup capabilities on, or left blank for all jobs", + "description": "Index, indices or index-pattern to return rollup capabilities for.\n`_all` may be used to fetch rollup capabilities from all jobs.", "name": "id", "required": false, "type": { @@ -166368,7 +166383,7 @@ } ], "query": [], - "specLocation": "rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts#L23-L31" + "specLocation": "rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts#L23-L36" }, { "body": { @@ -166565,7 +166580,7 @@ "body": { "kind": "no_body" }, - "description": "Returns the rollup capabilities of all jobs inside of a rollup index (e.g. the index where rollup data is stored).", + "description": "Returns the rollup capabilities of all jobs inside of a rollup index (for example, the index where rollup data is stored).", "inherits": { "type": { "name": "RequestBase", @@ -166579,7 +166594,7 @@ }, "path": [ { - "description": "The rollup index or index pattern to obtain rollup capabilities from.", + "description": "Data stream or index to check for rollup capabilities.\nWildcard (`*`) expressions are supported.", "name": "index", "required": true, "type": { @@ -166592,7 +166607,7 @@ } ], "query": [], - "specLocation": "rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts#L23-L31" + "specLocation": "rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts#L23-L36" }, { "body": { @@ -166869,7 +166884,7 @@ } ], "query": [], - "specLocation": "rollup/put_job/CreateRollupJobRequest.ts#L27-L88" + "specLocation": "rollup/put_job/CreateRollupJobRequest.ts#L27-L89" }, { "body": { @@ -166900,6 +166915,7 @@ "aliases": [ "aggs" ], + "description": "Specifies aggregations.", "name": "aggregations", "required": false, "type": { @@ -166922,6 +166938,7 @@ } }, { + "description": "Specifies a DSL query.", "name": "query", "required": false, "type": { @@ -166933,7 +166950,7 @@ } }, { - "description": "Must be zero if set, as rollups work on pre-aggregated data", + "description": "Must be zero if set, as rollups work on pre-aggregated data.", "name": "size", "required": false, "type": { @@ -166946,7 +166963,7 @@ } ] }, - "description": "Enables searching rolled-up data using the standard query DSL.", + "description": "Enables searching rolled-up data using the standard Query DSL.", "inherits": { "type": { "name": "RequestBase", @@ -166960,7 +166977,7 @@ }, "path": [ { - "description": "The indices or index-pattern(s) (containing rollup or regular data) that should be searched", + "description": "Enables searching rolled-up data using the standard Query DSL.", "name": "index", "required": true, "type": { @@ -166998,7 +167015,7 @@ } } ], - "specLocation": "rollup/rollup_search/RollupSearchRequest.ts#L27-L46" + "specLocation": "rollup/rollup_search/RollupSearchRequest.ts#L27-L57" }, { "body": { @@ -167126,7 +167143,7 @@ }, "path": [ { - "description": "The ID of the job to start", + "description": "Identifier for the rollup job.", "name": "id", "required": true, "type": { @@ -167139,7 +167156,7 @@ } ], "query": [], - "specLocation": "rollup/start_job/StartRollupJobRequest.ts#L23-L31" + "specLocation": "rollup/start_job/StartRollupJobRequest.ts#L23-L35" }, { "body": { @@ -167186,7 +167203,7 @@ }, "path": [ { - "description": "The ID of the job to stop", + "description": "Identifier for the rollup job.", "name": "id", "required": true, "type": { @@ -167200,9 +167217,10 @@ ], "query": [ { - "description": "Block for (at maximum) the specified duration while waiting for the job to stop. Defaults to 30s.", + "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.", "name": "timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -167212,9 +167230,10 @@ } }, { - "description": "True if the API should block until the job has fully stopped, false if should be executed async. Defaults to false.", + "description": "If set to `true`, causes the API to block until the indexer state completely stops.\nIf set to `false`, the API returns immediately and the indexer is stopped asynchronously in the background.", "name": "wait_for_completion", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -167224,7 +167243,7 @@ } } ], - "specLocation": "rollup/stop_job/StopRollupJobRequest.ts#L24-L36" + "specLocation": "rollup/stop_job/StopRollupJobRequest.ts#L24-L50" }, { "body": { diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index b7d0dfdac5..757ed7f593 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -17,6 +17,7 @@ autoscaling-put-autoscaling-policy,https://www.elastic.co/guide/en/elasticsearch avoid-index-pattern-collisions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index-templates.html#avoid-index-pattern-collisions byte-units,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/api-conventions.html#byte-units bytes-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/bytes-processor.html +calendar-and-fixed-intervals,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-datehistogram-aggregation.html#calendar_and_fixed_intervals cat-alias,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-alias.html cat-allocation,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-allocation.html cat-anomaly-detectors,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cat-anomaly-detectors.html diff --git a/specification/rollup/_types/Groupings.ts b/specification/rollup/_types/Groupings.ts index eb1e608cb7..76ef882180 100644 --- a/specification/rollup/_types/Groupings.ts +++ b/specification/rollup/_types/Groupings.ts @@ -22,26 +22,76 @@ import { long } from '@_types/Numeric' import { Duration, TimeZone } from '@_types/Time' export class Groupings { + /** + * A date histogram group aggregates a date field into time-based buckets. + * This group is mandatory; you currently cannot rollup documents without a timestamp and a `date_histogram` group. + */ date_histogram?: DateHistogramGrouping + /** + * The histogram group aggregates one or more numeric fields into numeric histogram intervals. + */ histogram?: HistogramGrouping + /** + * The terms group can be used on keyword or numeric fields to allow bucketing via the terms aggregation at a later point. + * The indexer enumerates and stores all values of a field for each time-period. + * This can be potentially costly for high-cardinality groups such as IP addresses, especially if the time-bucket is particularly sparse. + */ terms?: TermsGrouping } export class DateHistogramGrouping { + /** + * How long to wait before rolling up new documents. + * By default, the indexer attempts to roll up all data that is available. + * However, it is not uncommon for data to arrive out of order. + * The indexer is unable to deal with data that arrives after a time-span has been rolled up. + * You need to specify a delay that matches the longest period of time you expect out-of-order data to arrive. + */ delay?: Duration + /** + * The date field that is to be rolled up. + */ field: Field format?: string interval?: Duration + /** + * The interval of time buckets to be generated when rolling up. + * @doc_id calendar-and-fixed-intervals + */ calendar_interval?: Duration + /** + * The interval of time buckets to be generated when rolling up. + * @doc_id calendar-and-fixed-intervals + */ fixed_interval?: Duration + /** + * Defines what `time_zone` the rollup documents are stored as. + * Unlike raw data, which can shift timezones on the fly, rolled documents have to be stored with a specific timezone. + * By default, rollup documents are stored in `UTC`. + */ time_zone?: TimeZone } export class TermsGrouping { + /** + * The set of fields that you wish to collect terms for. + * This array can contain fields that are both keyword and numerics. + * Order does not matter. + */ fields: Fields } export class HistogramGrouping { + /** + * The set of fields that you wish to build histograms for. + * All fields specified must be some kind of numeric. + * Order does not matter. + */ fields: Fields + /** + * The interval of histogram buckets to be generated when rolling up. + * For example, a value of `5` creates buckets that are five units wide (`0-5`, `5-10`, etc). + * Note that only one interval can be specified in the histogram group, meaning that all fields being grouped via the histogram must share the same interval. + */ interval: long } diff --git a/specification/rollup/delete_job/DeleteRollupJobRequest.ts b/specification/rollup/delete_job/DeleteRollupJobRequest.ts index e0d16506c4..e2d467fe3d 100644 --- a/specification/rollup/delete_job/DeleteRollupJobRequest.ts +++ b/specification/rollup/delete_job/DeleteRollupJobRequest.ts @@ -21,11 +21,15 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** + * Deletes an existing rollup job. * @rest_spec_name rollup.delete_job * @availability stack since=6.3.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Identifier for the job. + */ id: Id } } diff --git a/specification/rollup/get_jobs/GetRollupJobRequest.ts b/specification/rollup/get_jobs/GetRollupJobRequest.ts index 957ddc394e..fa990bf94f 100644 --- a/specification/rollup/get_jobs/GetRollupJobRequest.ts +++ b/specification/rollup/get_jobs/GetRollupJobRequest.ts @@ -21,11 +21,16 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** + * Retrieves the configuration, stats, and status of rollup jobs. * @rest_spec_name rollup.get_jobs * @availability stack since=6.3.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Identifier for the rollup job. + * If it is `_all` or omitted, the API returns all rollup jobs. + */ id?: Id } } diff --git a/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts b/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts index 2e8f2d5dd3..bd7673d72a 100644 --- a/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts +++ b/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts @@ -21,11 +21,16 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** + * Returns the capabilities of any rollup jobs that have been configured for a specific index or index pattern. * @rest_spec_name rollup.get_rollup_caps * @availability stack since=6.3.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Index, indices or index-pattern to return rollup capabilities for. + * `_all` may be used to fetch rollup capabilities from all jobs. + */ id?: Id } } diff --git a/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts b/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts index 4534a42ad8..36d77bd4c2 100644 --- a/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts +++ b/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts @@ -21,11 +21,16 @@ import { RequestBase } from '@_types/Base' import { Ids } from '@_types/common' /** + * Returns the rollup capabilities of all jobs inside of a rollup index (for example, the index where rollup data is stored). * @rest_spec_name rollup.get_rollup_index_caps * @availability stack since=6.4.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Data stream or index to check for rollup capabilities. + * Wildcard (`*`) expressions are supported. + */ index: Ids } } diff --git a/specification/rollup/put_job/CreateRollupJobRequest.ts b/specification/rollup/put_job/CreateRollupJobRequest.ts index f47bd5b149..6f00c8cb9a 100644 --- a/specification/rollup/put_job/CreateRollupJobRequest.ts +++ b/specification/rollup/put_job/CreateRollupJobRequest.ts @@ -25,6 +25,7 @@ import { integer } from '@_types/Numeric' import { Duration } from '@_types/Time' /** + * Creates a rollup job. * @rest_spec_name rollup.put_job * @availability stack since=6.3.0 stability=experimental * @cluster_privileges manage, manage_rollup diff --git a/specification/rollup/rollup_search/RollupSearchRequest.ts b/specification/rollup/rollup_search/RollupSearchRequest.ts index 63fc3b8507..7f27d9b54f 100644 --- a/specification/rollup/rollup_search/RollupSearchRequest.ts +++ b/specification/rollup/rollup_search/RollupSearchRequest.ts @@ -25,11 +25,15 @@ import { integer } from '@_types/Numeric' import { QueryContainer } from '@_types/query_dsl/abstractions' /** + * Enables searching rolled-up data using the standard Query DSL. * @rest_spec_name rollup.rollup_search * @availability stack since=6.3.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Enables searching rolled-up data using the standard Query DSL. + */ index: Indices } query_parameters: { @@ -37,10 +41,17 @@ export interface Request extends RequestBase { typed_keys?: boolean } body: { - /** @aliases aggs */ + /** + * Specifies aggregations. + * @aliases aggs */ aggregations?: Dictionary + /** + * Specifies a DSL query. + */ query?: QueryContainer - /** Must be zero if set, as rollups work on pre-aggregated data */ + /** + * Must be zero if set, as rollups work on pre-aggregated data. + */ size?: integer } } diff --git a/specification/rollup/start_job/StartRollupJobRequest.ts b/specification/rollup/start_job/StartRollupJobRequest.ts index c72c31104e..1ae1c98aaa 100644 --- a/specification/rollup/start_job/StartRollupJobRequest.ts +++ b/specification/rollup/start_job/StartRollupJobRequest.ts @@ -21,11 +21,15 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** + * Starts an existing, stopped rollup job. * @rest_spec_name rollup.start_job * @availability stack since=6.3.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Identifier for the rollup job. + */ id: Id } } diff --git a/specification/rollup/stop_job/StopRollupJobRequest.ts b/specification/rollup/stop_job/StopRollupJobRequest.ts index df5c0b29b8..a8824f19e3 100644 --- a/specification/rollup/stop_job/StopRollupJobRequest.ts +++ b/specification/rollup/stop_job/StopRollupJobRequest.ts @@ -22,15 +22,29 @@ import { Id } from '@_types/common' import { Duration } from '@_types/Time' /** + * Stops an existing, started rollup job. * @rest_spec_name rollup.stop_job * @availability stack since=6.3.0 stability=experimental */ export interface Request extends RequestBase { path_parts: { + /** + * Identifier for the rollup job. + */ id: Id } query_parameters: { + /** + * 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. + * @server_default 30s + */ timeout?: Duration + /** + * If set to `true`, causes the API to block until the indexer state completely stops. + * If set to `false`, the API returns immediately and the indexer is stopped asynchronously in the background. + * @server_default false + */ wait_for_completion?: boolean } }