From 5fbb80f2dde4128eb4aad8f8044ab9d2cb0f8484 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 4 Jul 2024 08:16:58 -0700 Subject: [PATCH] Add summaries for machine learning APIs (#2453) --- output/openapi/elasticsearch-openapi.json | 10 +++++----- .../elasticsearch-serverless-openapi.json | 10 +++++----- output/schema/schema.json | 20 +++++++++---------- .../ml/close_job/MlCloseJobRequest.ts | 2 +- .../ml/delete_job/MlDeleteJobRequest.ts | 3 +-- specification/ml/open_job/MlOpenJobRequest.ts | 2 +- specification/ml/put_job/MlPutJobRequest.ts | 3 ++- 7 files changed, 25 insertions(+), 25 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 25d5138db9..828dd408ef 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -16705,8 +16705,8 @@ "tags": [ "ml.close_job" ], - "summary": "Close anomaly detection jobs A job can be opened and closed multiple times throughout its lifecycle", - "description": "A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.", + "summary": "Close anomaly detection jobs", + "description": "A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-close-job.html" }, @@ -18044,7 +18044,7 @@ "tags": [ "ml.put_job" ], - "summary": "Instantiates an anomaly detection job", + "summary": "Create an anomaly detection job", "description": "If you include a `datafeed_config`, you must have read index privileges on the source index.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-job.html" @@ -18229,7 +18229,7 @@ "tags": [ "ml.delete_job" ], - "summary": "Deletes an anomaly detection job.", + "summary": "Delete an anomaly detection job", "description": "All job configuration, model state and results are deleted. It is not currently possible to delete multiple jobs using wildcards or a comma separated list. If you delete a job that has a datafeed, the request first tries to delete the datafeed. This behavior is equivalent to calling the delete datafeed API with the same timeout and force parameters as the delete job request.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-job.html" @@ -20630,7 +20630,7 @@ "tags": [ "ml.open_job" ], - "summary": "Opens one or more anomaly detection jobs", + "summary": "Open anomaly detection jobs", "description": "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. 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 new data is received.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html" diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index aa5e2584f3..fd03a9aa9e 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -10079,8 +10079,8 @@ "tags": [ "ml.close_job" ], - "summary": "Close anomaly detection jobs A job can be opened and closed multiple times throughout its lifecycle", - "description": "A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.", + "summary": "Close anomaly detection jobs", + "description": "A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-close-job.html" }, @@ -11197,7 +11197,7 @@ "tags": [ "ml.put_job" ], - "summary": "Instantiates an anomaly detection job", + "summary": "Create an anomaly detection job", "description": "If you include a `datafeed_config`, you must have read index privileges on the source index.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-job.html" @@ -11382,7 +11382,7 @@ "tags": [ "ml.delete_job" ], - "summary": "Deletes an anomaly detection job.", + "summary": "Delete an anomaly detection job", "description": "All job configuration, model state and results are deleted. It is not currently possible to delete multiple jobs using wildcards or a comma separated list. If you delete a job that has a datafeed, the request first tries to delete the datafeed. This behavior is equivalent to calling the delete datafeed API with the same timeout and force parameters as the delete job request.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-job.html" @@ -12747,7 +12747,7 @@ "tags": [ "ml.open_job" ], - "summary": "Opens one or more anomaly detection jobs", + "summary": "Open anomaly detection jobs", "description": "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. 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 new data is received.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html" diff --git a/output/schema/schema.json b/output/schema/schema.json index 1c76b5b168..0366010f6d 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -10074,7 +10074,7 @@ "stability": "stable" } }, - "description": "Close anomaly detection jobs\nA job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.\nWhen you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.\nIf you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.\nWhen a datafeed that has a specified end date stops, it automatically closes its associated job.", + "description": "Close anomaly detection jobs.\nA job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.\nWhen you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.\nIf you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.\nWhen a datafeed that has a specified end date stops, it automatically closes its associated job.", "docId": "ml-close-job", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ml-close-job.html", "name": "ml.close_job", @@ -10480,7 +10480,7 @@ "stability": "stable" } }, - "description": "Deletes an anomaly detection job.\n\nAll job configuration, model state and results are deleted.\nIt is not currently possible to delete multiple jobs using wildcards or a\ncomma separated list. If you delete a job that has a datafeed, the request\nfirst tries to delete the datafeed. This behavior is equivalent to calling\nthe delete datafeed API with the same timeout and force parameters as the\ndelete job request.", + "description": "Delete an anomaly detection job.\nAll job configuration, model state and results are deleted.\nIt is not currently possible to delete multiple jobs using wildcards or a\ncomma separated list. If you delete a job that has a datafeed, the request\nfirst tries to delete the datafeed. This behavior is equivalent to calling\nthe delete datafeed API with the same timeout and force parameters as the\ndelete job request.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-job.html", "name": "ml.delete_job", "privileges": { @@ -11920,7 +11920,7 @@ "stability": "stable" } }, - "description": "Opens one or more anomaly detection jobs.\nAn anomaly detection job must be opened in order for it to be ready to\nreceive and analyze data. It can be opened and closed multiple times\nthroughout its lifecycle.\nWhen you open a new job, it starts with an empty model.\nWhen you open an existing job, the most recent model state is automatically\nloaded. The job is ready to resume its analysis from where it left off, once\nnew data is received.", + "description": "Open anomaly detection jobs.\nAn anomaly detection job must be opened in order for it to be ready to\nreceive and analyze data. It can be opened and closed multiple times\nthroughout its lifecycle.\nWhen you open a new job, it starts with an empty model.\nWhen you open an existing job, the most recent model state is automatically\nloaded. The job is ready to resume its analysis from where it left off, once\nnew data is received.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html", "name": "ml.open_job", "privileges": { @@ -12408,7 +12408,7 @@ "stability": "stable" } }, - "description": "Instantiates an anomaly detection job. If you include a `datafeed_config`, you must have read index privileges on the source index.", + "description": "Create an anomaly detection job.\nIf you include a `datafeed_config`, you must have read index privileges on the source index.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-job.html", "name": "ml.put_job", "privileges": { @@ -154873,7 +154873,7 @@ } ] }, - "description": "Close anomaly detection jobs\nA job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.\nWhen you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.\nIf you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.\nWhen a datafeed that has a specified end date stops, it automatically closes its associated job.", + "description": "Close anomaly detection jobs.\nA job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results.\nWhen you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data.\nIf you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request.\nWhen a datafeed that has a specified end date stops, it automatically closes its associated job.", "inherits": { "type": { "name": "RequestBase", @@ -155598,7 +155598,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes an anomaly detection job.\n\nAll job configuration, model state and results are deleted.\nIt is not currently possible to delete multiple jobs using wildcards or a\ncomma separated list. If you delete a job that has a datafeed, the request\nfirst tries to delete the datafeed. This behavior is equivalent to calling\nthe delete datafeed API with the same timeout and force parameters as the\ndelete job request.", + "description": "Delete an anomaly detection job.\nAll job configuration, model state and results are deleted.\nIt is not currently possible to delete multiple jobs using wildcards or a\ncomma separated list. If you delete a job that has a datafeed, the request\nfirst tries to delete the datafeed. This behavior is equivalent to calling\nthe delete datafeed API with the same timeout and force parameters as the\ndelete job request.", "inherits": { "type": { "name": "RequestBase", @@ -155664,7 +155664,7 @@ } } ], - "specLocation": "ml/delete_job/MlDeleteJobRequest.ts#L23-L64" + "specLocation": "ml/delete_job/MlDeleteJobRequest.ts#L23-L63" }, { "body": { @@ -161026,7 +161026,7 @@ } ] }, - "description": "Opens one or more anomaly detection jobs.\nAn anomaly detection job must be opened in order for it to be ready to\nreceive and analyze data. It can be opened and closed multiple times\nthroughout its lifecycle.\nWhen you open a new job, it starts with an empty model.\nWhen you open an existing job, the most recent model state is automatically\nloaded. The job is ready to resume its analysis from where it left off, once\nnew data is received.", + "description": "Open anomaly detection jobs.\nAn anomaly detection job must be opened in order for it to be ready to\nreceive and analyze data. It can be opened and closed multiple times\nthroughout its lifecycle.\nWhen you open a new job, it starts with an empty model.\nWhen you open an existing job, the most recent model state is automatically\nloaded. The job is ready to resume its analysis from where it left off, once\nnew data is received.", "inherits": { "type": { "name": "RequestBase", @@ -163064,7 +163064,7 @@ } ] }, - "description": "Instantiates an anomaly detection job. If you include a `datafeed_config`, you must have read index privileges on the source index.", + "description": "Create an anomaly detection job.\nIf you include a `datafeed_config`, you must have read index privileges on the source index.", "inherits": { "type": { "name": "RequestBase", @@ -163091,7 +163091,7 @@ } ], "query": [], - "specLocation": "ml/put_job/MlPutJobRequest.ts#L30-L111" + "specLocation": "ml/put_job/MlPutJobRequest.ts#L30-L112" }, { "body": { diff --git a/specification/ml/close_job/MlCloseJobRequest.ts b/specification/ml/close_job/MlCloseJobRequest.ts index da30f6e2b7..4808f1d6bc 100644 --- a/specification/ml/close_job/MlCloseJobRequest.ts +++ b/specification/ml/close_job/MlCloseJobRequest.ts @@ -22,7 +22,7 @@ import { Id } from '@_types/common' import { Duration } from '@_types/Time' /** - * Close anomaly detection jobs + * Close anomaly detection jobs. * A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. * When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. * If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. diff --git a/specification/ml/delete_job/MlDeleteJobRequest.ts b/specification/ml/delete_job/MlDeleteJobRequest.ts index ff89c7957b..6560a531ef 100644 --- a/specification/ml/delete_job/MlDeleteJobRequest.ts +++ b/specification/ml/delete_job/MlDeleteJobRequest.ts @@ -21,8 +21,7 @@ import { RequestBase } from '@_types/Base' import { Id } from '@_types/common' /** - * Deletes an anomaly detection job. - * + * Delete an anomaly detection job. * All job configuration, model state and results are deleted. * It is not currently possible to delete multiple jobs using wildcards or a * comma separated list. If you delete a job that has a datafeed, the request diff --git a/specification/ml/open_job/MlOpenJobRequest.ts b/specification/ml/open_job/MlOpenJobRequest.ts index 2b05b44aef..9813f14700 100644 --- a/specification/ml/open_job/MlOpenJobRequest.ts +++ b/specification/ml/open_job/MlOpenJobRequest.ts @@ -22,7 +22,7 @@ import { Id } from '@_types/common' import { Duration } from '@_types/Time' /** - * Opens one or more anomaly detection jobs. + * 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. diff --git a/specification/ml/put_job/MlPutJobRequest.ts b/specification/ml/put_job/MlPutJobRequest.ts index 645d1cef7b..24ac4b1ad2 100644 --- a/specification/ml/put_job/MlPutJobRequest.ts +++ b/specification/ml/put_job/MlPutJobRequest.ts @@ -28,7 +28,8 @@ import { Duration } from '@_types/Time' import { DatafeedConfig } from '@ml/_types/Datafeed' /** - * Instantiates an anomaly detection job. If you include a `datafeed_config`, you must have read index privileges on the source index. + * Create an anomaly detection job. + * If you include a `datafeed_config`, you must have read index privileges on the source index. * @rest_spec_name ml.put_job * @availability stack since=5.4.0 stability=stable * @availability serverless stability=stable visibility=public