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

[stefnestor]

Thanks, @leemthompo ! I have updated per feedback all points except replying here to: "Why not? 😄" Because it's not defined anywhere, Dev would need to write a doc PR.

[leemthompo]

Thanks! There's some language cleanup to be done here, but I'd like to get a technical review before doing that.

[jimczi]

This is still quite hairy ;)
What about something like:

The timeout value applies per shard, starting when the query phase begins on that shard. It does not enforce an overall search-level timeout. If a shard exceeds the timeout, it returns partial results and the search response is marked timed_out: true.

[stefnestor]

Thanks for the feedback! This is delineated because it's what Support spends time clarifying from the doc not currently saying (specifically the whole bullet list of what doesn't qualify, which is actually what started this whole PR flow) 🙂.

FWIW maybe that's part of what @leemthompo's comment about language clean up 🙃

[jimczi]

It's too detailed and not up to date to my taste. The only thing that we should clarify is that it's applied per shard and we check it on a best effort basis every thread_pool.estimated_time_interval.

[jimczi]

I am not sure that async search is the best example for this. This is generally used in scenario where latency is crucial.
Can we use a simple example with few shards, showing that some shards may return incomplete results?

[stefnestor]

I am not sure that async search is the best example for this.

It is the existing example (although it only had a request body no response body); 🤷‍♀️ I have no horse in the race but also it doesn't really affect the response body example IMO.

Can we use a simple example with few shards, showing that some shards may return incomplete results?

I may need your help with a "more valid" example. This was simplified patterned from this real life which AFAICT looks par (that shards all "successful" but still timed_out: true). 🙏

[jimczi]

I am just proposing to change _async_search to _search, the example is fine.