118 lines
5.0 KiB
Plaintext
118 lines
5.0 KiB
Plaintext
|
[[java-rest-high-search-template]]
|
||
|
|
=== Search Template API
|
||
|
|
|
||
|
|
The search template API allows for searches to be executed from a template based
|
||
|
|
on the mustache language, and also for previewing rendered templates.
|
||
|
|
|
||
|
|
[[java-rest-high-search-template-request]]
|
||
|
|
==== Search Template Request
|
||
|
|
|
||
|
|
===== Inline Templates
|
||
|
|
|
||
|
|
In the most basic form of request, the search template is specified inline:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-request-inline]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The search is executed against the `posts` index.
|
||
|
|
<2> The template defines the structure of the search source. It is passed
|
||
|
|
as a string because mustache templates are not always valid JSON.
|
||
|
|
<3> Before running the search, the template is rendered with the provided parameters.
|
||
|
|
|
||
|
|
===== Registered Templates
|
||
|
|
|
||
|
|
Search templates can be registered in advance through stored scripts API. Note that
|
||
|
|
the stored scripts API is not yet available in the high-level REST client, so in this
|
||
|
|
example we use the low-level REST client.
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[register-script]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
Instead of providing an inline script, we can refer to this registered template in the request:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-request-stored]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
===== Rendering Templates
|
||
|
|
|
||
|
|
Given parameter values, a template can be rendered without executing a search:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[render-search-template-request]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> Setting `simulate` to `true` causes the search template to only be rendered.
|
||
|
|
|
||
|
|
Both inline and pre-registered templates can be rendered.
|
||
|
|
|
||
|
|
===== Optional Arguments
|
||
|
|
|
||
|
|
As in standard search requests, the `explain` and `profile` options are supported:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-request-options]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
===== Additional References
|
||
|
|
|
||
|
|
The {ref}/search-template.html[Search Template documentation] contains further examples of how search requests can be templated.
|
||
|
|
|
||
|
|
[[java-rest-high-search-template-sync]]
|
||
|
|
==== Synchronous Execution
|
||
|
|
|
||
|
|
The `searchTemplate` method executes the request synchronously:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-execute]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
==== Asynchronous Execution
|
||
|
|
|
||
|
|
A search template request can be executed asynchronously through the `searchTemplateAsync`
|
||
|
|
method:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-execute-async]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The `SearchTemplateRequest` to execute and the `ActionListener` to call when the execution completes.
|
||
|
|
|
||
|
|
The asynchronous method does not block and returns immediately. Once the request completes, the
|
||
|
|
`ActionListener` is called back using the `onResponse` method if the execution completed successfully,
|
||
|
|
or using the `onFailure` method if it failed.
|
||
|
|
|
||
|
|
A typical listener for `SearchTemplateResponse` is constructed as follows:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-execute-listener]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> Called when the execution is successfully completed.
|
||
|
|
<2> Called when the whole `SearchTemplateRequest` fails.
|
||
|
|
|
||
|
|
==== Search Template Response
|
||
|
|
|
||
|
|
For a standard search template request, the response contains a `SearchResponse` object
|
||
|
|
with the result of executing the search:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-template-response]
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
If `simulate` was set to `true` in the request, then the response
|
||
|
|
will contain the rendered search source instead of a `SearchResponse`:
|
||
|
|
|
||
|
|
["source","java",subs="attributes,callouts,macros"]
|
||
|
|
--------------------------------------------------
|
||
|
|
include-tagged::{doc-tests}/SearchDocumentationIT.java[render-search-template-response]
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The rendered source in bytes, in our example `{"query": { "match" : { "title" : "elasticsearch" }}, "size" : 5}`.
|