From feca6156fac37977311fb005a0dead5f46099bc5 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 26 Jun 2019 15:09:19 -0700 Subject: [PATCH 1/5] [DOCS] Adds data frame API response codes --- .../apis/get-transform-stats.asciidoc | 24 +++++++++++++------ .../data-frames/apis/get-transform.asciidoc | 24 +++++++++++++------ .../data-frames/apis/stop-transform.asciidoc | 17 ++++++++++--- 3 files changed, 48 insertions(+), 17 deletions(-) diff --git a/docs/reference/data-frames/apis/get-transform-stats.asciidoc b/docs/reference/data-frames/apis/get-transform-stats.asciidoc index 5751c8a3ea7bc..a996749d66a76 100644 --- a/docs/reference/data-frames/apis/get-transform-stats.asciidoc +++ b/docs/reference/data-frames/apis/get-transform-stats.asciidoc @@ -56,17 +56,20 @@ see {stack-ov}/security-privileges.html[Security privileges] and ==== {api-query-parms-title} `allow_no_match` (Optional):: - (boolean) Whether to ignore if a wildcard expression matches no - {dataframe-transforms}. This includes `_all` string or when no transforms have - been specified. The default is `true`. + (boolean) Specifies what to do when the request contains a wildcard expression + and there are no {dataframe-transforms} that match. The default value is + `true`, which returns an empty `transforms` array in this scenario. If it's + `false`, the request returns a `404` status code when there are no matches. + This parameter also affects requests that include the `_all` string or that + do not include any identifiers. `from` (Optional):: - (integer) Skips the specified number of {dataframe-transforms}. The - default value is `0`. + (integer) Skips the specified number of {dataframe-transforms}. The + default value is `0`. `size` (Optional):: - (integer) Specifies the maximum number of {dataframe-transforms} to obtain. - The default value is `100`. + (integer) Specifies the maximum number of {dataframe-transforms} to obtain. + The default value is `100`. [discrete] [[get-data-frame-transform-stats-response]] @@ -75,6 +78,13 @@ see {stack-ov}/security-privileges.html[Security privileges] and `transforms`:: (array) An array of statistics objects for {dataframe-transforms}, which are sorted by the `id` value in ascending order. + +[[get-data-frame-transform-stats-response-codes]] +==== {api-response-codes-title} + +`404`:: + If `allow_no_match` is `false`, this code indicates that there are no + resources that match the request. [discrete] [[get-data-frame-transform-stats-example]] diff --git a/docs/reference/data-frames/apis/get-transform.asciidoc b/docs/reference/data-frames/apis/get-transform.asciidoc index 9dd0ff092d754..70a2c259fe178 100644 --- a/docs/reference/data-frames/apis/get-transform.asciidoc +++ b/docs/reference/data-frames/apis/get-transform.asciidoc @@ -51,17 +51,20 @@ see {stack-ov}/security-privileges.html[Security privileges] and ==== {api-query-parms-title} `allow_no_match` (Optional):: - (boolean) Whether to ignore if a wildcard expression matches no - {dataframe-transforms}. This includes `_all` string or when no transforms have - been specified. The default is `true`. + (boolean) Specifies what to do when the request contains a wildcard expression + and there are no {dataframe-transforms} that match. The default value is + `true`, which returns an empty `transforms` array in this scenario. If it's + `false`, the request returns a `404` status code when there are no matches. + This parameter also affects requests that include the `_all` string or that + do not include any identifiers. `from` (Optional):: - (integer) Skips the specified number of {dataframe-transforms}. The - default value is `0`. + (integer) Skips the specified number of {dataframe-transforms}. The + default value is `0`. `size` (Optional):: - (integer) Specifies the maximum number of {dataframe-transforms} to obtain. - The default value is `100`. + (integer) Specifies the maximum number of {dataframe-transforms} to obtain. + The default value is `100`. [discrete] [[get-data-frame-transform-response]] @@ -70,6 +73,13 @@ see {stack-ov}/security-privileges.html[Security privileges] and `transforms`:: (array) An array of transform resources, which are sorted by the `id` value in ascending order. + +[[get-data-frame-transform-response-codes]] +==== {api-response-codes-title} + +`404`:: + If `allow_no_match` is `false`, this code indicates that there are no + resources that match the request. [discrete] [[get-data-frame-transform-example]] diff --git a/docs/reference/data-frames/apis/stop-transform.asciidoc b/docs/reference/data-frames/apis/stop-transform.asciidoc index 4ade2706ab2b6..8538788302e7f 100644 --- a/docs/reference/data-frames/apis/stop-transform.asciidoc +++ b/docs/reference/data-frames/apis/stop-transform.asciidoc @@ -55,9 +55,12 @@ All {dataframe-transforms} can be stopped by using `_all` or `*` as the ==== {api-query-parms-title} `allow_no_match` (Optional):: - (boolean) Whether to ignore if a wildcard expression matches no - {dataframe-transforms}. This includes `_all` string or when no transforms have - been specified. The default is `true`. + (boolean) Specifies what to do when the request contains a wildcard expression + and there are no {dataframe-transforms} that match. The default value is + `true`, which returns an empty `transforms` array in this scenario. If it's + `false`, the request returns a `404` status code when there are no matches. + This parameter also affects requests that include the `_all` string or that + do not include any identifiers. `timeout` (Optional):: (time value) If `wait_for_completion=true`, the API blocks for (at maximum) @@ -72,6 +75,14 @@ All {dataframe-transforms} can be stopped by using `_all` or `*` as the completely stops. If set to `false`, the API returns immediately and the indexer will be stopped asynchronously in the background. Defaults to `false`. +[discrete] +[[stop-data-frame-transform-response-codes]] +==== {api-response-codes-title} + +`404`:: + If `allow_no_match` is `false`, this code indicates that there are no + resources that match the request. + [discrete] [[stop-data-frame-transform-example]] ==== {api-example-title} From fa642dab2f456a8f82fc4a4a981029a88b52fa0d Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 27 Jun 2019 13:40:26 -0700 Subject: [PATCH 2/5] [DOCS] Addresses feedback --- .../apis/get-transform-stats.asciidoc | 34 +++++++++++++------ .../data-frames/apis/get-transform.asciidoc | 32 ++++++++++++----- .../data-frames/apis/stop-transform.asciidoc | 27 ++++++++++----- 3 files changed, 66 insertions(+), 27 deletions(-) diff --git a/docs/reference/data-frames/apis/get-transform-stats.asciidoc b/docs/reference/data-frames/apis/get-transform-stats.asciidoc index a996749d66a76..4934144c469ab 100644 --- a/docs/reference/data-frames/apis/get-transform-stats.asciidoc +++ b/docs/reference/data-frames/apis/get-transform-stats.asciidoc @@ -37,9 +37,15 @@ If the {es} {security-features} are enabled, you must have see {stack-ov}/security-privileges.html[Security privileges] and {stack-ov}/built-in-roles.html[Built-in roles]. -//[discrete] -//[[get-data-frame-transform-stats-desc]] -//===== {api-description-title} +[discrete] +[[get-data-frame-transform-stats-desc]] +===== {api-description-title} + +You can get statistics for multiple {dataframe-transforms} in a single API +request by using a comma-separated list of identifiers or a wildcard expression. +You can get statistics for all {dataframe-transforms} by using `_all`, by +specifying `*` as the ``, or by omitting the +``. [discrete] [[get-data-frame-transform-stats-path-parms]] @@ -56,12 +62,18 @@ see {stack-ov}/security-privileges.html[Security privileges] and ==== {api-query-parms-title} `allow_no_match` (Optional):: - (boolean) Specifies what to do when the request contains a wildcard expression - and there are no {dataframe-transforms} that match. The default value is - `true`, which returns an empty `transforms` array in this scenario. If it's - `false`, the request returns a `404` status code when there are no matches. - This parameter also affects requests that include the `_all` string or that - do not include any identifiers. + (boolean) Specifies what to do when the request: ++ +-- +* Contains wildcard expressions and there are no {dataframe-transforms} that match. +* Contains the `_all` string or no identifiers and there are no matches. +* Contains wildcard expressions and there are only partial matches. + +The default value is `true`, which returns an empty `transforms` array when +there are no matches and the subset of results when there are partial matches. +If this parameter is `false`, the request returns a `404` status code when there +are no matches or only partial matches. +-- `from` (Optional):: (integer) Skips the specified number of {dataframe-transforms}. The @@ -82,9 +94,9 @@ see {stack-ov}/security-privileges.html[Security privileges] and [[get-data-frame-transform-stats-response-codes]] ==== {api-response-codes-title} -`404`:: +`404` (Missing resources):: If `allow_no_match` is `false`, this code indicates that there are no - resources that match the request. + resources that match the request or only partial matches for the request. [discrete] [[get-data-frame-transform-stats-example]] diff --git a/docs/reference/data-frames/apis/get-transform.asciidoc b/docs/reference/data-frames/apis/get-transform.asciidoc index 70a2c259fe178..9c550d5ea1638 100644 --- a/docs/reference/data-frames/apis/get-transform.asciidoc +++ b/docs/reference/data-frames/apis/get-transform.asciidoc @@ -36,6 +36,16 @@ If the {es} {security-features} are enabled, you must have see {stack-ov}/security-privileges.html[Security privileges] and {stack-ov}/built-in-roles.html[Built-in roles]. +[discrete] +[[get-data-frame-transform-desc]] +===== {api-description-title} + +You can get information for multiple {dataframe-transforms} in a single API +request by using a comma-separated list of identifiers or a wildcard expression. +You can get information for all {dataframe-transforms} by using `_all`, by +specifying `*` as the ``, or by omitting the +``. + [discrete] [[get-data-frame-transform-path-parms]] ==== {api-path-parms-title} @@ -51,12 +61,18 @@ see {stack-ov}/security-privileges.html[Security privileges] and ==== {api-query-parms-title} `allow_no_match` (Optional):: - (boolean) Specifies what to do when the request contains a wildcard expression - and there are no {dataframe-transforms} that match. The default value is - `true`, which returns an empty `transforms` array in this scenario. If it's - `false`, the request returns a `404` status code when there are no matches. - This parameter also affects requests that include the `_all` string or that - do not include any identifiers. +(boolean) Specifies what to do when the request: ++ +-- +* Contains wildcard expressions and there are no {dataframe-transforms} that match. +* Contains the `_all` string or no identifiers and there are no matches. +* Contains wildcard expressions and there are only partial matches. + +The default value is `true`, which returns an empty `transforms` array when +there are no matches and the subset of results when there are partial matches. +If this parameter is `false`, the request returns a `404` status code when there +are no matches or only partial matches. +-- `from` (Optional):: (integer) Skips the specified number of {dataframe-transforms}. The @@ -77,9 +93,9 @@ see {stack-ov}/security-privileges.html[Security privileges] and [[get-data-frame-transform-response-codes]] ==== {api-response-codes-title} -`404`:: +`404` (Missing resources):: If `allow_no_match` is `false`, this code indicates that there are no - resources that match the request. + resources that match the request or only partial matches for the request. [discrete] [[get-data-frame-transform-example]] diff --git a/docs/reference/data-frames/apis/stop-transform.asciidoc b/docs/reference/data-frames/apis/stop-transform.asciidoc index 8538788302e7f..c0fe77f74fa8e 100644 --- a/docs/reference/data-frames/apis/stop-transform.asciidoc +++ b/docs/reference/data-frames/apis/stop-transform.asciidoc @@ -55,12 +55,23 @@ All {dataframe-transforms} can be stopped by using `_all` or `*` as the ==== {api-query-parms-title} `allow_no_match` (Optional):: - (boolean) Specifies what to do when the request contains a wildcard expression - and there are no {dataframe-transforms} that match. The default value is - `true`, which returns an empty `transforms` array in this scenario. If it's - `false`, the request returns a `404` status code when there are no matches. - This parameter also affects requests that include the `_all` string or that - do not include any identifiers. +(boolean) Specifies what to do when the request: ++ +-- +* Contains wildcard expressions and there are no {dataframe-transforms} that match. +* Contains the `_all` string or no identifiers and there are no matches. +* Contains wildcard expressions and there are only partial matches. + +The default value is `true`, which returns a successful acknowledgement message +when there are no matches. When there are only partial matches, the API stops +the appropriate {dataframe-transforms}. For example, if the request contains +`test-id1*,test-id2*` as the identifiers and there are no {dataframe-transforms} +that match `test-id2*`, the API nonetheless stops the {dataframe-transforms} +that match `test-id1`. + +If this parameter is `false`, the request returns a `404` status code when there +are no matches or only partial matches. +-- `timeout` (Optional):: (time value) If `wait_for_completion=true`, the API blocks for (at maximum) @@ -79,9 +90,9 @@ All {dataframe-transforms} can be stopped by using `_all` or `*` as the [[stop-data-frame-transform-response-codes]] ==== {api-response-codes-title} -`404`:: +`404` (Missing resources):: If `allow_no_match` is `false`, this code indicates that there are no - resources that match the request. + resources that match the request or only partial matches for the request. [discrete] [[stop-data-frame-transform-example]] From 3d19a0a138c7ce95ab7724adb2e80e0b6d4a1a7a Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 27 Jun 2019 13:46:54 -0700 Subject: [PATCH 3/5] [DOCS] More minor fixes --- docs/reference/data-frames/apis/get-transform-stats.asciidoc | 2 +- docs/reference/data-frames/apis/get-transform.asciidoc | 2 +- docs/reference/data-frames/apis/stop-transform.asciidoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/data-frames/apis/get-transform-stats.asciidoc b/docs/reference/data-frames/apis/get-transform-stats.asciidoc index 4934144c469ab..cba0e286f30dd 100644 --- a/docs/reference/data-frames/apis/get-transform-stats.asciidoc +++ b/docs/reference/data-frames/apis/get-transform-stats.asciidoc @@ -39,7 +39,7 @@ see {stack-ov}/security-privileges.html[Security privileges] and [discrete] [[get-data-frame-transform-stats-desc]] -===== {api-description-title} +==== {api-description-title} You can get statistics for multiple {dataframe-transforms} in a single API request by using a comma-separated list of identifiers or a wildcard expression. diff --git a/docs/reference/data-frames/apis/get-transform.asciidoc b/docs/reference/data-frames/apis/get-transform.asciidoc index 9c550d5ea1638..f0dc1e791032b 100644 --- a/docs/reference/data-frames/apis/get-transform.asciidoc +++ b/docs/reference/data-frames/apis/get-transform.asciidoc @@ -38,7 +38,7 @@ see {stack-ov}/security-privileges.html[Security privileges] and [discrete] [[get-data-frame-transform-desc]] -===== {api-description-title} +==== {api-description-title} You can get information for multiple {dataframe-transforms} in a single API request by using a comma-separated list of identifiers or a wildcard expression. diff --git a/docs/reference/data-frames/apis/stop-transform.asciidoc b/docs/reference/data-frames/apis/stop-transform.asciidoc index c0fe77f74fa8e..4df839896fdce 100644 --- a/docs/reference/data-frames/apis/stop-transform.asciidoc +++ b/docs/reference/data-frames/apis/stop-transform.asciidoc @@ -67,7 +67,7 @@ when there are no matches. When there are only partial matches, the API stops the appropriate {dataframe-transforms}. For example, if the request contains `test-id1*,test-id2*` as the identifiers and there are no {dataframe-transforms} that match `test-id2*`, the API nonetheless stops the {dataframe-transforms} -that match `test-id1`. +that match `test-id1*`. If this parameter is `false`, the request returns a `404` status code when there are no matches or only partial matches. From 2a72b18d99953b1dd26a086abafef13a2f5d9659 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 27 Jun 2019 14:57:02 -0700 Subject: [PATCH 4/5] [DOCS] Adds bulleted lists in dataframe APIs --- docs/reference/data-frames/apis/delete-transform.asciidoc | 2 +- docs/reference/data-frames/apis/get-transform-stats.asciidoc | 2 +- docs/reference/data-frames/apis/get-transform.asciidoc | 2 +- docs/reference/data-frames/apis/preview-transform.asciidoc | 2 +- docs/reference/data-frames/apis/put-transform.asciidoc | 3 +-- docs/reference/data-frames/apis/start-transform.asciidoc | 2 +- docs/reference/data-frames/apis/stop-transform.asciidoc | 2 +- docs/reference/ml/apis/close-job.asciidoc | 2 -- 8 files changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/reference/data-frames/apis/delete-transform.asciidoc b/docs/reference/data-frames/apis/delete-transform.asciidoc index 23c70d914f08f..d772bc3c15d89 100644 --- a/docs/reference/data-frames/apis/delete-transform.asciidoc +++ b/docs/reference/data-frames/apis/delete-transform.asciidoc @@ -22,7 +22,7 @@ Deletes an existing {dataframe-transform}. [[delete-data-frame-transform-prereqs]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in `data_frame_transforms_admin` role has these privileges. For more information, see {stack-ov}/security-privileges.html[Security privileges] and diff --git a/docs/reference/data-frames/apis/get-transform-stats.asciidoc b/docs/reference/data-frames/apis/get-transform-stats.asciidoc index cba0e286f30dd..889a109b8a376 100644 --- a/docs/reference/data-frames/apis/get-transform-stats.asciidoc +++ b/docs/reference/data-frames/apis/get-transform-stats.asciidoc @@ -31,7 +31,7 @@ Retrieves usage information for {dataframe-transforms}. [[get-data-frame-transform-stats-prereqs]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `monitor_data_frame_transforms` cluster privileges to use this API. The built-in `data_frame_transforms_user` role has these privileges. For more information, see {stack-ov}/security-privileges.html[Security privileges] and diff --git a/docs/reference/data-frames/apis/get-transform.asciidoc b/docs/reference/data-frames/apis/get-transform.asciidoc index fb9373de3899b..bf7901c191e33 100644 --- a/docs/reference/data-frames/apis/get-transform.asciidoc +++ b/docs/reference/data-frames/apis/get-transform.asciidoc @@ -30,7 +30,7 @@ Retrieves configuration information for {dataframe-transforms}. [[get-data-frame-transform-prereqs]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `monitor_data_frame_transforms` cluster privileges to use this API. The built-in `data_frame_transforms_user` role has these privileges. For more information, see {stack-ov}/security-privileges.html[Security privileges] and diff --git a/docs/reference/data-frames/apis/preview-transform.asciidoc b/docs/reference/data-frames/apis/preview-transform.asciidoc index 4e11fd5eda231..5dfe1f2f1d726 100644 --- a/docs/reference/data-frames/apis/preview-transform.asciidoc +++ b/docs/reference/data-frames/apis/preview-transform.asciidoc @@ -22,7 +22,7 @@ Previews a {dataframe-transform}. [[preview-data-frame-transform-prereq]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in `data_frame_transforms_admin` role has these privileges. You must also have `read` and `view_index_metadata` privileges on the source index for the diff --git a/docs/reference/data-frames/apis/put-transform.asciidoc b/docs/reference/data-frames/apis/put-transform.asciidoc index 3c6a5251bffd8..eb3d447518c50 100644 --- a/docs/reference/data-frames/apis/put-transform.asciidoc +++ b/docs/reference/data-frames/apis/put-transform.asciidoc @@ -22,7 +22,7 @@ Instantiates a {dataframe-transform}. [[put-data-frame-transform-prereqs]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in `data_frame_transforms_admin` role has these privileges. You must also have `read` and `view_index_metadata` privileges on the source index and `read`, @@ -30,7 +30,6 @@ have `read` and `view_index_metadata` privileges on the source index and `read`, information, see {stack-ov}/security-privileges.html[Security privileges] and {stack-ov}/built-in-roles.html[Built-in roles]. - [discrete] [[put-data-frame-transform-desc]] ===== {api-description-title} diff --git a/docs/reference/data-frames/apis/start-transform.asciidoc b/docs/reference/data-frames/apis/start-transform.asciidoc index e7ae0353f5ca6..b76bcb0dd4796 100644 --- a/docs/reference/data-frames/apis/start-transform.asciidoc +++ b/docs/reference/data-frames/apis/start-transform.asciidoc @@ -22,7 +22,7 @@ Starts one or more {dataframe-transforms}. [[start-data-frame-transform-prereqs]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. You must also have `view_index_metadata` privileges on the source index for the {dataframe-transform}. For more information, see diff --git a/docs/reference/data-frames/apis/stop-transform.asciidoc b/docs/reference/data-frames/apis/stop-transform.asciidoc index 1eb247b2de93b..80c2654babe0d 100644 --- a/docs/reference/data-frames/apis/stop-transform.asciidoc +++ b/docs/reference/data-frames/apis/stop-transform.asciidoc @@ -26,7 +26,7 @@ Stops one or more {dataframe-transforms}. [[stop-data-frame-transform-prereq]] ==== {api-prereq-title} -If the {es} {security-features} are enabled, you must have +* If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in `data_frame_transforms_admin` role has these privileges. For more information, see {stack-ov}/security-privileges.html[Security privileges] and diff --git a/docs/reference/ml/apis/close-job.asciidoc b/docs/reference/ml/apis/close-job.asciidoc index 8eb78cff0064e..2a38648e48fe5 100644 --- a/docs/reference/ml/apis/close-job.asciidoc +++ b/docs/reference/ml/apis/close-job.asciidoc @@ -12,7 +12,6 @@ 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. -[discrete] [[ml-close-job-request]] ==== {api-request-title} @@ -55,7 +54,6 @@ after the close job API returns. The `force` query parameter should only be use situations where the job has already failed, or where you are not interested in results the job might have recently produced or might produce in the future. -[discrete] [[ml-close-job-path-parms]] ==== {api-path-parms-title} From 7eae945adb89ff78024ecbfe5a7270fb27f25793 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 27 Jun 2019 15:01:35 -0700 Subject: [PATCH 5/5] [DOCS] Fixes section level in dataframe API --- docs/reference/data-frames/apis/put-transform.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/data-frames/apis/put-transform.asciidoc b/docs/reference/data-frames/apis/put-transform.asciidoc index eb3d447518c50..6910cb85a25f5 100644 --- a/docs/reference/data-frames/apis/put-transform.asciidoc +++ b/docs/reference/data-frames/apis/put-transform.asciidoc @@ -32,7 +32,7 @@ information, see {stack-ov}/security-privileges.html[Security privileges] and [discrete] [[put-data-frame-transform-desc]] -===== {api-description-title} +==== {api-description-title} IMPORTANT: You must use {kib} or this API to create a {dataframe-transform}. Do not put a {dataframe-transform} directly into any