OpenSearch/docs/java-rest/high-level/apis/search.asciidoc

[[java-rest-high-search]]
=== Search API

[[java-rest-high-document-search-request]]
==== Search Request

The `SearchRequest` is used for any operation that has to do with searching
documents, aggregations, suggestions and also offers ways of requesting
highlighting on the resulting documents.

In its most basic form, a query can be added to the request like this:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-basic]
--------------------------------------------------

<1> Creates the `SeachRequest`. Without arguments this runs against all indices.
<2> Most parameters of the search can be added to the `SearchSourceBuilder`
which contains everything that
in the Rest API would be placed in the search request body.
<3> Add a `match_all` query to the `SearchSourceBuilder`.

==== Optional arguments

Lets first look at some of the optional argument of a `SearchRequest`.
First of all, the request can be restricted to one or more indices using the
constructor or to on or more types using a setter:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-indices-types]
--------------------------------------------------

There are a couple of other interesting optional parameters:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-routing]
--------------------------------------------------
<1> Set a routing parameter

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-indicesOptions]
--------------------------------------------------
<1> Setting `IndicesOptions` controls how unavailable indices are resolved and
how wildcard expressions are expanded

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-preference]
--------------------------------------------------
<1> Use the preference parameter e.g. to execute the search to prefer local
shards. The The default is to randomize across shards.

==== Using the SearchSourceBuilder

Most options controlling the search behavior can be set on the
`SearchSourceBuilder`,
which contains more or less the equivalent of the options in the search request
body of the Rest API.

Here are a few examples of some common options:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-basics]
--------------------------------------------------
<1> Create a `SearchSourceBuilder` with default options.
<2> Set the query. Can be any type of `QueryBuilder`
<3> Set the `from` option that determines the result index to start searching
from. Defaults to 0.
<4> Set the `size` option that determines the number of search hits to return.
Defaults to 10.
<5> Set an optional timeout that controls how long the search is allowed to
take.

After this, the `SearchSourceBuilder` only needs to be added to the
`SearchRequest`:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-setter]
--------------------------------------------------


[[java-rest-high-document-search-sync]]
==== Synchronous Execution

When executing a `SearchRequest` in the following manner, the client waits
for the `SearchResponse` to be returned before continuing with code execution:  

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute]
--------------------------------------------------

[[java-rest-high-document-search-async]]
==== Asynchronous Execution


Executing a `SearchRequest` can also be done in an asynchronous fashion so that
the client can return directly. Users need to specify how the response or
potential failures will be handled by passing in appropriate listeners:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-async]
--------------------------------------------------
<1> Called when the execution is successfully completed.
<2> Called when the whole `SearchRequest` fails.

==== SearchResponse

The `SearchResponse` that is returned by executing the search provides details
about the search execution itself as well as access to the documents returned.
First, there is useful information about the request execution itself, like the
HTTP status code, execution time or wether the request terminated early or timed
out: 

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-1]
--------------------------------------------------

Second, the response also provides information about the execution on the
shard level by offering statistics about the total number of shards that were
affected by the search, and the successful vs. unsuccessful shards. Possible
failures can also be handled by iterating over an array off
`ShardSearchFailures` like in the following example:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-2]
--------------------------------------------------

To get access to the returned documents, we need to first get the `SearchHits`
contained in the response:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-get]
--------------------------------------------------

The `SearchHits` provides global information about all hits, like total number
of hits or the maximum score:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-info]
--------------------------------------------------

Nested inside the `SearchHits` are the individual search results that can
be iterated over like this:


["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit]
--------------------------------------------------

The `SearchHit` provides access to basic information like index, type, docId and
score of each search hit:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit-properties]
--------------------------------------------------

Furthermore, it lets you get back the document source, either as a simple
JSON-String or as a map of key/value pairs. In this map, regular fields 
are keyed by the field name and contain the field value. Multi-valued fields are
returned as lists of objects, nested objects as another key/value map. These
cases need to be case accordingly:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit-source]
--------------------------------------------------