From 48b0e04fb86481e02ca987aace3491106d4139d2 Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 6 May 2025 19:23:00 -0500 Subject: [PATCH 1/5] Add async APIs. Signed-off-by: Archer --- .../asynchronous-search/async-search-stats.md | 124 +++++++++ .../create-async-search.md | 242 ++++++++++++++++++ .../delete-async-search.md | 61 +++++ .../asynchronous-search/get-async-search.md | 110 ++++++++ _api-reference/asynchronous-search/index.md | 39 +++ 5 files changed, 576 insertions(+) create mode 100644 _api-reference/asynchronous-search/async-search-stats.md create mode 100644 _api-reference/asynchronous-search/create-async-search.md create mode 100644 _api-reference/asynchronous-search/delete-async-search.md create mode 100644 _api-reference/asynchronous-search/get-async-search.md create mode 100644 _api-reference/asynchronous-search/index.md diff --git a/_api-reference/asynchronous-search/async-search-stats.md b/_api-reference/asynchronous-search/async-search-stats.md new file mode 100644 index 00000000000..ad35f742192 --- /dev/null +++ b/_api-reference/asynchronous-search/async-search-stats.md @@ -0,0 +1,124 @@ +--- +layout: default +title: Asynchronous search stats +parent: Asynchronous Search APIs +nav_order: 40 +--- + +# Asynchronous search stats +**Introduced 1.0** +{: .label .label-purple } + +The Asynchronous Search Stats API provides statistical information about asynchronous search operations across the cluster. This API helps monitor usage patterns, resource consumption, and the overall health of asynchronous search functionality by returning detailed metrics on both running and completed searches. + +These statistics can be valuable for the following actions: +- Performance monitoring and tuning +- Troubleshooting asynchronous search issues +- Capacity planning and resource allocation +- Understanding usage patterns for asynchronous searches + + +## Endpoints +```json +GET /_plugins/_asynchronous_search/{id} +``` + + +## Example request + +The following request retrieves statistics about asynchronous searches across all nodes in the cluster: + +```json +GET /_plugins/_asynchronous_search/stats +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "_nodes": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "cluster_name": "opensearch-cluster", + "nodes": { + "node1": { + "running_current": 0, + "running_count": 12, + "persisted_current": 3, + "persisted_count": 15, + "completed_count": 25, + "cancelled_count": 2, + "rejected_count": 1, + "failed_count": 3 + }, + "node2": { + "running_current": 1, + "running_count": 8, + "persisted_current": 2, + "persisted_count": 10, + "completed_count": 18, + "cancelled_count": 1, + "rejected_count": 0, + "failed_count": 2 + } + } +} +``` + +## Response body fields + +The response body is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `_nodes` | Object | Statistics about node operations and responses. | +| `cluster_name` | String | The name of the OpenSearch cluster. | +| `nodes` | Object | A map of node IDs to node-specific asynchronous search statistics. | + +
+ + Response body fields: _nodes + + {: .text-delta} + +The statistics about node operations. + +`_nodes` is a JSON object with the following fields. + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `failed` | **Required** | Integer | The number of nodes that rejected the request or failed to respond. If this value is not 0, then a reason for the rejection or failure is included in the response. | +| `successful` | **Required** | Integer | The number of nodes that responded successfully to the request. | +| `total` | **Required** | Integer | The total number of nodes selected by the request. | +| `failures` | Optional | Array of Objects | Details about any failures that occurred during the request. Present only when there are failures. | + +
+ +
+ + Response body fields: nodes + + {: .text-delta} + +A map of node IDs to node-specific asynchronous search statistics. + +Each entry in the `nodes` object contains the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `running_current` | Integer | The number of asynchronous searches currently running on this node. | +| `running_count` | Integer | The total number of asynchronous searches that have been executed on this node since it was started. | +| `persisted_current` | Integer | The number of completed asynchronous searches that are currently persisted on this node. | +| `persisted_count` | Integer | The total number of asynchronous searches that have been persisted on this node since it was started. | +| `completed_count` | Integer | The total number of asynchronous searches that have completed successfully on this node since it was started. | +| `cancelled_count` | Integer | The total number of asynchronous searches that have been cancelled on this node since it was started. | +| `rejected_count` | Integer | The total number of asynchronous searches that have been rejected on this node since it was started. | +| `failed_count` | Integer | The total number of asynchronous searches that have failed on this node since it was started. | + +
\ No newline at end of file diff --git a/_api-reference/asynchronous-search/create-async-search.md b/_api-reference/asynchronous-search/create-async-search.md new file mode 100644 index 00000000000..a15fbe4c7ae --- /dev/null +++ b/_api-reference/asynchronous-search/create-async-search.md @@ -0,0 +1,242 @@ +--- +layout: default +title: Create asynchronous search +parent: Asynchronous Search APIs +nav_order: 10 +--- + +# Create asynchronous search +**Introduced 1.0** +{: .label .label-purple } + +The Create Asynchronous Search API allows you to run search operations in the background and retrieve results later. This is especially useful for resource-intensive searches that may take a long time to complete, helping you avoid request timeouts and providing a better experience for operations involving large data volumes or complex aggregations. + +Unlike standard search operations that maintain an open HTTP connection until completion, asynchronous searches let you: + +- Submit a search request that runs in the background +- Receive a search ID immediately +- Check status or retrieve partial results as they become available +- Access the complete results once the search finishes + +You can also configure how long the search results are stored in the cluster after completion, enabling flexible retrieval based on your application's needs. + + + +## Endpoints +```json +POST /_plugins/_asynchronous_search +``` + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `index` | String | The name of the index to be searched. Can be an individual name, a comma-separated list of indexes, or a wildcard expression of index names. | +| `keep_alive` | String | The amount of time that the result is saved in the cluster. For example, `2d` means that the results are stored in the cluster for 48 hours. The saved search results are deleted after this period or if the search is canceled. Note that this includes the query execution time. If the query exceeds this amount of time, the process cancels this query automatically. | +| `keep_on_completion` | Boolean | Whether to save the results in the cluster after the search is complete. You can examine the stored results at a later time. | +| `wait_for_completion_timeout` | String | The amount of time to wait for the results. You can poll the remaining results based on an ID. The maximum value is 300 seconds. Default is `1s`. | + + + +## Request body fields + +The request body follows the standard OpenSearch Search API format using the Query DSL. + +The request body is optional. It is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `_source` | All | Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered. | +| `aggregations` | Object | Defines the aggregations that are run as part of the search request. | +| `collapse` | Object | The field to collapse search results on. | +| `docvalue_fields` | Array of objects or strings | An array of wildcard (`*`) patterns. The request returns doc values for field names matching these patterns in the `hits.fields` property of the response. | +| `explain` | Boolean | When `true`, returns detailed information about score computation as part of a hit. | +| `ext` | Object | Configuration of search extensions defined by OpenSearch plugins. | +| `fields` | Array of object or strings | Array of wildcard (`*`) patterns. The request returns values for field names matching these patterns in the `hits.fields` property of the response. | +| `from` | Float | Starting document offset. Needs to be non-negative. By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. To page through more hits, use the `search_after` parameter. | +| `highlight` | Object | Highlighting configuration for matched fields. | +| `indices_boost` | Array of objects | Boosts the `_score` of documents from specified indexes. | +| `min_score` | Float | Minimum `_score` for matching documents. Documents with a lower `_score` are not included in the search results. | +| `pit` | Object | Point-in-time context for search operations. | +| `post_filter` | Object | Filter that runs after the query and aggregations. | +| `profile` | Boolean | Set to `true` to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution. | +| `query` | Object | The query definition using the Query DSL. | +| `rank` | Object | The container for ranking configuration. | +| `script_fields` | Object | Retrieve a script evaluation (based on different fields) for each hit. | +| `search_after` | Array of Booleans, float, or strings | Enables pagination of search results beyond the 10,000 document limit of from/size. | +| `seq_no_primary_term` | Boolean | When `true`, returns sequence number and primary term of the last modification of each hit. | +| `size` | Float | The number of hits to return. By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. To page through more hits, use the `search_after` parameter. | +| `slice` | Object | The configuration for a sliced scroll request. | +| `sort` | Array of objects or strings | Valid values are:
- `_score`: Sort by document score.
- `_doc`: Sort by document index order. | +| `stats` | Array of Strings | The statistics groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indexes stats API. | +| `stored_fields` | Array of strings | A list of stored fields to retrieve. | +| `suggest` | Object | Suggests a configuration for similar looking terms. | +| `terminate_after` | Integer | The maximum number of documents to collect for each shard. If a query reaches this limit, OpenSearch terminates the query early. OpenSearch collects documents before sorting. Use with caution. OpenSearch applies this parameter to each shard handling the request. When possible, let OpenSearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indexes across multiple data tiers. If set to `0` (default), the query does not terminate early. | +| `timeout` | String | Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Default is no timeout. | +| `track_scores` | Boolean | When `true`, calculate and return document scores, even if the scores are not used for sorting. | +| `track_total_hits` | Boolean or integer | The number of hits matching the query. When `true`, the exact number of hits is returned at the cost of some performance. When `false`, the response does not include the total number of hits matching the query. Default is `10,000` hits. | +| `version` | Boolean | When `true`, returns document version as part of a hit. | + + +## Example requests + +### Basic asynchronous search + +The following example submits an asynchronous search for the term "OpenSearch" across all indices with a 2-minute wait time: + +```json +POST /_plugins/_asynchronous_search?wait_for_completion_timeout=2m&keep_alive=10m&keep_on_completion=true +{ + "query": { + "match": { + "content": "OpenSearch" + } + }, + "size": 100 +} +``` +{% include copy-curl.html %} + +### Asynchronous search with aggregations + +The following example runs an asynchronous search with both a query and aggregations: + +```json +POST /_plugins/_asynchronous_search?wait_for_completion_timeout=5s&keep_alive=1d +{ + "query": { + "range": { + "timestamp": { + "gte": "now-1d/d", + "lt": "now/d" + } + } + }, + "size": 0, + "aggs": { + "categories": { + "terms": { + "field": "category", + "size": 10 + } + } + } +} +``` +{% include copy-curl.html %} + +## Example responses + +### Response with partial results + +```json +{ + "id": "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWGJKdFQ0USsydzoxMDc=", + "state": "RUNNING", + "start_time_in_millis": 1663276896192, + "expiration_time_in_millis": 1663363296192, + "response": { + "took": 1019, + "timed_out": false, + "_shards": { + "total": 10, + "successful": 5, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 3, + "relation": "eq" + }, + "max_score": 0.9530773, + "hits": [ + { + "_index": "my-index", + "_id": "1", + "_score": 0.9530773, + "_source": { + "content": "OpenSearch is a community-driven open source search and analytics suite" + } + }, + // Additional hits omitted for brevity + ] + } + } +} +``` + +### Response for a completed search + +```json +{ + "id": "MkZ5QTVrSTZSaVN3WlNFVmtlWGJKdFQ0USsydzoxFmRldE8zREVEUzA2ZVpUeGs2ejJFUFE=", + "state": "SUCCEEDED", + "start_time_in_millis": 1663276892345, + "expiration_time_in_millis": 1663363292345, + "took": 3876, + "response": { + "took": 3876, + "timed_out": false, + "_shards": { + "total": 10, + "successful": 10, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 15, + "relation": "eq" + }, + "max_score": 2.341092, + "hits": [ + // Hits omitted for brevity + ] + }, + "aggregations": { + "categories": { + "doc_count_error_upper_bound": 0, + "sum_other_doc_count": 0, + "buckets": [ + { + "key": "documentation", + "doc_count": 7 + }, + { + "key": "blog", + "doc_count": 5 + }, + { + "key": "tutorial", + "doc_count": 3 + } + ] + } + } + } +} +``` + +## Response body fields + +The response body is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `expiration_time_in_millis` | Long | The UNIX timestamp in milliseconds when the asynchronous search results will expire and be deleted from the cluster. | +| `id` | String | The unique identifier for the asynchronous search request. Use this ID to check the status, get results, or delete the search. | +| `response` | Object | Contains the search results (if available) in the same format as a standard search response. May be empty if no results are available yet. | +| `start_time_in_millis` | Long | The UNIX timestamp in milliseconds when the asynchronous search was started. | +| `state` | String | The current state of the asynchronous search. Possible values include `RUNNING`, `SUCCEEDED`, `FAILED`, or `PERSISTED`. | +| `took` | Integer | The time in milliseconds that the search took to execute so far. | diff --git a/_api-reference/asynchronous-search/delete-async-search.md b/_api-reference/asynchronous-search/delete-async-search.md new file mode 100644 index 00000000000..214f0704507 --- /dev/null +++ b/_api-reference/asynchronous-search/delete-async-search.md @@ -0,0 +1,61 @@ +--- +layout: default +title: Delete asynchronous search +parent: Asynchronous Search APIs +nav_order: 30 +--- + +# Delete asynchronous search +**Introduced 1.0** +{: .label .label-purple } + +The Delete Asynchronous Search API allows you to manually delete an asynchronous search by its ID before its configured expiration time. This is useful for cleaning up searches that are no longer needed, freeing up resources, or removing stored results that contain sensitive information. + +When you delete an asynchronous search: + +- If the search is still running, the operation is canceled +- Any stored partial or complete results are immediately removed from the cluster +- Resources associated with the search are released + + +## Endpoints +```json +DELETE /_plugins/_asynchronous_search/{id} +``` + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `id` | **Required** | String | The ID of the asynchronous search to delete. This is the ID returned when the search was created. | + +## Example request + +The following request deletes an asynchronous search with ID `FmRldE8zREVEUzA2ZV`: + +```json +DELETE /_plugins/_asynchronous_search/FmRldE8zREVEUzA2ZV +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "acknowledged": true +} +``` + +## Response body fields + +The response body is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `acknowledged` | Boolean | Whether the delete operation was successful. Returns `true` when the asynchronous search was successfully deleted. | \ No newline at end of file diff --git a/_api-reference/asynchronous-search/get-async-search.md b/_api-reference/asynchronous-search/get-async-search.md new file mode 100644 index 00000000000..6a3bbeddcaa --- /dev/null +++ b/_api-reference/asynchronous-search/get-async-search.md @@ -0,0 +1,110 @@ +--- +layout: default +title: Get asynchronous search +parent: Asynchronous Search APIs +nav_order: 20 +--- + +# Get asynchronous search +**Introduced 1.0** +{: .label .label-purple } + +The Get Asynchronous Search API allows you to retrieve the status or results of a previously submitted asynchronous search operation. You can use this API to check whether a search has completed, retrieve partial results while it's still running, or access the final results after completion. + +This API is particularly useful in workflows where you need to: +- Monitor the progress of long-running searches +- Retrieve partial results to display incremental updates to users +- Access the final search results when ready +- Extend the expiration time of stored search results + +The API returns both metadata about the search status and any available results, with the same format as the standard search response. + + +## Endpoints +```json +GET /_plugins/_asynchronous_search/{id} +``` + + +## Path parameters + +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `id` | **Required** | String | The ID of the asynchronous search to retrieve. This is the ID returned when the search was created. | + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `keep_alive` | String | Extends the expiration time of the search results. For example, passing `2d` will extend the expiration by 2 days from the current time. If not specified, the expiration time remains unchanged. | +| `wait_for_completion_timeout` | String | The amount of time to wait for the search to complete before returning partial results. Maximum value is 300 seconds. If not specified, returns results immediately based on the current state. | + +## Example request + +The following request retrieves an asynchronous search with ID `FFj38GhYw82NsHg7` and extends its expiration time by 1 hour: + +```json +GET /_plugins/_asynchronous_search/Fj38GhYw82NsHg7keep_alive=1h +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "id": "Fj38GhYw82NsHg7", + "state": "SUCCEEDED", + "start_time_in_millis": 1663276896192, + "expiration_time_in_millis": 1663366896192, + "took": 3255, + "response": { + "took": 3255, + "timed_out": false, + "_shards": { + "total": 10, + "successful": 10, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 15, + "relation": "eq" + }, + "max_score": 1.0, + "hits": [ + { + "_index": "my-index", + "_id": "1", + "_score": 1.0, + "_source": { + "field1": "value1", + "field2": "value2" + } + }, + // Additional hits omitted for brevity + ] + } + } +} +``` + +## Response body fields + +The response body is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `expiration_time_in_millis` | Long | The UNIX timestamp in milliseconds when the asynchronous search results will expire and be deleted from the cluster. | +| `id` | String | The unique identifier for the asynchronous search request. Use this ID to check the status, get results, or delete the search. | +| `response` | Object | Contains the search results (if available) in the same format as a standard search response. May be empty if no results are available yet. | +| `start_time_in_millis` | Long | The UNIX timestamp in milliseconds when the asynchronous search was started. | +| `state` | String | The current state of the asynchronous search. Possible values include `RUNNING`, `SUCCEEDED`, `FAILED`, or `PERSISTED`. | +| `took` | Integer | The time in milliseconds that the search took to execute so far. | \ No newline at end of file diff --git a/_api-reference/asynchronous-search/index.md b/_api-reference/asynchronous-search/index.md new file mode 100644 index 00000000000..d5bc9cd8b40 --- /dev/null +++ b/_api-reference/asynchronous-search/index.md @@ -0,0 +1,39 @@ +--- +layout: default +title: Asynchronous Search APIs +nav_order: 8 +has_children: true +--- + +# Asynchronous search +**Introduced 1.0** +{: .label .label-purple } + +Asynchronous search in OpenSearch allows you to execute search operations in the background and retrieve results at a later time. This is particularly valuable for resource-intensive or long-running search operations that might otherwise time out in a synchronous context. + + +## Available APIs + +OpenSearch provides the following APIs for working with asynchronous searches. + +| API | Description | +| :--- | :--- | +| [Create asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/create-asynchronous-search/) | Submits a search that runs in the background | +| [Get asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/get-asynchronous-search/) | Retrieves status and results of a previously submitted search | +| [Delete asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/delete-asynchronous-search/) | Removes a stored asynchronous search | +| [Asynchronous search stats]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/asynchronous-search-stats/) | Provides statistics about asynchronous search operations | + + +## Performance considerations + +Asynchronous searches consume resources on the cluster. To optimize performance, remember the following considerations: + +- Set appropriate `keep_alive` values to prevent unnecessary storage. +- Use `keep_on_completion=false` if you want to retrieve results immediately. +- Monitor statistics to understand usage patterns. +- Delete searches when no longer needed. +- Consider increasing search thread pools if running many concurrent searches. + +## Security + +If you use the Security plugin, users need the `asynchronous_search_full_access` or `asynchronous_search_read_access` permission to use or view asynchronous searches. You can also define more granular permissions for specific actions. For more information, see [Asynchronous search security]({{site.url}}{{site.baseurl}}/search-plugins/async/security/). \ No newline at end of file From 6665bf1c25d9e2c92ec6291c72b5e773376ace44 Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 6 May 2025 19:34:39 -0500 Subject: [PATCH 2/5] Fix links Signed-off-by: Archer --- _api-reference/asynchronous-search/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_api-reference/asynchronous-search/index.md b/_api-reference/asynchronous-search/index.md index d5bc9cd8b40..53d4186988b 100644 --- a/_api-reference/asynchronous-search/index.md +++ b/_api-reference/asynchronous-search/index.md @@ -18,10 +18,10 @@ OpenSearch provides the following APIs for working with asynchronous searches. | API | Description | | :--- | :--- | -| [Create asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/create-asynchronous-search/) | Submits a search that runs in the background | -| [Get asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/get-asynchronous-search/) | Retrieves status and results of a previously submitted search | -| [Delete asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/delete-asynchronous-search/) | Removes a stored asynchronous search | -| [Asynchronous search stats]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/asynchronous-search-stats/) | Provides statistics about asynchronous search operations | +| [Create asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/create-async-search/) | Submits a search that runs in the background | +| [Get asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/get-async-search/) | Retrieves status and results of a previously submitted search | +| [Delete asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/delete-async-search/) | Removes a stored asynchronous search | +| [Asynchronous search stats]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/asynch-search-stats/) | Provides statistics about asynchronous search operations | ## Performance considerations From b47dea4d525537fa4ae881f9a1579bf6fcf27dcb Mon Sep 17 00:00:00 2001 From: Archer Date: Tue, 6 May 2025 20:07:03 -0500 Subject: [PATCH 3/5] Fix final link Signed-off-by: Archer --- _api-reference/asynchronous-search/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/asynchronous-search/index.md b/_api-reference/asynchronous-search/index.md index 53d4186988b..b51947f2933 100644 --- a/_api-reference/asynchronous-search/index.md +++ b/_api-reference/asynchronous-search/index.md @@ -21,7 +21,7 @@ OpenSearch provides the following APIs for working with asynchronous searches. | [Create asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/create-async-search/) | Submits a search that runs in the background | | [Get asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/get-async-search/) | Retrieves status and results of a previously submitted search | | [Delete asynchronous search]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/delete-async-search/) | Removes a stored asynchronous search | -| [Asynchronous search stats]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/asynch-search-stats/) | Provides statistics about asynchronous search operations | +| [Asynchronous search stats]({{site.url}}{{site.baseurl}}/api-reference/asynchronous-search/async-search-stats/) | Provides statistics about asynchronous search operations | ## Performance considerations From e898b2401ec46799f1f7e04a7c76de2f8732b9cd Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Wed, 7 May 2025 12:56:29 -0500 Subject: [PATCH 4/5] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _api-reference/asynchronous-search/create-async-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/asynchronous-search/create-async-search.md b/_api-reference/asynchronous-search/create-async-search.md index a15fbe4c7ae..c4d1abf44ca 100644 --- a/_api-reference/asynchronous-search/create-async-search.md +++ b/_api-reference/asynchronous-search/create-async-search.md @@ -42,7 +42,7 @@ The following table lists the available query parameters. All query parameters a | Parameter | Data type | Description | | :--- | :--- | :--- | | `index` | String | The name of the index to be searched. Can be an individual name, a comma-separated list of indexes, or a wildcard expression of index names. | -| `keep_alive` | String | The amount of time that the result is saved in the cluster. For example, `2d` means that the results are stored in the cluster for 48 hours. The saved search results are deleted after this period or if the search is canceled. Note that this includes the query execution time. If the query exceeds this amount of time, the process cancels this query automatically. | +| `keep_alive` | String | The amount of time that the result is saved in the cluster. For example, `2d` means that the results are stored in the cluster for 48 hours. The saved search results are deleted after this period or if the search is canceled. Note that this includes the query execution time. If the query exceeds this amount of time, the process cancels this query automatically. | | `keep_on_completion` | Boolean | Whether to save the results in the cluster after the search is complete. You can examine the stored results at a later time. | | `wait_for_completion_timeout` | String | The amount of time to wait for the results. You can poll the remaining results based on an ID. The maximum value is 300 seconds. Default is `1s`. | From 7b7bb1f02d234d5a2399c42a53335e976b3f41cd Mon Sep 17 00:00:00 2001 From: Archer Date: Wed, 7 May 2025 14:47:38 -0500 Subject: [PATCH 5/5] Additional edits Signed-off-by: Archer --- .../asynchronous-search/async-search-stats.md | 14 ++-- .../create-async-search.md | 80 +++++++++---------- .../delete-async-search.md | 12 +-- .../asynchronous-search/get-async-search.md | 38 ++++----- _api-reference/asynchronous-search/index.md | 32 ++++---- 5 files changed, 88 insertions(+), 88 deletions(-) diff --git a/_api-reference/asynchronous-search/async-search-stats.md b/_api-reference/asynchronous-search/async-search-stats.md index ad35f742192..80f3d557e6b 100644 --- a/_api-reference/asynchronous-search/async-search-stats.md +++ b/_api-reference/asynchronous-search/async-search-stats.md @@ -9,13 +9,15 @@ nav_order: 40 **Introduced 1.0** {: .label .label-purple } -The Asynchronous Search Stats API provides statistical information about asynchronous search operations across the cluster. This API helps monitor usage patterns, resource consumption, and the overall health of asynchronous search functionality by returning detailed metrics on both running and completed searches. -These statistics can be valuable for the following actions: -- Performance monitoring and tuning -- Troubleshooting asynchronous search issues -- Capacity planning and resource allocation -- Understanding usage patterns for asynchronous searches +The Asynchronous Search Stats API provides statistics about asynchronous search activity across the cluster. Use this API to monitor performance, track usage trends, and evaluate the resource impact of running and completed asynchronous searches. + +The following list describes common use cases for this API: + +- Monitoring and tuning performance. +- Troubleshooting search issues. +- Planning cluster capacity. +- Understanding how asynchronous search is used.