mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
[Docs] Add HLRC Async Search API documentation (#54353)
Adds documentation and a corresponding test case containing typical API usage for the Async Search API to the High Level Rest Client.
This commit is contained in:
Christoph Büscher
GitHub
parent
128bcc59d8
commit
610b7bdcbf
6 changed files with 504 additions and 1 deletions
68
docs/java-rest/high-level/asyncsearch/delete.asciidoc
Normal file
68
docs/java-rest/high-level/asyncsearch/delete.asciidoc
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
--
|
||||
:api: asyncsearch-delete
|
||||
:request: DeleteAsyncSearchRequest
|
||||
:response: AcknowledgedResponse
|
||||
--
|
||||
|
||||
[role="xpack"]
|
||||
[id="{upid}-{api}"]
|
||||
=== Delete Async Search API
|
||||
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Request
|
||||
|
||||
A +{request}+ allows deleting a running asynchronous search task using
|
||||
its id. Required arguments are the `id` of a running search:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-request]
|
||||
--------------------------------------------------
|
||||
|
||||
[id="{upid}-{api}-sync"]
|
||||
==== Synchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute]
|
||||
--------------------------------------------------
|
||||
<1> Execute the request and get back the response as an +{response}+ object.
|
||||
|
||||
[id="{upid}-{api}-async"]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a +{request}+ allows to use an
|
||||
`ActionListener` to be called back when the submit request returns:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The +{request}+ to execute and the `ActionListener` to use when
|
||||
the execution completes
|
||||
|
||||
The asynchronous method does not block and returns immediately. Once it is
|
||||
completed the `ActionListener` is called back using the `onResponse` method
|
||||
if the execution successfully completed or using the `onFailure` method if
|
||||
it failed.
|
||||
|
||||
A typical listener for +{response}+ looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-listener]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument
|
||||
<2> Called in case of failure. The raised exception is provided as an argument
|
||||
|
||||
[id="{upid}-{api}-response"]
|
||||
==== Response
|
||||
|
||||
The returned +{response}+ indicates the acknowledgement of the request:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-response]
|
||||
--------------------------------------------------
|
||||
<1> `isAcknowledged` was the deletion request acknowledged or not.
|
||||
87
docs/java-rest/high-level/asyncsearch/get.asciidoc
Normal file
87
docs/java-rest/high-level/asyncsearch/get.asciidoc
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
--
|
||||
:api: asyncsearch-get
|
||||
:request: GetAsyncSearchRequest
|
||||
:response: AsyncSearchResponse
|
||||
--
|
||||
|
||||
[role="xpack"]
|
||||
[id="{upid}-{api}"]
|
||||
=== Get Async Search API
|
||||
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Request
|
||||
|
||||
A +{request}+ allows to get a running asynchronous search task by
|
||||
its id. Required arguments are the `id` of a running async search:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-request]
|
||||
--------------------------------------------------
|
||||
|
||||
==== Optional arguments
|
||||
The following arguments can optionally be provided:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-request-arguments]
|
||||
--------------------------------------------------
|
||||
<1> The minimum time that the request should wait before
|
||||
returning a partial result (defaults to no wait).
|
||||
<2> The expiration time of the request (defaults to none).
|
||||
|
||||
|
||||
[id="{upid}-{api}-sync"]
|
||||
==== Synchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute]
|
||||
--------------------------------------------------
|
||||
<1> Execute the request and get back the response as an +{response}+ object.
|
||||
|
||||
[id="{upid}-{api}-async"]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a +{request}+ allows to use an
|
||||
`ActionListener` to be called back when the submit request returns:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The +{request}+ to execute and the `ActionListener` to use when
|
||||
the execution completes
|
||||
|
||||
The asynchronous method does not block and returns immediately. Once it is
|
||||
completed the `ActionListener` is called back using the `onResponse` method
|
||||
if the execution successfully completed or using the `onFailure` method if
|
||||
it failed.
|
||||
|
||||
A typical listener for +{response}+ looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-listener]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument
|
||||
<2> Called in case of failure. The raised exception is provided as an argument
|
||||
|
||||
[id="{upid}-{api}-response"]
|
||||
==== Response
|
||||
|
||||
The returned +{response}+ allows to retrieve information about the executed
|
||||
operation as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-response]
|
||||
--------------------------------------------------
|
||||
<1> The `SearchResponse`, or `null` if not available yet
|
||||
<2> The id of the async search request, `null` if the response isn't stored
|
||||
<3> `true` when the response contains partial results
|
||||
<4> `true` when the search is still running
|
||||
<5> The time the response was created (millis since epoch)
|
||||
<6> The time the response expires (millis since epoch)
|
||||
<7> Get failure reasons or `null` for no failures
|
||||
94
docs/java-rest/high-level/asyncsearch/submit.asciidoc
Normal file
94
docs/java-rest/high-level/asyncsearch/submit.asciidoc
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
--
|
||||
:api: asyncsearch-submit
|
||||
:request: SubmitAsyncSearchRequest
|
||||
:response: AsyncSearchResponse
|
||||
--
|
||||
|
||||
[role="xpack"]
|
||||
[id="{upid}-{api}"]
|
||||
=== Submit Async Search API
|
||||
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Request
|
||||
|
||||
A +{request}+ allows to submit an asynchronous search task to
|
||||
the cluster. Required arguments are the `SearchSourceBuilder` defining
|
||||
the search and the target indices:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-request]
|
||||
--------------------------------------------------
|
||||
<1> The definition of the search to run
|
||||
<2> The target indices for the search
|
||||
|
||||
==== Optional arguments
|
||||
The following arguments can optionally be provided:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-request-arguments]
|
||||
--------------------------------------------------
|
||||
<1> The minimum time that the request should wait before
|
||||
returning a partial result (defaults to 1 second).
|
||||
<2> The expiration time of the request (defaults to 5 days).
|
||||
<3> Controls whether the results should be stored if the request
|
||||
completed within the provided `wait_for_completion` time (default: false)
|
||||
|
||||
[id="{upid}-{api}-sync"]
|
||||
==== Synchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute]
|
||||
--------------------------------------------------
|
||||
<1> Execute the request and get back the response as an +{response}+ object.
|
||||
|
||||
[id="{upid}-{api}-async"]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a +{request}+ allows to use an
|
||||
`ActionListener` to be called back when the submit request returns. Note
|
||||
that this is does not concern the execution of the submitted search request,
|
||||
which always executes asynchronously. The listener, however, waits for the
|
||||
submit request itself to come back:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The +{request}+ to execute and the `ActionListener` to use when
|
||||
the execution completes
|
||||
|
||||
The asynchronous method does not block and returns immediately. Once it is
|
||||
completed the `ActionListener` is called back using the `onResponse` method
|
||||
if the execution successfully completed or using the `onFailure` method if
|
||||
it failed.
|
||||
|
||||
A typical listener for +{response}+ looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-listener]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed. The response is
|
||||
provided as an argument
|
||||
<2> Called in case of failure. The raised exception is provided as an argument
|
||||
|
||||
[id="{upid}-{api}-response"]
|
||||
==== Response
|
||||
|
||||
The returned +{response}+ allows to retrieve information about the executed
|
||||
operation as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-response]
|
||||
--------------------------------------------------
|
||||
<1> The `SearchResponse`, or `null` if not available yet
|
||||
<2> The id of the async search request, `null` if the response isn't stored
|
||||
<3> `true` when the response contains partial results
|
||||
<4> `true` when the search is still running
|
||||
<5> The time the response was created (millis since epoch)
|
||||
<6> The time the response expires (millis since epoch)
|
||||
<7> Get failure reasons or `null` for no failures
|
||||
|
|
@ -71,6 +71,22 @@ include::search/rank-eval.asciidoc[]
|
|||
include::search/explain.asciidoc[]
|
||||
include::search/count.asciidoc[]
|
||||
|
||||
[role="xpack"]
|
||||
== Async Search APIs
|
||||
|
||||
:upid: {mainid}-asyncsearch
|
||||
:doc-tests-file: {doc-tests}/AsyncSearchDocumentationIT.java
|
||||
|
||||
The Java High Level REST Client supports the following Async Search APIs:
|
||||
|
||||
* <<{upid}-asyncsearch-submit>>
|
||||
* <<{upid}-asyncsearch-get>>
|
||||
* <<{upid}-asyncsearch-delete>>
|
||||
|
||||
include::asyncsearch/submit.asciidoc[]
|
||||
include::asyncsearch/get.asciidoc[]
|
||||
include::asyncsearch/delete.asciidoc[]
|
||||
|
||||
== Miscellaneous APIs
|
||||
|
||||
The Java High Level REST Client supports the following Miscellaneous APIs:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue