From 2ef8257cd8ccab308d3161e4f8a9414bb0778bf3 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 13 Dec 2024 19:13:02 -0800 Subject: [PATCH] [DOCS] Edit more rollup summaries --- .../get_rollup_caps/GetRollupCapabilitiesRequest.ts | 11 ++++++++++- .../GetRollupIndexCapabilitiesRequest.ts | 8 +++++++- .../rollup/rollup_search/RollupSearchRequest.ts | 4 +++- .../rollup/start_job/StartRollupJobRequest.ts | 5 ++++- specification/rollup/stop_job/StopRollupJobRequest.ts | 5 ++++- 5 files changed, 28 insertions(+), 5 deletions(-) diff --git a/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts b/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts index bd7673d72a..21e61d290c 100644 --- a/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts +++ b/specification/rollup/get_rollup_caps/GetRollupCapabilitiesRequest.ts @@ -21,9 +21,18 @@ 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. + * Get the rollup job capabilities. + * Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern. + * + * This API is useful because a rollup job is often configured to rollup only a subset of fields from the source index. + * Furthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration. + * This API enables you to inspect an index and determine: + * + * 1. Does this index have associated rollup data somewhere in the cluster? + * 2. If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live? * @rest_spec_name rollup.get_rollup_caps * @availability stack since=6.3.0 stability=experimental + * @cluster_privileges monitor_rollup */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts b/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts index 36d77bd4c2..4ff08efcf4 100644 --- a/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts +++ b/specification/rollup/get_rollup_index_caps/GetRollupIndexCapabilitiesRequest.ts @@ -21,9 +21,15 @@ 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). + * Get the rollup index capabilities. + * Get the rollup capabilities of all jobs inside of a rollup index. + * A single rollup index may store the data for multiple rollup jobs and may have a variety of capabilities depending on those jobs. This API enables you to determine: + * + * * What jobs are stored in an index (or indices specified via a pattern)? + * * What target indices were rolled up, what fields were used in those rollups, and what aggregations can be performed on each job? * @rest_spec_name rollup.get_rollup_index_caps * @availability stack since=6.4.0 stability=experimental + * @index_privileges read */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/rollup/rollup_search/RollupSearchRequest.ts b/specification/rollup/rollup_search/RollupSearchRequest.ts index 7f27d9b54f..4261604f07 100644 --- a/specification/rollup/rollup_search/RollupSearchRequest.ts +++ b/specification/rollup/rollup_search/RollupSearchRequest.ts @@ -25,7 +25,9 @@ import { integer } from '@_types/Numeric' import { QueryContainer } from '@_types/query_dsl/abstractions' /** - * Enables searching rolled-up data using the standard Query DSL. + * 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. * @rest_spec_name rollup.rollup_search * @availability stack since=6.3.0 stability=experimental */ diff --git a/specification/rollup/start_job/StartRollupJobRequest.ts b/specification/rollup/start_job/StartRollupJobRequest.ts index 1ae1c98aaa..229aa2a56f 100644 --- a/specification/rollup/start_job/StartRollupJobRequest.ts +++ b/specification/rollup/start_job/StartRollupJobRequest.ts @@ -21,9 +21,12 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** - * Starts an existing, stopped rollup job. + * Start rollup jobs. + * If you try to start a job that does not exist, an exception occurs. + * If you try to start a job that is already started, nothing happens. * @rest_spec_name rollup.start_job * @availability stack since=6.3.0 stability=experimental + * @cluster_privileges manage_rollup */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/rollup/stop_job/StopRollupJobRequest.ts b/specification/rollup/stop_job/StopRollupJobRequest.ts index a8824f19e3..88541dea0c 100644 --- a/specification/rollup/stop_job/StopRollupJobRequest.ts +++ b/specification/rollup/stop_job/StopRollupJobRequest.ts @@ -22,9 +22,12 @@ import { Id } from '@_types/common' import { Duration } from '@_types/Time' /** - * Stops an existing, started rollup job. + * 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. * @rest_spec_name rollup.stop_job * @availability stack since=6.3.0 stability=experimental + * @cluster_privileges manage_rollup */ export interface Request extends RequestBase { path_parts: {