Reviews summaries of ML APIs (F-Z) (#2764)

Co-authored-by: Lisa Cawley <[email protected]>
Co-authored-by: David Kyle <[email protected]>

specification/ml/flush_job/MlFlushJobRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { DateTime } from '@_types/Time'
 
 /**
- * Forces any buffered data to be processed by the job.
+ * Force buffered data to be processed.
  * The flush jobs API is only applicable when sending data for analysis using
  * the post data API. Depending on the content of the buffer, then it might
  * additionally calculate new results. Both flush and close operations are

specification/ml/forecast/MlForecastJobRequest.ts

@@ -22,12 +22,12 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Predicts the future behavior of a time series by using its historical
- * behavior.
+ * Predict future behavior of a time series.
  *
  * Forecasts are not supported for jobs that perform population analysis; an
  * error occurs if you try to create a forecast for a job that has an
- * `over_field_name` in its configuration.
+ * `over_field_name` in its configuration. Forcasts predict future behavior
+ * based on historical data.
  *
  * @rest_spec_name ml.forecast
  * @availability stack since=6.1.0 stability=stable

specification/ml/get_buckets/MlGetBucketsRequest.ts

@@ -24,7 +24,7 @@ import { double, integer } from '@_types/Numeric'
 import { DateTime } from '@_types/Time'
 
 /**
- * Retrieves anomaly detection job results for one or more buckets.
+ * Get anomaly detection job results for buckets.
  * The API presents a chronological view of the records, grouped by bucket.
  * @rest_spec_name ml.get_buckets
  * @availability stack since=5.4.0 stability=stable

specification/ml/get_calendar_events/MlGetCalendarEventsRequest.ts

@@ -23,7 +23,7 @@ import { integer } from '@_types/Numeric'
 import { DateTime } from '@_types/Time'
 
 /**
- * Retrieves information about the scheduled events in calendars.
+ * Get info about events in calendars.
  * @rest_spec_name ml.get_calendar_events
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/get_calendars/MlGetCalendarsRequest.ts

@@ -23,7 +23,7 @@ import { Id } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Retrieves configuration information for calendars.
+ * Get calendar configuration info.
  * @rest_spec_name ml.get_calendars
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/get_categories/MlGetCategoriesRequest.ts

@@ -23,7 +23,7 @@ import { CategoryId, Id } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Retrieves anomaly detection job results for one or more categories.
+ * Get anomaly detection job results for categories.
  * @rest_spec_name ml.get_categories
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/ml/get_data_frame_analytics/MlGetDataFrameAnalyticsRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Retrieves configuration information for data frame analytics jobs.
+ * Get data frame analytics job configuration info.
  * You can get information for multiple data frame analytics jobs in a single
  * API request by using a comma-separated list of data frame analytics jobs or a
  * wildcard expression.

specification/ml/get_data_frame_analytics_stats/MlGetDataFrameAnalyticsStatsRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Retrieves usage information for data frame analytics jobs.
+ * Get data frame analytics jobs usage info.
  * @rest_spec_name ml.get_data_frame_analytics_stats
  * @availability stack since=7.3.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/get_datafeed_stats/MlGetDatafeedStatsRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
- * Retrieves usage information for datafeeds.
+ * Get datafeeds usage info.
  * You can get statistics for multiple datafeeds in a single API request by
  * using a comma-separated list of datafeeds or a wildcard expression. You can
  * get statistics for all datafeeds by using `_all`, by specifying `*` as the

specification/ml/get_datafeeds/MlGetDatafeedsRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
- * Retrieves configuration information for datafeeds.
+ * Get datafeeds configuration info.
  * You can get information for multiple datafeeds in a single API request by
  * using a comma-separated list of datafeeds or a wildcard expression. You can
  * get information for all datafeeds by using `_all`, by specifying `*` as the

specification/ml/get_filters/MlGetFiltersRequest.ts

@@ -22,7 +22,7 @@ import { Ids } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Retrieves filters.
+ * Get filters.
  * You can get a single filter or all filters.
  * @rest_spec_name ml.get_filters
  * @availability stack since=5.5.0 stability=stable

specification/ml/get_influencers/MlGetInfluencersRequest.ts

@@ -24,7 +24,7 @@ import { double, integer } from '@_types/Numeric'
 import { DateTime } from '@_types/Time'
 
 /**
- * Retrieves anomaly detection job results for one or more influencers.
+ * Get anomaly detection job results for influencers.
  * Influencers are the entities that have contributed to, or are to blame for,
  * the anomalies. Influencer results are available only if an
  * `influencer_field_name` is specified in the job configuration.

specification/ml/get_job_stats/MlGetJobStatsRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Retrieves usage information for anomaly detection jobs.
+ * Get anomaly detection jobs usage info.
  * @rest_spec_name ml.get_job_stats
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/get_jobs/MlGetJobsRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
- * Retrieves configuration information for anomaly detection jobs.
+ * Get anomaly detection jobs configuration info.
  * You can get information for multiple anomaly detection jobs in a single API
  * request by using a group name, a comma-separated list of jobs, or a wildcard
  * expression. You can get information for all anomaly detection jobs by using

specification/ml/get_memory_stats/MlGetMemoryStatsRequest.ts

@@ -22,6 +22,7 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
+ * Get machine learning memory usage info.
  * Get information about how machine learning jobs and trained models are using memory,
  * on each node, both within the JVM heap, and natively, outside of the JVM.
  * @rest_spec_name ml.get_memory_stats

specification/ml/get_model_snapshot_upgrade_stats/MlGetModelSnapshotUpgradeStatsRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Retrieves usage information for anomaly detection job model snapshot upgrades.
+ * Get anomaly detection job model snapshot upgrade usage info.
  * @rest_spec_name ml.get_model_snapshot_upgrade_stats
  * @availability stack since=7.16.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/ml/get_model_snapshots/MlGetModelSnapshotsRequest.ts

@@ -24,7 +24,7 @@ import { integer } from '@_types/Numeric'
 import { Duration, DateTime } from '@_types/Time'
 
 /**
- * Retrieves information about model snapshots.
+ * Get model snapshots info.
  * @rest_spec_name ml.get_model_snapshots
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/ml/get_overall_buckets/MlGetOverallBucketsRequest.ts

@@ -23,7 +23,9 @@ import { double, integer } from '@_types/Numeric'
 import { Duration, DateTime } from '@_types/Time'
 
 /**
- * Retrieves overall bucket results that summarize the bucket results of
+ * Get overall bucket results.
+ *
+ * Retrievs overall bucket results that summarize the bucket results of
  * multiple anomaly detection jobs.
  *
  * The `overall_score` is calculated by combining the scores of all the

specification/ml/get_records/MlGetAnomalyRecordsRequest.ts

@@ -24,7 +24,7 @@ import { double, integer } from '@_types/Numeric'
 import { DateTime } from '@_types/Time'
 
 /**
- * Retrieves anomaly records for an anomaly detection job.
+ * Get anomaly records for an anomaly detection job.
  * Records contain the detailed analytical results. They describe the anomalous
  * activity that has been identified in the input data based on the detector
  * configuration.

specification/ml/get_trained_models/MlGetTrainedModelRequest.ts

@@ -23,7 +23,7 @@ import { integer } from '@_types/Numeric'
 import { Include } from '@ml/_types/Include'
 
 /**
- * Retrieves configuration information for a trained model.
+ * Get trained model configuration info.
  * @rest_spec_name ml.get_trained_models
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/get_trained_models_stats/MlGetTrainedModelStatsRequest.ts

@@ -22,7 +22,8 @@ import { Ids } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Retrieves usage information for trained models. You can get usage information for multiple trained
+ * Get trained models usage info.
+ * You can get usage information for multiple trained
  * models in a single API request by using a comma-separated list of model IDs or a wildcard expression.
  * @rest_spec_name ml.get_trained_models_stats
  * @availability stack since=7.10.0 stability=stable

specification/ml/infer_trained_model/MlInferTrainedModelRequest.ts

@@ -25,7 +25,7 @@ import { InferenceConfigUpdateContainer } from '@ml/_types/inference'
 import { UserDefinedValue } from '@spec_utils/UserDefinedValue'
 
 /**
- * Evaluates a trained model.
+ * Evaluate a trained model.
  * @rest_spec_name ml.infer_trained_model
  * @availability stack since=8.3.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/info/MlInfoRequest.ts

@@ -20,6 +20,7 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Return ML defaults and limits.
  * Returns defaults and limits used by machine learning.
  * This endpoint is designed to be used by a user interface that needs to fully
  * understand machine learning configurations where some options are not

specification/ml/open_job/MlOpenJobRequest.ts

@@ -23,9 +23,8 @@ import { Duration } from '@_types/Time'
 
 /**
  * Open anomaly detection jobs.
- * An anomaly detection job must be opened in order for it to be ready to
- * receive and analyze data. It can be opened and closed multiple times
- * throughout its lifecycle.
+ * An anomaly detection job must be opened to be ready to receive and analyze
+ * data. It can be opened and closed multiple times throughout its lifecycle.
  * When you open a new job, it starts with an empty model.
  * When you open an existing job, the most recent model state is automatically
  * loaded. The job is ready to resume its analysis from where it left off, once

specification/ml/post_calendar_events/MlPostCalendarEventsRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { CalendarEvent } from '../_types/CalendarEvent'
 
 /**
- * Adds scheduled events to a calendar.
+ * Add scheduled events to the calendar.
  * @rest_spec_name ml.post_calendar_events
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/post_data/MlPostJobDataRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { DateTime } from '@_types/Time'
 
 /**
- * Sends data to an anomaly detection job for analysis.
+ * Send data to an anomaly detection job for analysis.
  *
  * IMPORTANT: For each job, data can be accepted from only a single connection at a time.
  * It is not currently possible to post data to multiple jobs using wildcards or a comma-separated list.

specification/ml/preview_data_frame_analytics/MlPreviewDataFrameAnalyticsRequest.ts

@@ -22,6 +22,7 @@ import { Id } from '@_types/common'
 import { DataframePreviewConfig } from './types'
 
 /**
+ * Preview features used by data frame analytics.
  * Previews the extracted features used by a data frame analytics config.
  * @rest_spec_name ml.preview_data_frame_analytics
  * @availability stack since=7.13.0 stability=stable

specification/ml/preview_datafeed/MlPreviewDatafeedRequest.ts

@@ -24,7 +24,7 @@ import { JobConfig } from '@ml/_types/Job'
 import { DateTime } from '@_types/Time'
 
 /**
- * Previews a datafeed.
+ * Preview a datafeed.
  * This API returns the first "page" of search results from a datafeed.
  * You can preview an existing datafeed or provide configuration details for a datafeed
  * and anomaly detection job in the API. The preview shows the structure of the data

specification/ml/put_calendar/MlPutCalendarRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Creates a calendar.
+ * Create a calendar.
  * @rest_spec_name ml.put_calendar
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/put_calendar_job/MlPutCalendarJobRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id, Ids } from '@_types/common'
 
 /**
- * Adds an anomaly detection job to a calendar.
+ * Add anomaly detection job to calendar.
  * @rest_spec_name ml.put_calendar_job
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/put_data_frame_analytics/MlPutDataFrameAnalyticsRequest.ts

@@ -28,7 +28,7 @@ import { HttpHeaders, Id, VersionString } from '@_types/common'
 import { integer } from '@_types/Numeric'
 
 /**
- * Instantiates a data frame analytics job.
+ * Create a data frame analytics job.
  * This API creates a data frame analytics job that performs an analysis on the
  * source indices and stores the outcome in a destination index.
  * @rest_spec_name ml.put_data_frame_analytics

specification/ml/put_datafeed/MlPutDatafeedRequest.ts

@@ -35,7 +35,7 @@ import { ScriptField } from '@_types/Scripting'
 import { Duration } from '@_types/Time'
 
 /**
- * Instantiates a datafeed.
+ * Create a datafeed.
  * Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job.
  * You can associate only one datafeed with each anomaly detection job.
  * The datafeed contains a query that runs at a defined interval (`frequency`).

specification/ml/put_filter/MlPutFilterRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Instantiates a filter.
+ * Create a filter.
  * A filter contains a list of strings. It can be used by one or more anomaly detection jobs.
  * Specifically, filters are referenced in the `custom_rules` property of detector configuration objects.
  * @rest_spec_name ml.put_filter

specification/ml/put_trained_model/MlPutTrainedModelRequest.ts

@@ -27,7 +27,8 @@ import { TrainedModelType } from '../_types/TrainedModel'
 import { InferenceConfigCreateContainer } from '@ml/_types/inference'
 
 /**
- * Enables you to supply a trained model that is not created by data frame analytics.
+ * Create a trained model.
+ * Enable you to supply a trained model that is not created by data frame analytics.
  * @rest_spec_name ml.put_trained_model
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/put_trained_model_alias/MlPutTrainedModelAliasRequest.ts

@@ -21,8 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Id, Name } from '@_types/common'
 
 /**
- * Creates or updates a trained model alias. A trained model alias is a logical
- * name used to reference a single trained model.
+ * Create or update a trained model alias.
+ * A trained model alias is a logical name used to reference a single trained
+ * model.
  * You can use aliases instead of trained model identifiers to make it easier to
  * reference your models. For example, you can use aliases in inference
  * aggregations and processors.

specification/ml/put_trained_model_definition_part/MlPutTrainedModelDefinitionPartRequest.ts

@@ -22,7 +22,7 @@ import { integer, long } from '@_types/Numeric'
 import { Id } from '@_types/common'
 
 /**
- * Creates part of a trained model definition.
+ * Create part of a trained model definition.
  * @rest_spec_name ml.put_trained_model_definition_part
  * @availability stack since=8.0.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/ml/put_trained_model_vocabulary/MlPutTrainedModelVocabularyRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { double } from '@_types/Numeric'
 
 /**
- * Creates a trained model vocabulary.
+ * Create a trained model vocabulary.
  * This API is supported only for natural language processing (NLP) models.
  * The vocabulary is stored in the index as described in `inference_config.*.vocabulary` of the trained model definition.
  * @rest_spec_name ml.put_trained_model_vocabulary

specification/ml/reset_job/MlResetJobRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Resets an anomaly detection job.
+ * Reset an anomaly detection job.
  * All model state and results are deleted. The job is ready to start over as if
  * it had just been created.
  * It is not currently possible to reset multiple jobs using wildcards or a

specification/ml/revert_model_snapshot/MlRevertModelSnapshotRequest.ts

@@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Reverts to a specific snapshot.
+ * Revert to a snapshot.
  * The machine learning features react quickly to anomalous input, learning new
  * behaviors in data. Highly anomalous input increases the variance in the
  * models whilst the system learns whether this is a new step-change in behavior

specification/ml/set_upgrade_mode/MlSetUpgradeModeRequest.ts

@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Duration } from '@_types/Time'
 
 /**
+ * Set upgrade_mode for ML indices.
  * Sets a cluster wide upgrade_mode setting that prepares machine learning
  * indices for an upgrade.
  * When upgrading your cluster, in some circumstances you must restart your

specification/ml/start_data_frame_analytics/MlStartDataFrameAnalyticsRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Starts a data frame analytics job.
+ * Start a data frame analytics job.
  * A data frame analytics job can be started and stopped multiple times
  * throughout its lifecycle.
  * If the destination index does not exist, it is created automatically the

specification/ml/start_datafeed/MlStartDatafeedRequest.ts

@@ -22,7 +22,7 @@ import { Id } from '@_types/common'
 import { Duration, DateTime } from '@_types/Time'
 
 /**
- * Starts one or more datafeeds.
+ * Start datafeeds.
  *
  * A datafeed must be started in order to retrieve data from Elasticsearch. A datafeed can be started and stopped
  * multiple times throughout its lifecycle.