Add further summaries (#2734)

shainaraskas · web-flow · commit c3dcedf7fd7f · 2024-07-26T14:38:23.000-04:00
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
diff --git a/output/schema/schema.json b/output/schema/schema.json
diff --git a/specification/_global/delete_by_query/DeleteByQueryRequest.ts b/specification/_global/delete_by_query/DeleteByQueryRequest.ts
@@ -34,6 +34,7 @@ import { Duration } from '@_types/Time'
 import { Operator } from '@_types/query_dsl/Operator'
 
 /**
+ * Delete documents.
  * Deletes documents that match the specified query.
  * @rest_spec_name delete_by_query
  * @availability stack since=5.0.0 stability=stable
diff --git a/specification/_global/update_by_query/UpdateByQueryRequest.ts b/specification/_global/update_by_query/UpdateByQueryRequest.ts
@@ -35,6 +35,7 @@ import { Duration } from '@_types/Time'
 import { Operator } from '@_types/query_dsl/Operator'
 
 /**
+ * Update documents.
  * Updates documents that match the specified query.
  * If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.
  * @rest_spec_name update_by_query
diff --git a/specification/cat/aliases/CatAliasesRequest.ts b/specification/cat/aliases/CatAliasesRequest.ts
@@ -21,9 +21,11 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { ExpandWildcards, Names } from '@_types/common'
 
 /**
+ * Get aliases.
  * Retrieves the cluster’s index aliases, including filter and routing information.
  * The API does not return data stream aliases.
- * IMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
+ * > info
+ * > CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use [the /_alias endpoints](#endpoint-alias).
  * @rest_spec_name cat.aliases
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/cat/component_templates/CatComponentTemplatesRequest.ts b/specification/cat/component_templates/CatComponentTemplatesRequest.ts
@@ -20,10 +20,12 @@
 import { CatRequestBase } from '@cat/_types/CatBase'
 
 /**
+ * Get component templates.
  * Returns information about component templates in a cluster.
  * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
- * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
- * They are not intended for use by applications. For application consumption, use the get component template API.
+ * > info
+ * > CAT APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use [the /_component_template endpoints](#endpoint-component-template).
  * @rest_spec_name cat.component_templates
  * @availability stack since=5.1.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/cat/count/CatCountRequest.ts b/specification/cat/count/CatCountRequest.ts
@@ -21,10 +21,12 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { Indices } from '@_types/common'
 
 /**
- * Provides quick access to a document count for a data stream, an index, or an entire cluster.
- * NOTE: The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
- * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
- * They are not intended for use by applications. For application consumption, use the count API.
+ * Get a document count.
+ * Provides quick access to a document count for a data stream, an index, or an entire cluster.n/
+ * The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
+ * > info
+ * > CAT APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use [the /_count endpoints](#endpoint-count).
  * @rest_spec_name cat.count
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/cat/help/CatHelpRequest.ts b/specification/cat/help/CatHelpRequest.ts
@@ -20,6 +20,8 @@
 import { CatRequestBase } from '@cat/_types/CatBase'
 
 /**
+ * Get CAT help.
+ * Returns help for the CAT APIs.
  * @rest_spec_name cat.help
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/cat/indices/CatIndicesRequest.ts b/specification/cat/indices/CatIndicesRequest.ts
@@ -22,12 +22,21 @@ import { Bytes, ExpandWildcards, HealthStatus, Indices } from '@_types/common'
 import { TimeUnit } from '@_types/Time'
 
 /**
+ * Get index information.
  * Returns high-level information about indices in a cluster, including backing indices for data streams.
- * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
- * They are not intended for use by applications. For application consumption, use the get index API.
- * Use the cat indices API to get the following information for each index in a cluster: shard count; document count; deleted document count; primary store size; total store size of all shards, including shard replicas.
+ * > info
+ * > CAT APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use an index endpoint.
+ *
+ * Use this request to get the following information for each index in a cluster:
+ * - shard count
+ * - document count
+ * - deleted document count
+ * - primary store size
+ * - total store size of all shards, including shard replicas
+ *
  * These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents.
- * To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
+ * To get an accurate count of Elasticsearch documents, use the [/_cat/count](#operation-cat-count) or [count](#endpoint-count) endpoints.
  * @rest_spec_name cat.indices
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts b/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts
@@ -22,11 +22,13 @@ import { Bytes, Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Get data frame analytics jobs.
  * Returns configuration and usage information about data frame analytics jobs.
  *
- * IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+ * > info
+ * > CAT APIs are only intended for human consumption using the Kibana
  * console or command line. They are not intended for use by applications. For
- * application consumption, use the get data frame analytics jobs statistics API.
+ * application consumption, use [the /_ml/data_frame/analytics endpoints](#endpoint-ml).
  *
  * @rest_spec_name cat.ml_data_frame_analytics
  * @availability stack since=7.7.0 stability=stable
diff --git a/specification/cat/ml_datafeeds/CatDatafeedsRequest.ts b/specification/cat/ml_datafeeds/CatDatafeedsRequest.ts
@@ -22,14 +22,16 @@ import { Id } from '@_types/common'
 import { TimeUnit } from '@_types/Time'
 
 /**
+ * Get datafeeds.
  * Returns configuration and usage information about datafeeds.
  * This API returns a maximum of 10,000 datafeeds.
  * If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage`
  * cluster privileges to use this API.
  *
- * IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+ * > info
+ * > CAT APIs are only intended for human consumption using the Kibana
  * console or command line. They are not intended for use by applications. For
- * application consumption, use the get datafeed statistics API.
+ * application consumption, use [the /_ml/datafeeds endpoints](#endpoint-ml).
  *
  * @rest_spec_name cat.ml_datafeeds
  * @availability stack since=7.7.0 stability=stable
diff --git a/specification/cat/ml_jobs/CatJobsRequest.ts b/specification/cat/ml_jobs/CatJobsRequest.ts
@@ -22,14 +22,16 @@ import { Bytes, Id } from '@_types/common'
 import { TimeUnit } from '@_types/Time'
 
 /**
+ * Get anomaly detection jobs.
  * Returns configuration and usage information for anomaly detection jobs.
  * This API returns a maximum of 10,000 jobs.
  * If the Elasticsearch security features are enabled, you must have `monitor_ml`,
  * `monitor`, `manage_ml`, or `manage` cluster privileges to use this API.
  *
- * IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+ * > info
+ * > CAT APIs are only intended for human consumption using the Kibana
  * console or command line. They are not intended for use by applications. For
- * application consumption, use the get anomaly detection job statistics API.
+ * application consumption, use [the /_ml/anomaly_detectors endpoints](#endpoint-ml).
  *
  * @rest_spec_name cat.ml_jobs
  * @availability stack since=7.7.0 stability=stable
diff --git a/specification/cat/ml_trained_models/CatTrainedModelsRequest.ts b/specification/cat/ml_trained_models/CatTrainedModelsRequest.ts
@@ -22,11 +22,13 @@ import { Bytes, Id } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
+ * Get trained models.
  * Returns configuration and usage information about inference trained models.
  *
- * IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+ * > info
+ * > CAT APIs are only intended for human consumption using the Kibana
  * console or command line. They are not intended for use by applications. For
- * application consumption, use the get trained models statistics API.
+ * application consumption, use [the /_ml/trained_models endpoints](#endpoint-ml).
  *
  * @rest_spec_name cat.ml_trained_models
  * @availability stack since=7.7.0 stability=stable
diff --git a/specification/cat/transforms/CatTransformsRequest.ts b/specification/cat/transforms/CatTransformsRequest.ts
@@ -23,11 +23,13 @@ import { integer } from '@_types/Numeric'
 import { Duration, TimeUnit } from '@_types/Time'
 
 /**
+ * Get transforms.
  * Returns configuration and usage information about transforms.
  *
- * IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+ * > info
+ * > CAT APIs are only intended for human consumption using the Kibana
  * console or command line. They are not intended for use by applications. For
- * application consumption, use the get transform statistics API.
+ * application consumption, use [the /_transform endpoints](#endpoint-transform).
  *
  * @rest_spec_name cat.transforms
  * @availability stack since=7.7.0 stability=stable
diff --git a/specification/enrich/delete_policy/DeleteEnrichPolicyRequest.ts b/specification/enrich/delete_policy/DeleteEnrichPolicyRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Delete an enrich policy.
  * Deletes an existing enrich policy and its enrich index.
  * @rest_spec_name enrich.delete_policy
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/enrich/get_policy/GetEnrichPolicyRequest.ts b/specification/enrich/get_policy/GetEnrichPolicyRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Get an enrich policy.
  * Returns information about an enrich policy.
  * @rest_spec_name enrich.get_policy
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/enrich/put_policy/PutEnrichPolicyRequest.ts b/specification/enrich/put_policy/PutEnrichPolicyRequest.ts
@@ -22,6 +22,7 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Create an enrich policy.
  * Creates an enrich policy.
  * @doc_id put-enrich-policy-api
  * @rest_spec_name enrich.put_policy
diff --git a/specification/enrich/stats/EnrichStatsRequest.ts b/specification/enrich/stats/EnrichStatsRequest.ts
@@ -20,6 +20,7 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Get enrich stats.
  * Returns enrich coordinator statistics and information about enrich policies that are currently executing.
  * @rest_spec_name enrich.stats
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/indices/get_field_mapping/IndicesGetFieldMappingRequest.ts b/specification/indices/get_field_mapping/IndicesGetFieldMappingRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { ExpandWildcards, Fields, Indices } from '@_types/common'
 
 /**
+ * Get mapping definitions.
  * Retrieves mapping definitions for one or more fields.
  * For data streams, the API retrieves field mappings for the stream’s backing indices.
  * @rest_spec_name indices.get_field_mapping
diff --git a/specification/indices/get_mapping/IndicesGetMappingRequest.ts b/specification/indices/get_mapping/IndicesGetMappingRequest.ts
@@ -22,6 +22,7 @@ import { ExpandWildcards, Indices } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Get mapping definitions.
  * Retrieves mapping definitions for one or more indices.
  * For data streams, the API retrieves mappings for the stream’s backing indices.
  * @rest_spec_name indices.get_mapping
diff --git a/specification/indices/put_mapping/IndicesPutMappingRequest.ts b/specification/indices/put_mapping/IndicesPutMappingRequest.ts
@@ -40,6 +40,7 @@ import { RuntimeFields } from '@_types/mapping/RuntimeFields'
 import { Duration } from '@_types/Time'
 
 /**
+ * Update field mappings.
  * Adds new fields to an existing data stream or index.
  * You can also use this API to change the search settings of existing fields.
  * For data streams, these changes are applied to all backing indices by default.
diff --git a/specification/indices/validate_query/IndicesValidateQueryRequest.ts b/specification/indices/validate_query/IndicesValidateQueryRequest.ts
@@ -23,7 +23,8 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
 import { Operator } from '@_types/query_dsl/Operator'
 
 /**
- * Validates a potentially expensive query without executing it.
+ * Validate a query.
+ * Validates a query without running it.
  * @rest_spec_name indices.validate_query
  * @availability stack since=1.3.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/transform/delete_transform/DeleteTransformRequest.ts b/specification/transform/delete_transform/DeleteTransformRequest.ts
@@ -22,6 +22,7 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Delete a transform.
  * Deletes a transform.
  * @rest_spec_name transform.delete_transform
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/transform/get_transform/GetTransformRequest.ts b/specification/transform/get_transform/GetTransformRequest.ts
@@ -22,6 +22,7 @@ import { Name, Names } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
+ * Get transforms.
  * Retrieves configuration information for transforms.
  * @rest_spec_name transform.get_transform
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/transform/get_transform_stats/GetTransformStatsRequest.ts b/specification/transform/get_transform_stats/GetTransformStatsRequest.ts
@@ -23,6 +23,7 @@ import { long } from '@_types/Numeric'
 import { Duration } from '@_types/Time'
 
 /**
+ * Get transform stats.
  * Retrieves usage information for transforms.
  * @rest_spec_name transform.get_transform_stats
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/transform/preview_transform/PreviewTransformRequest.ts b/specification/transform/preview_transform/PreviewTransformRequest.ts
@@ -31,7 +31,8 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Previews a transform.
+ * Preview a transform.
+ * Generates a preview of the results that you will get when you create a transform with the same configuration.
  *
  * It returns a maximum of 100 results. The calculations are based on all the current data in the source index. It also
  * generates a list of mappings and settings for the destination index. These values are determined based on the field
diff --git a/specification/transform/put_transform/PutTransformRequest.ts b/specification/transform/put_transform/PutTransformRequest.ts
@@ -31,6 +31,7 @@ import { Id, Metadata } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Create a transform.
  * Creates a transform.
  *
  * A transform copies data from source indices, transforms it, and persists it into an entity-centric destination index. You can also think of the destination index as a two-dimensional tabular data structure (known as
diff --git a/specification/transform/reset_transform/ResetTransformRequest.ts b/specification/transform/reset_transform/ResetTransformRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
+ * Reset a transform.
  * Resets a transform.
  * Before you can reset it, you must stop it; alternatively, use the `force` query parameter.
  * If the destination index was created by the transform, it is deleted.
diff --git a/specification/transform/schedule_now_transform/ScheduleNowTransformRequest.ts b/specification/transform/schedule_now_transform/ScheduleNowTransformRequest.ts
@@ -21,7 +21,8 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Schedules now a transform.
+ * Schedule a transform to start now.
+ * Instantly runs a transform to process data.
  *
  * If you _schedule_now a transform, it will process the new data instantly,
  * without waiting for the configured frequency interval. After _schedule_now API is called,
diff --git a/specification/transform/start_transform/StartTransformRequest.ts b/specification/transform/start_transform/StartTransformRequest.ts
@@ -22,6 +22,7 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Start a transform.
  * Starts a transform.
  *
  * When you start a transform, it creates the destination index if it does not already exist. The `number_of_shards` is
diff --git a/specification/transform/stop_transform/StopTransformRequest.ts b/specification/transform/stop_transform/StopTransformRequest.ts
@@ -22,6 +22,7 @@ import { Name } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Stop transforms.
  * Stops one or more transforms.
  * @rest_spec_name transform.stop_transform
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/transform/update_transform/UpdateTransformRequest.ts b/specification/transform/update_transform/UpdateTransformRequest.ts
@@ -29,6 +29,7 @@ import { Id, Metadata } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Update a transform.
  * Updates certain properties of a transform.
  *
  * All updated properties except `description` do not take effect until after the transform starts the next checkpoint,
