[DOC] document transform settings and docs_per_second (#56178)

add documentation for throttling, added in #56007

Author: Hendrik Muhs

docs/reference/cat/transforms.asciidoc

@@ -102,7 +102,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=exponential-avg-documents-i
 
 `max_page_search_size`, `mpsz`:::
 (Default)
-include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-max-page-search-size]
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-max-page-search-size]
 
 `pages_processed`, `pp`:::
 include::{docdir}/rest-api/common-parms.asciidoc[tag=pages-processed]

docs/reference/rest-api/common-parms.asciidoc

@@ -689,13 +689,6 @@ Defines how to group the data. More than one grouping can be defined
 --
 end::pivot-group-by[]
 
-tag::pivot-max-page-search-size[]
-Defines the initial page size to use for the composite aggregation for each
-checkpoint. If circuit breaker exceptions occur, the page size is dynamically
-adjusted to a lower value. The minimum value is `10` and the maximum is `10,000`.
-The default value is `500`.
-end::pivot-max-page-search-size[]
-
 tag::positions[]
 `positions`::
 (Optional, boolean) If `true`, the response includes term positions.
@@ -941,6 +934,25 @@ The time delay between the current time and the latest input data time. The
 default value is `60s`.
 end::sync-time-delay[]
 
+tag::transform-settings[]
+Defines the settings of the {transform}.
+end::transform-settings[]
+
+tag::transform-settings-docs-per-second[]
+Set `docs-per-second` to throttle the rate transform is issuing search and
+index requests. Throttling slows down search requests by adding a wait time
+between searches. For the number of docs, the number of input documents is taken.
+Throttling can be disabled by setting it to `null`.
+The default is no throttling, value `null`.
+end::transform-settings-docs-per-second[]
+
+tag::transform-settings-max-page-search-size[]
+Defines the initial page size to use for the composite aggregation for each
+checkpoint. If circuit breaker exceptions occur, the page size is dynamically
+adjusted to a lower value. The minimum value is `10` and the maximum is `10,000`.
+The default value is `500`.
+end::transform-settings-max-page-search-size[]
+
 tag::target-index[]
 `<target-index>`::
 +

docs/reference/transform/apis/preview-transform.asciidoc

@@ -93,10 +93,6 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-aggs]
 `group_by`:::
 (Required, object)
 include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-group-by]
-
-`max_page_search_size`:::
-(Optional, integer)
-include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-max-page-search-size]
 ====
 //End pivot
 
@@ -149,6 +145,23 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=sync-time-field]
 ====
 //End sync
 
+//Begin settings
+`settings`::
+(Optional, object)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings]
++
+.Properties of `settings`
+[%collapsible%open]
+====
+`docs_per_second`:::
+(Optional, float)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-docs-per-second]
+`max_page_search_size`:::
+(Optional, integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-max-page-search-size]
+====
+//End settings
+
 [role="child_attributes"]
 [[preview-transform-response]]
 ==== {api-response-body-title}

docs/reference/transform/apis/put-transform.asciidoc

@@ -125,9 +125,6 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-aggs]
 (Required, object)
 include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-group-by]
 
-`max_page_search_size`:::
-(Optional, integer)
-include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-max-page-search-size]
 ====
 //End pivot
 
@@ -188,6 +185,24 @@ delays.
 ====
 //End sync
 
+//Begin settings
+`settings`::
+(Optional, object)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings]
++
+.Properties of `settings`
+[%collapsible%open]
+====
+`docs_per_second`:::
+(Optional, float)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-docs-per-second]
+`max_page_search_size`:::
+(Optional, integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-max-page-search-size]
+====
+//End settings
+
+
 [[put-transform-example]]
 ==== {api-examples-title}
 

docs/reference/transform/apis/update-transform.asciidoc

@@ -159,6 +159,23 @@ delays.
 ====
 //End sync
 
+//Begin settings
+`settings`::
+(Optional, object)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings]
++
+.Properties of `settings`
+[%collapsible%open]
+====
+`docs_per_second`:::
+(Optional, float)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-docs-per-second]
+`max_page_search_size`:::
+(Optional, integer)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=transform-settings-max-page-search-size]
+====
+//End settings
+
 [[update-transform-example]]
 ==== {api-examples-title}