From 5c46e2f62e63af177caec6664fda9d92ec23fbd9 Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Fri, 17 Oct 2025 10:14:17 -0600 Subject: [PATCH 1/4] Expand Elasticsearch Search timeout --- solutions/search/the-search-api.md | 54 +++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/solutions/search/the-search-api.md b/solutions/search/the-search-api.md index 8e6af4be87..d9598848ed 100644 --- a/solutions/search/the-search-api.md +++ b/solutions/search/the-search-api.md @@ -172,23 +172,59 @@ The response includes an aggregation based on the `day_of_week` runtime field. U ## Search timeout [search-timeout] -By default, search requests don’t time out. The request waits for complete results from each shard before returning a response. +Search requests do not time out by default. The request waits for complete results from every shard before returning a response as outlined in the [basic read model](https://www.elastic.co/docs/deploy-manage/distributed-architecture/reading-and-writing-documents#_basic_read_model). -While [async search](async-search-api.md) is designed for long-running searches, you can also use the `timeout` parameter to specify a duration you’d like to wait on each shard to complete. Each shard collects hits within the specified time period. If collection isn’t finished when the period ends, {{es}} uses only the hits accumulated up to that point. The overall latency of a search request depends on the number of shards needed for the search and the number of concurrent shard requests. +You can override the search request to best-effort time out through its [`timeout` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search), provided either as query parameter or within request body. If the search timeout is surpassed before the search request finishes, the request is cancelled using [task cancellation API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-tasks-cancel). The `timeout` setting + +* Checks for duration expiration on a per shard basis. +* Performs cancellations along a shard's segment boundaries; therefore, large segments may delay cancellation. +* Compares timeout duration against the search `query` phase's duration. This implies that it does not include time spent in + * internet network nor inter-node transport network + * coordinating node wrapping task + * [thread pool queue](https://www.elastic.co/docs/troubleshoot/elasticsearch/task-queue-backlog#diagnose-task-queue-thread-pool) + * [`fetch` phase](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/search-profile#profiling-fetch) + +You can set a cluster-wide default `timeout` for all search requests. This is configured by the `search.default_search_timeout` cluster setting. This setting defaults to `-1` indicating disabled or no timeout. This cluster-wide time-out is used as fallback if no `timeout` argument is designated by a search request. You can override this to a desired [time unit](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units) value using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). For example ```console -GET /my-index-000001/_search +PUT /_cluster/settings +{ "persistent": { "search.default_search_timeout": "5m" } } +``` + +:::{note} +The `search.default_search_timeout` setting's resolution sensitivity is based from expert setting `thread_pool.estimated_time_interval` which defaults to `200ms`. This means the minimum meaningful impact threshold for `search.default_search_timeout` would also be `200ms`. Elastic recommends against overriding this expert setting as it has far reaching impact. +::: + +:::{tip} +The `search.default_search_timeout` cluster setting only applies to the current cluster and does not cascade during [Cross Cluster Search (CSS)](https://www.elastic.co/docs/solutions/search/cross-cluster-search). Remote clusters should be individually configured as makes sense for your use case. +::: + +To demonstrate the impact of the `timeout` parameter, consider an [async search](async-search-api.md). Async searches are designed for long-running searches, but you can use the `timeout` parameter to specify a duration you’d like to wait on each shard to complete. The overall latency of a search request depends on the number of shards needed for the search and the number of concurrent shard requests. Each shard collects hits within the specified time period. If collection isn’t finished when the period ends, {{es}} uses only the hits accumulated up to that point. + +For example response, if the `timeout` duration was surpassed for at least one shard, the API response will return a HTTP 200 status code but the response body field `timed_out` will report `true`. + +```json { - "timeout": "2s", - "query": { - "match": { - "user.id": "kimchy" - } + "took" : 11, + "timed_out" : true, + "_shards" : { + "total" : 40, + "successful" : 40, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 98393, // possibly incomplete value + "relation" : "eq" + }, + + // ... } } ``` -To set a cluster-wide default timeout for all search requests, configure `search.default_search_timeout` using the [cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). This global timeout duration is used if no `timeout` argument is passed in the request. If the global search timeout expires before the search request finishes, the request is cancelled using [task cancellation](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-tasks). The `search.default_search_timeout` setting defaults to `-1` (no timeout). +For a particular search request, if the request should error out instead of returning partial results, consider also overriding [`default_allow_partial_results` setting](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-search) to `false`. ## Search cancellation [global-search-cancellation] From 6999255ad69e24dbf28d7f8238ee4c4be8a89c58 Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Fri, 17 Oct 2025 10:36:55 -0600 Subject: [PATCH 2/4] feedback --- solutions/search/the-search-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solutions/search/the-search-api.md b/solutions/search/the-search-api.md index d9598848ed..0a3cb0e458 100644 --- a/solutions/search/the-search-api.md +++ b/solutions/search/the-search-api.md @@ -174,7 +174,7 @@ The response includes an aggregation based on the `day_of_week` runtime field. U Search requests do not time out by default. The request waits for complete results from every shard before returning a response as outlined in the [basic read model](https://www.elastic.co/docs/deploy-manage/distributed-architecture/reading-and-writing-documents#_basic_read_model). -You can override the search request to best-effort time out through its [`timeout` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search), provided either as query parameter or within request body. If the search timeout is surpassed before the search request finishes, the request is cancelled using [task cancellation API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-tasks-cancel). The `timeout` setting +You can override the search request to best-effort time out through its [`timeout` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search), provided either as query parameter or within request body. If the search timeout is surpassed before the search request finishes for the given shard it stops where it is and returns partial results. The `timeout` setting * Checks for duration expiration on a per shard basis. * Performs cancellations along a shard's segment boundaries; therefore, large segments may delay cancellation. @@ -184,7 +184,7 @@ You can override the search request to best-effort time out through its [`timeou * [thread pool queue](https://www.elastic.co/docs/troubleshoot/elasticsearch/task-queue-backlog#diagnose-task-queue-thread-pool) * [`fetch` phase](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/search-profile#profiling-fetch) -You can set a cluster-wide default `timeout` for all search requests. This is configured by the `search.default_search_timeout` cluster setting. This setting defaults to `-1` indicating disabled or no timeout. This cluster-wide time-out is used as fallback if no `timeout` argument is designated by a search request. You can override this to a desired [time unit](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units) value using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). For example +You can set a cluster-wide default `timeout` for all search requests. This is configured by the `search.default_search_timeout` cluster setting. This setting defaults to `-1` indicating disabled or no timeout. This cluster-wide time-out is used as fallback if no `timeout` argument is designated by a search request. You can override this to a desired [time unit](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units) value using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). In this case, the request will be cancelled using the [task cancellation API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-tasks-cancel). For example ```console PUT /_cluster/settings From c39d7851d0c9c81b167a54643d741cb0d8849697 Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Thu, 30 Oct 2025 13:02:52 -0600 Subject: [PATCH 3/4] =?UTF-8?q?feedback=20=F0=9F=99=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- solutions/search/the-search-api.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/solutions/search/the-search-api.md b/solutions/search/the-search-api.md index 0a3cb0e458..6788ca2bb3 100644 --- a/solutions/search/the-search-api.md +++ b/solutions/search/the-search-api.md @@ -172,7 +172,7 @@ The response includes an aggregation based on the `day_of_week` runtime field. U ## Search timeout [search-timeout] -Search requests do not time out by default. The request waits for complete results from every shard before returning a response as outlined in the [basic read model](https://www.elastic.co/docs/deploy-manage/distributed-architecture/reading-and-writing-documents#_basic_read_model). +Search requests do not time out by default. The request waits for complete results from every shard before returning a response as outlined in the [basic read model](/deploy-manage/distributed-architecture/reading-and-writing-documents.md#_basic_read_model). You can override the search request to best-effort time out through its [`timeout` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search), provided either as query parameter or within request body. If the search timeout is surpassed before the search request finishes for the given shard it stops where it is and returns partial results. The `timeout` setting @@ -181,10 +181,10 @@ You can override the search request to best-effort time out through its [`timeou * Compares timeout duration against the search `query` phase's duration. This implies that it does not include time spent in * internet network nor inter-node transport network * coordinating node wrapping task - * [thread pool queue](https://www.elastic.co/docs/troubleshoot/elasticsearch/task-queue-backlog#diagnose-task-queue-thread-pool) - * [`fetch` phase](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/search-profile#profiling-fetch) + * [thread pool queue](/troubleshoot/elasticsearch/task-queue-backlog.md#diagnose-task-queue-thread-pool) + * [`fetch` phase](elasticsearch://reference/elasticsearch/rest-apis/search-profile.md#profiling-fetch) -You can set a cluster-wide default `timeout` for all search requests. This is configured by the `search.default_search_timeout` cluster setting. This setting defaults to `-1` indicating disabled or no timeout. This cluster-wide time-out is used as fallback if no `timeout` argument is designated by a search request. You can override this to a desired [time unit](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units) value using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). In this case, the request will be cancelled using the [task cancellation API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-tasks-cancel). For example +You can set a cluster-wide default `timeout` for all search requests. This is configured by the `search.default_search_timeout` cluster setting. This setting defaults to `-1` indicating disabled or no timeout. This cluster-wide time-out is used as fallback if no `timeout` argument is designated by a search request. You can override this to a desired [time unit](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#time-units) value using the [update cluster settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). In this case, the request will be cancelled using the [task cancellation API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-tasks-cancel). For example ```console PUT /_cluster/settings @@ -195,9 +195,9 @@ PUT /_cluster/settings The `search.default_search_timeout` setting's resolution sensitivity is based from expert setting `thread_pool.estimated_time_interval` which defaults to `200ms`. This means the minimum meaningful impact threshold for `search.default_search_timeout` would also be `200ms`. Elastic recommends against overriding this expert setting as it has far reaching impact. ::: -:::{tip} -The `search.default_search_timeout` cluster setting only applies to the current cluster and does not cascade during [Cross Cluster Search (CSS)](https://www.elastic.co/docs/solutions/search/cross-cluster-search). Remote clusters should be individually configured as makes sense for your use case. -::: +The `search.default_search_timeout` cluster setting only applies to the current cluster and does not cascade during [Cross Cluster Search (CSS)](/solutions/search/cross-cluster-search). Remote clusters should be individually configured as makes sense for your use case. + +### Example [search-timeout-example] To demonstrate the impact of the `timeout` parameter, consider an [async search](async-search-api.md). Async searches are designed for long-running searches, but you can use the `timeout` parameter to specify a duration you’d like to wait on each shard to complete. The overall latency of a search request depends on the number of shards needed for the search and the number of concurrent shard requests. Each shard collects hits within the specified time period. If collection isn’t finished when the period ends, {{es}} uses only the hits accumulated up to that point. @@ -224,7 +224,7 @@ For example response, if the `timeout` duration was surpassed for at least one s } ``` -For a particular search request, if the request should error out instead of returning partial results, consider also overriding [`default_allow_partial_results` setting](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-search) to `false`. +For a particular search request, if the request should error out instead of returning partial results, consider also overriding [`default_allow_partial_results` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) to `false`. ## Search cancellation [global-search-cancellation] From a84ff59799dfda3ca3aea7924fcd907b5ddf58f3 Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Thu, 30 Oct 2025 13:09:22 -0600 Subject: [PATCH 4/4] typo --- solutions/search/the-search-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/the-search-api.md b/solutions/search/the-search-api.md index 6788ca2bb3..a9fe607686 100644 --- a/solutions/search/the-search-api.md +++ b/solutions/search/the-search-api.md @@ -195,7 +195,7 @@ PUT /_cluster/settings The `search.default_search_timeout` setting's resolution sensitivity is based from expert setting `thread_pool.estimated_time_interval` which defaults to `200ms`. This means the minimum meaningful impact threshold for `search.default_search_timeout` would also be `200ms`. Elastic recommends against overriding this expert setting as it has far reaching impact. ::: -The `search.default_search_timeout` cluster setting only applies to the current cluster and does not cascade during [Cross Cluster Search (CSS)](/solutions/search/cross-cluster-search). Remote clusters should be individually configured as makes sense for your use case. +The `search.default_search_timeout` cluster setting only applies to the current cluster and does not cascade during [Cross Cluster Search (CSS)](/solutions/search/cross-cluster-search.md). Remote clusters should be individually configured as makes sense for your use case. ### Example [search-timeout-example]