[DOCS] Edits rollup summaries

Author: lcawl

specification/rollup/delete_job/DeleteRollupJobRequest.ts

@@ -21,9 +21,33 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Deletes an existing rollup job.
+ * Delete a rollup job.
+ *
+ * A job must be stopped first before it can be deleted.
+ * If you attempt to delete a started job, an error occurs.
+ * Similarly, if you attempt to delete a nonexistent job, an exception occurs.
+ *
+ * IMPORTANT: When you delete a job, you remove only the process that is actively monitoring and rolling up data.
+ * The API does not delete any previously rolled up data.
+ * This is by design; a user may wish to roll up a static data set.
+ * Because 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).
+ * Thus the job can be deleted, leaving behind the rolled up data for analysis.
+ * If 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.
+ * If 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:
+ *
+ * ```
+ * POST my_rollup_index/_delete_by_query
+ * {
+ *   "query": {
+ *     "term": {
+ *       "_rollup.id": "the_rollup_job_id"
+ *     }
+ *   }
+ * }
+ * ```
  * @rest_spec_name rollup.delete_job
  * @availability stack since=6.3.0 stability=experimental
+ * @cluster_privileges manage_rollup
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/rollup/get_jobs/GetRollupJobRequest.ts

@@ -21,9 +21,15 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Retrieves the configuration, stats, and status of rollup jobs.
+ * Get rollup job information.
+ * Get the configuration, stats, and status of rollup jobs.
+ *
+ * NOTE: This API returns only active (both `STARTED` and `STOPPED`) jobs.
+ * If a job was created, ran for a while, then was deleted, the API does not return any details about it.
+ * For details about a historical rollup job, the rollup capabilities API may be more useful.
  * @rest_spec_name rollup.get_jobs
  * @availability stack since=6.3.0 stability=experimental
+ * @cluster_privileges monitor_rollup
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/rollup/put_job/CreateRollupJobRequest.ts

@@ -25,7 +25,15 @@ import { integer } from '@_types/Numeric'
 import { Duration } from '@_types/Time'
 
 /**
- * Creates a rollup job.
+ * Create a rollup job.
+ *
+ * WARNING: 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 either needs to contain a rollup job or a rollup index in order for this API to be allowed to run.
+ *
+ * The 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.
+ *
+ * There 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.
+ *
+ * Jobs are created in a `STOPPED` state. You can start them with the start rollup jobs API.
  * @rest_spec_name rollup.put_job
  * @availability stack since=6.3.0 stability=experimental
  * @cluster_privileges manage, manage_rollup