[DOCS] Async search response ID clarification

[russcam]

When an async search successfully completes within the wait_for_completion_timeout, and no keep_alive parameter is specified such that results will not be available in the cluster, an ID is not returned in the response to a submit async search API.

The documentation for async search APIs does not currently mention this, but I think it would be good to clarify this behaviour.

[elasticmachine]

Pinging @elastic/es-docs (>docs)

[elasticmachine]

Pinging @elastic/es-search (:Search/Search)

[javanna]

To clarify, keep_alive has little to do with this behaviour. If the request is completed within the wait for completion timeout, you will get back the final response directly, hence the response will not be stored in the cluster and no id will be returned regardless of the keep_alive parameter. There is an undocumented parameter called keep_on_completion that allows to request that every response is stored in the cluster, which is useful for testing but we do not expect users to need to change the default behaviour. I will clarify the docs on this.

As a side note, I still find this potentially confusing, as the keep_alive gets ignored in the described scenario. We did some thinking around these parameters, their meaning and naming, which is summarized in #54069. What we have now is the outcome of that discussion.

[russcam]

Sorry, I meant keep_on_completion, not keep_alive. This is what we're using for integration tests for the C# client: elastic/elasticsearch-net@ea847aa

The reason for raising this issue though is that the documentation does not mention any happy path scenario where an ID is not returned, which I think it should, along with document how keep_on_completion works in conjunction to keep_alive.

[javanna]

We should mention what happens when the response completed within the completion timeout, agreed. I am reluctant on documenting keep_on_completion because it's only used in tests and we are still looking for alternatives as we would love to remove it soon.

…

On Mon, Apr 27, 2020, 02:20 Russ Cam ***@***.***> wrote: Sorry, I meant keep_on_completion, not keep_alive. This is what we're using for integration tests for the C# client: elastic/elasticsearch-net@ ea847aa <elastic/elasticsearch-net@ea847aa> The reason for raising this issue though is that the documentation does not mention any happy path scenario where an ID is not returned, which I think it should, along with document how keep_on_completion works in conjunction to keep_alive. — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#55636 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGLHTA2ITWB6XVYBH67ZJTROTFTNANCNFSM4MOTGFLA> .