From 9bd0069c5c7e69e28d9060e2d2434198423772e1 Mon Sep 17 00:00:00 2001 From: Abdon Pijpelink Date: Thu, 16 Nov 2023 10:55:54 +0100 Subject: [PATCH 1/2] [DOCS] Improve enrich policy execute 'wait_for_completion' docs --- .../enrich/execute-enrich-policy.asciidoc | 19 +++++++++++++------ .../geo-match-enrich-policy-type-ex.asciidoc | 3 ++- .../match-enrich-policy-type-ex.asciidoc | 3 ++- .../range-enrich-policy-type-ex.asciidoc | 3 ++- ...sql-getting-started-enrich-policy.asciidoc | 3 ++- 5 files changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc b/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc index ee3af9c21de8f..e277d87baf730 100644 --- 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 those, 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 <>. [[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 index 6ba601e55ebe0..38c695c0b0667 100644 --- 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 <> 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 index 306e69577c426..ed75d15df853e 100644 --- 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 index 390360a640ea3..f11a95a6c5fe4 100644 --- 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 index 39560c7500b42..a1898dffda684 100644 --- 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] From cb5002bebe3f8d6a0b71b0bc36827f4db5a4c026 Mon Sep 17 00:00:00 2001 From: Abdon Pijpelink Date: Thu, 16 Nov 2023 13:54:09 +0100 Subject: [PATCH 2/2] Update docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc Co-authored-by: James Rodewig --- .../ingest/apis/enrich/execute-enrich-policy.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc b/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc index e277d87baf730..ebad9f09250d3 100644 --- a/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc +++ b/docs/reference/ingest/apis/enrich/execute-enrich-policy.asciidoc @@ -94,10 +94,10 @@ The previous enrich index will deleted with a delayed maintenance job. By default this is done every 15 minutes. // end::update-enrich-index[] -By default, this API is synchronous: it returns when a policy has been executed. +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 those, set the `wait_for_completion` parameter to +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 <>.