From ad84059db6b1b3e0d494d38e2ebc69e6fabfd49d Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 26 Jun 2019 13:46:21 -0700 Subject: [PATCH] [DOCS] Updates data frame APIs to use API template (#43610) --- .../apis/delete-transform.asciidoc | 35 ++++---- .../apis/get-transform-stats.asciidoc | 81 ++++++++++-------- .../data-frames/apis/get-transform.asciidoc | 79 ++++++++++-------- .../apis/preview-transform.asciidoc | 34 ++++---- .../data-frames/apis/put-transform.asciidoc | 83 +++++++++++-------- .../data-frames/apis/start-transform.asciidoc | 31 +++---- .../data-frames/apis/stop-transform.asciidoc | 83 +++++++++++-------- 7 files changed, 242 insertions(+), 184 deletions(-) diff --git a/docs/reference/data-frames/apis/delete-transform.asciidoc b/docs/reference/data-frames/apis/delete-transform.asciidoc index 77c74b95c43..7cc911e91ac 100644 --- a/docs/reference/data-frames/apis/delete-transform.asciidoc +++ b/docs/reference/data-frames/apis/delete-transform.asciidoc @@ -12,21 +12,15 @@ beta[] Deletes an existing {dataframe-transform}. - -==== Request +[discrete] +[[delete-data-frame-transform-request]] +==== {api-request-title} `DELETE _data_frame/transforms/` -==== Description - -NOTE: Before you can delete the {dataframe-transform}, you must stop it. - -==== Path Parameters - -`data_frame_transform_id` (required):: - (string) Identifier for the {dataframe-transform}. - -==== Authorization +[discrete] +[[delete-data-frame-transform-prereqs]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in @@ -34,9 +28,22 @@ 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]. -==== Examples +[discrete] +[[delete-data-frame-transform-desc]] +==== {api-description-title} -The following example deletes the `ecommerce_transform` {dataframe-transform}: +NOTE: Before you can delete the {dataframe-transform}, you must stop it. + +[discrete] +[[delete-data-frame-transform-path-parms]] +==== {api-path-parms-title} + +`` (Required):: + (string) Identifier for the {dataframe-transform}. + +[discrete] +[[delete-data-frame-transform-examples]] +==== {api-example-title} [source,js] -------------------------------------------------- diff --git a/docs/reference/data-frames/apis/get-transform-stats.asciidoc b/docs/reference/data-frames/apis/get-transform-stats.asciidoc index ff7e023d20f..5751c8a3ea7 100644 --- a/docs/reference/data-frames/apis/get-transform-stats.asciidoc +++ b/docs/reference/data-frames/apis/get-transform-stats.asciidoc @@ -12,8 +12,9 @@ beta[] Retrieves usage information for {dataframe-transforms}. - -==== Request +[discrete] +[[get-data-frame-transform-stats-request]] +==== {api-request-title} `GET _data_frame/transforms//_stats` @@ -26,38 +27,9 @@ Retrieves usage information for {dataframe-transforms}. `GET _data_frame/transforms/*/_stats` + -//===== Description - -==== Path Parameters - -`data_frame_transform_id`:: - (string) Identifier for the {dataframe-transform}. It can be a - {dataframe-transform} identifier or a wildcard expression. If you do not - specify one of these options, the API returns information for all - {dataframe-transforms}. - -==== Query Parameters - -`from`:: - (integer) Skips the specified number of {dataframe-transforms}. The - default value is `0`. - -`size`:: - (integer) Specifies the maximum number of {dataframe-transforms} to obtain. The default value is `100`. - -`allow_no_match`:: - (boolean) Whether to ignore if a wildcard expression matches no data frame transforms. - This includes `_all` string or when no transforms have been specified. The default is `true`. - -==== Results - -The API returns the following information: - -`transforms`:: - (array) An array of statistics objects for {dataframe-transforms}, which are - sorted by the `id` value in ascending order. - -==== Authorization +[discrete] +[[get-data-frame-transform-stats-prereqs]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `monitor_data_frame_transforms` cluster privileges to use this API. The built-in @@ -65,6 +37,47 @@ 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-path-parms]] +==== {api-path-parms-title} + +`` (Optional):: + (string) Identifier for the {dataframe-transform}. It can be a + {dataframe-transform} identifier or a wildcard expression. If you do not + specify one of these options, the API returns information for all + {dataframe-transforms}. + +[discrete] +[[get-data-frame-transform-stats-query-parms]] +==== {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`. + +`from` (Optional):: + (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`. + +[discrete] +[[get-data-frame-transform-stats-response]] +==== {api-response-body-title} + +`transforms`:: + (array) An array of statistics objects for {dataframe-transforms}, which are + sorted by the `id` value in ascending order. + +[discrete] +[[get-data-frame-transform-stats-example]] ==== Examples The following example skips for the first five {dataframe-transforms} and diff --git a/docs/reference/data-frames/apis/get-transform.asciidoc b/docs/reference/data-frames/apis/get-transform.asciidoc index 7a9e86cb520..9dd0ff092d7 100644 --- a/docs/reference/data-frames/apis/get-transform.asciidoc +++ b/docs/reference/data-frames/apis/get-transform.asciidoc @@ -12,8 +12,9 @@ beta[] Retrieves configuration information for {dataframe-transforms}. - -==== Request +[discrete] +[[get-data-frame-transform-request]] +==== {api-request-title} `GET _data_frame/transforms/` + @@ -25,38 +26,9 @@ Retrieves configuration information for {dataframe-transforms}. `GET _data_frame/transforms/*` -//===== Description - -==== Path Parameters - -`data_frame_transform_id`:: - (string) Identifier for the {dataframe-transform}. It can be a - {dataframe-transform} identifier or a wildcard expression. If you do not - specify one of these options, the API returns information for all - {dataframe-transforms}. - -==== Query Parameters - -`from`:: - (integer) Skips the specified number of {dataframe-transforms}. The - default value is `0`. - -`size`:: - (integer) Specifies the maximum number of {dataframe-transforms} to obtain. The default value is `100`. - -`allow_no_match`:: - (boolean) Whether to ignore if a wildcard expression matches no data frame transforms. - This includes `_all` string or when no transforms have been specified. The default is `true`. - -==== Results - -The API returns the following information: - -`transforms`:: - (array) An array of transform resources, which are sorted by the `id` value in - ascending order. - -==== Authorization +[discrete] +[[get-data-frame-transform-prereqs]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `monitor_data_frame_transforms` cluster privileges to use this API. The built-in @@ -64,7 +36,44 @@ 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]. -==== Examples +[discrete] +[[get-data-frame-transform-path-parms]] +==== {api-path-parms-title} + +`` (Optional):: + (string) Identifier for the {dataframe-transform}. It can be a + {dataframe-transform} identifier or a wildcard expression. If you do not + specify one of these options, the API returns information for all + {dataframe-transforms}. + +[discrete] +[[get-data-frame-transform-query-parms]] +==== {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`. + +`from` (Optional):: + (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`. + +[discrete] +[[get-data-frame-transform-response]] +==== {api-response-body-title} + +`transforms`:: + (array) An array of transform resources, which are sorted by the `id` value in + ascending order. + +[discrete] +[[get-data-frame-transform-example]] +==== {api-example-title} The following example retrieves information about a maximum of ten transforms: diff --git a/docs/reference/data-frames/apis/preview-transform.asciidoc b/docs/reference/data-frames/apis/preview-transform.asciidoc index dd8fb6d74d3..d4f2a9e6a12 100644 --- a/docs/reference/data-frames/apis/preview-transform.asciidoc +++ b/docs/reference/data-frames/apis/preview-transform.asciidoc @@ -12,22 +12,15 @@ beta[] Previews a {dataframe-transform}. - -==== Request +[discrete] +[[preview-data-frame-transform-request]] +==== {api-request-title} `POST _data_frame/transforms/_preview` -//==== Description -//==== Path Parameters - -==== Request Body - -`source`:: The source index or index pattern. - -`pivot`:: Defines the pivot function `group by` fields and the aggregation to -reduce the data. - -==== Authorization +[discrete] +[[preview-data-frame-transform-prereq]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in @@ -37,10 +30,19 @@ If the {es} {security-features} are enabled, you must have {stack-ov}/security-privileges.html[Security privileges] and {stack-ov}/built-in-roles.html[Built-in roles]. -==== Examples +[discrete] +[[preview-data-frame-transform-request-body]] +==== {api-request-body-title} -The following example obtains a preview of a {dataframe-transform} on the {kib} -eCommerce sample data: +`source` (Required):: + (object) The source index or index pattern. + +`pivot` (Required):: + (object) Defines the pivot function `group by` fields and the aggregation to + reduce the data. See <>. + +[discrete] +==== {api-example-title} [source,js] -------------------------------------------------- diff --git a/docs/reference/data-frames/apis/put-transform.asciidoc b/docs/reference/data-frames/apis/put-transform.asciidoc index 93ce6db6df3..a24cc7d2245 100644 --- a/docs/reference/data-frames/apis/put-transform.asciidoc +++ b/docs/reference/data-frames/apis/put-transform.asciidoc @@ -12,42 +12,15 @@ beta[] Instantiates a {dataframe-transform}. - -==== Request +[discrete] +[[put-data-frame-transform-request]] +==== {api-request-title} `PUT _data_frame/transforms/` -===== Description - -IMPORTANT: You must use {kib} or this API to create a {dataframe-transform}. - Do not put a {dataframe-transform} directly into any - `.data-frame-internal*` indices using the Elasticsearch index API. - If {es} {security-features} are enabled, do not give users any - privileges on `.data-frame-internal*` indices. - -==== Path Parameters - -`data_frame_transform_id` (required):: - (string) Identifier for the {dataframe-transform}. This identifier can contain - lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It - must start and end with alphanumeric characters. - - -==== Request Body - -`source` (required):: (object) The source configuration, consisting of `index` and optionally -a `query`. - -`dest` (required):: (object) The destination configuration, consisting of `index` and optionally a -`pipeline` id. - -`pivot`:: (object) Defines the pivot function `group by` fields and the aggregation to -reduce the data. See <>. - -`description`:: Optional free text description of the data frame transform - - -==== Authorization +[discrete] +[[put-data-frame-transform-prereqs]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in @@ -57,10 +30,48 @@ 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]. -==== Examples -The following example creates a {dataframe-transform} for the {kib} eCommerce -sample data: +[discrete] +[[put-data-frame-transform-desc]] +===== {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 + `.data-frame-internal*` indices using the Elasticsearch index API. + If {es} {security-features} are enabled, do not give users any + privileges on `.data-frame-internal*` indices. + +[discrete] +[[put-data-frame-transform-path-parms]] +==== {api-path-parms-title} + +`` (Required):: + (string) Identifier for the {dataframe-transform}. This identifier can contain + lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It + must start and end with alphanumeric characters. + +[discrete] +[[put-data-frame-transform-request-body]] +==== {api-request-body-title} + +`description` (Optional):: + (string) Free text description of the {dataframe-transform}. + +`dest` (Required):: + (object) The destination configuration, which consists of `index` and + optionally a `pipeline` id. + +`pivot` (Optional):: + (object) Defines the pivot function `group by` fields and the aggregation to + reduce the data. See <>. + +`source` (Required):: + (object) The source configuration, which consists of `index` and optionally + a `query`. + +[discrete] +[[put-data-frame-transform-example]] +==== {api-example-title} [source,js] -------------------------------------------------- diff --git a/docs/reference/data-frames/apis/start-transform.asciidoc b/docs/reference/data-frames/apis/start-transform.asciidoc index 7baefb34ee3..059f8a63414 100644 --- a/docs/reference/data-frames/apis/start-transform.asciidoc +++ b/docs/reference/data-frames/apis/start-transform.asciidoc @@ -12,21 +12,15 @@ beta[] Starts one or more {dataframe-transforms}. -==== Request +[discrete] +[[start-data-frame-transform-request]] +==== {api-request-title} `POST _data_frame/transforms//_start` -//==== Description - -==== Path Parameters - -`data_frame_transform_id` (required):: - (string) Identifier for the {dataframe-transform}. This identifier can contain - lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It - must start and end with alphanumeric characters. - -//==== Request Body -==== Authorization +[discrete] +[[start-data-frame-transform-prereqs]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. You must also @@ -35,9 +29,18 @@ have `view_index_metadata` privileges on the source index for the {stack-ov}/security-privileges.html[Security privileges] and {stack-ov}/built-in-roles.html[Built-in roles]. -==== Examples +[discrete] +[[start-data-frame-transform-path-parms]] +==== {api-path-parms-title} -The following example starts the `ecommerce_transform` {dataframe-transform}: +`` (Required):: + (string) Identifier for the {dataframe-transform}. This identifier can contain + lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It + must start and end with alphanumeric characters. + +[discrete] +[[start-data-frame-transform-example]] +==== {api-example-title} [source,js] -------------------------------------------------- diff --git a/docs/reference/data-frames/apis/stop-transform.asciidoc b/docs/reference/data-frames/apis/stop-transform.asciidoc index 3620c24a88d..4ade2706ab2 100644 --- a/docs/reference/data-frames/apis/stop-transform.asciidoc +++ b/docs/reference/data-frames/apis/stop-transform.asciidoc @@ -12,7 +12,9 @@ beta[] Stops one or more {dataframe-transforms}. -==== Request +[discrete] +[[stop-data-frame-transform-request]] +==== {api-request-title} `POST _data_frame/transforms//_stop` + @@ -20,38 +22,9 @@ Stops one or more {dataframe-transforms}. `POST _data_frame/transforms/_all/_stop` - -==== Description -You can stop multiple {dataframe-transforms} in a single API request by using a -comma-separated list of {dataframe-transforms} or a wildcard expression. -All {dataframe-transforms} can be stopped by using `_all` or `*` as the ``. - -==== Path Parameters - -`data_frame_transform_id` (required):: - (string) Identifier for the {dataframe-transform}. This identifier can contain - lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It - must start and end with alphanumeric characters. - -==== Query Parameters - -`wait_for_completion`:: - (boolean) If set to true, causes the API to block until the indexer state completely stops. If set to false, the API returns immediately and the indexer will be stopped asynchronously in the background. Defaults to `false`. - - `timeout`:: - (time value) If `wait_for_completion=true`, the API blocks for (at maximum) - the specified duration while waiting for the transform to stop. If more than - `timeout` time has passed, the API throws a timeout exception. Even if a - timeout exception is thrown, the stop request is still processing and - eventually moves the transform to `STOPPED`. The timeout simply means the API - call itself timed out while waiting for the status change. Defaults to `30s` - - `allow_no_match`:: - (boolean) Whether to ignore if a wildcard expression matches no data frame transforms. - This includes `_all` string or when no transforms have been specified. The default is `true`. - -//==== Request Body -==== Authorization +[discrete] +[[stop-data-frame-transform-prereq]] +==== {api-prereq-title} If the {es} {security-features} are enabled, you must have `manage_data_frame_transforms` cluster privileges to use this API. The built-in @@ -59,9 +32,49 @@ 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]. -==== Examples +[discrete] +[[stop-data-frame-transform-desc]] +==== {api-description-title} -The following example stops the `ecommerce_transform` {dataframe-transform}: +You can stop multiple {dataframe-transforms} in a single API request by using a +comma-separated list of {dataframe-transforms} or a wildcard expression. +All {dataframe-transforms} can be stopped by using `_all` or `*` as the +``. + +[discrete] +[[stop-data-frame-transform-path-parms]] +==== {api-path-parms-title} + +`` (Required):: + (string) Identifier for the {dataframe-transform}. This identifier can contain + lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It + must start and end with alphanumeric characters. + +[discrete] +[[stop-data-frame-transform-query-parms]] +==== {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`. + +`timeout` (Optional):: + (time value) If `wait_for_completion=true`, the API blocks for (at maximum) + the specified duration while waiting for the transform to stop. If more than + `timeout` time has passed, the API throws a timeout exception. Even if a + timeout exception is thrown, the stop request is still processing and + eventually moves the transform to `STOPPED`. The timeout simply means the API + call itself timed out while waiting for the status change. Defaults to `30s` + +`wait_for_completion` (Optional):: + (boolean) If set to `true`, causes the API to block until the indexer state + 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-example]] +==== {api-example-title} [source,js] --------------------------------------------------