[DOCS] Improve enrich policy execute 'wait_for_completion' docs (elas…

…tic#102291) * [DOCS] Improve enrich policy execute 'wait_for_completion' docs * Update docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc Co-authored-by: James Rodewig <[email protected]> --------- Co-authored-by: James Rodewig <[email protected]>
jakelandis · Nov 27, 2023 · ac973f0 · ac973f0
1 parent e24a909
commit ac973f0
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 10 deletions.
diff --git a/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc b/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc
@@ -37,8 +37,9 @@ PUT /_enrich/policy/my-policy
 
 [source,console]
 --------------------------------------------------
-PUT /_enrich/policy/my-policy/_execute
+PUT /_enrich/policy/my-policy/_execute?wait_for_completion=false
 --------------------------------------------------
+// TEST[s/\?wait_for_completion=false//]
 
 ////
 [source,console]
@@ -93,8 +94,13 @@ The previous enrich index will deleted with a delayed maintenance job.
 By default this is done every 15 minutes. 
 // end::update-enrich-index[]
 
-Because this API request performs several operations,
-it may take a while to return a response.
+By default, this API is synchronous: It returns when a policy has been executed.
+Because executing a policy performs several operations, it may take a while to
+return a response, especially when the source indices are large. This can lead
+to timeouts. To prevent timeouts, set the `wait_for_completion` parameter to
+`false`. This runs the request asynchronously in the background, and returns a
+task ID. You can use the task ID to manage the request with the <<tasks,task
+management API>>.
 
 [[execute-enrich-policy-api-path-params]]
 ==== {api-path-parms-title}
@@ -107,6 +113,7 @@ Enrich policy to execute.
 ==== {api-query-parms-title}
 
 `wait_for_completion`::
-(Required, Boolean)
-If `true`, the request blocks other enrich policy execution requests until
-complete. Defaults to `true`.
+(Optional, Boolean)
+If `true`, the request blocks until execution is complete. If `false`, the
+request returns immediately and execution runs asynchronously in the background.
+Defaults to `true`.
diff --git a/docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc b/docs/reference/ingest/geo-match-enrich-policy-type-ex.asciidoc
@@ -72,8 +72,9 @@ enrich index for the policy.
 
 [source,console]
 ----
-POST /_enrich/policy/postal_policy/_execute
+POST /_enrich/policy/postal_policy/_execute?wait_for_completion=false
 ----
+// TEST[s/\?wait_for_completion=false//]
 // TEST[continued]
 
 Use the <<put-pipeline-api,create or update pipeline API>> to create an ingest

diff --git a/docs/reference/ingest/match-enrich-policy-type-ex.asciidoc b/docs/reference/ingest/match-enrich-policy-type-ex.asciidoc
@@ -58,8 +58,9 @@ enrich index for the policy.
 
 [source,console]
 ----
-POST /_enrich/policy/users-policy/_execute
+POST /_enrich/policy/users-policy/_execute?wait_for_completion=false
 ----
+// TEST[s/\?wait_for_completion=false//]
 // TEST[continued]
 
 

diff --git a/docs/reference/ingest/range-enrich-policy-type-ex.asciidoc b/docs/reference/ingest/range-enrich-policy-type-ex.asciidoc
@@ -70,8 +70,9 @@ enrich index for the policy.
 
 [source,console]
 ----
-POST /_enrich/policy/networks-policy/_execute
+POST /_enrich/policy/networks-policy/_execute?wait_for_completion=false
 ----
+// TEST[s/\?wait_for_completion=false//]
 // TEST[continued]
 
 

diff --git a/docs/reference/tab-widgets/esql/esql-getting-started-enrich-policy.asciidoc b/docs/reference/tab-widgets/esql/esql-getting-started-enrich-policy.asciidoc
@@ -41,8 +41,9 @@ PUT /_enrich/policy/clientip_policy
   }
 }
 
-PUT /_enrich/policy/clientip_policy/_execute
+PUT /_enrich/policy/clientip_policy/_execute?wait_for_completion=false
 ----
+// TEST[s/\?wait_for_completion=false//]
 
 ////
 [source,console]