Expand Elasticsearch Search timeout

[stefnestor]

👋🏽 howdy, team!

This updates the The _search API > Search Timeout documentation section which causes user confusion and induces Support volume. TLDR it looks like we had aspirations to clarify this recently in elastic/elasticsearch#47716 but need to go a bit farther.

Statements pulled from

• v5 docs
• internal
• https://support.elastic.co/knowledge/6ea7fdbb
• Search request timeout option is confusing elasticsearch#47716
• Clarify timeout and terminate_after docs elasticsearch#71713
• [DOCS] Clarify that search timeouts behave like cancellation elasticsearch#31263
• SearchRequest cancellation based on timeout elasticsearch#56258
• Add a hard time limit for the entire search request elasticsearch#30897

This does not include @\javanna's excellent callout here that some searches also cancel on connection closed.

🙋‍♀️ This PR should be confirmed by a Dev before merging.

TIA! Stef

[github-actions]

🔍 Preview links for changed docs

• solutions/search/the-search-api.md

[leemthompo]

Hey @stefnestor thanks for opening this, might be a bit tardy in reviewing this given 9.2 goes out this week. Please re-ping next week if don't hear anything back ;)

But in the meantime, perhaps @jimczi could weigh in on these suggested changes, and/or recommend one of the relevant dev teams have a look?

[leemthompo]

Couple of things off top of my head:

• We need to be clear about what's relevant to serverless versus other deployment types using applies_to metadata
• Should investigate follow up changes on related pages (eg the API reference)

• This does not include @\javanna's excellent callout that some searches also cancel on connection closed.

  • Why not? 😄
• Feel free to use subheadings instead of stacked admonitions (tips and notes) because this is more future-proof and improves page scannability in the On this page nav
• Putting your example under a subheading would also improve scannability

[leemthompo]

Couple linking things :)

[leemthompo]

Suggested change

	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).

This is the syntax for links to pages that live in the same repo

See https://elastic.github.io/docs-builder/syntax/links/

[leemthompo]

apart from API docs which use a different system, we should always be linking to an .md file, not a full webpage URL for docs links

[leemthompo]

You can check for any other instances that need updating :)

[leemthompo]

Suggested change

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

https://elastic.github.io/docs-builder/syntax/links/#cross-repository-links

If pages live in different repos we need to use ☝️ cross-repo syntax, and always linking to an .md file. Again API ref links are only exception, they are considered external URLs because they don't use the same system and can't be validated by docs CI.

Again, you can check for any other instances that need updating :)