[DOC] Explain the differences between search timeouts

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request.

I would like to set a timeout on a search request and found two methods in the Java client, searchRequest.setCancelAfterTimeInterval and SearchSourceBuilder.timeout. I could find no documentation at all for setCancelAfterTimeInterval. After reading some issues in the Elasticsearch repository I make the more or less educated gues that the first one is a general timeout while the timeout on the SearchSourceBuilder is set on the shard level. Some documentation to distinguish the two would be very helpful. It would also be good to know if SearchResponse.isTimedOut refers to both of these timeouts or only one of them.

Start by comparing the Java client methods searchRequest.setCancelAfterTimeInterval and SearchSourceBuilder.timeout, then determine how SearchResponse.isTimedOut relates to each timeout. Done means the documentation clearly distinguishes their scopes and explains which timeout or timeouts are reflected by isTimedOut.