OpenSearch/docs/java-api/search.asciidoc

[[search]]
== Search API

The search API allows one to execute a search query and get back search hits
that match the query. It can be executed across one or more indices and
across one or more types. The query can either be provided using the
<<query-dsl-queries,query Java API>> or
the <<query-dsl-filters,filter Java API>>. 
The body of the search request is built using the
`SearchSourceBuilder`. Here is an example:

[source,java]
--------------------------------------------------
import org.elasticsearch.action.search.SearchResponse;
import org.elasticsearch.action.search.SearchType;
import org.elasticsearch.index.query.FilterBuilders.*;
import org.elasticsearch.index.query.QueryBuilders.*;
--------------------------------------------------

[source,java]
--------------------------------------------------
SearchResponse response = client.prepareSearch("index1", "index2")
        .setTypes("type1", "type2")
        .setSearchType(SearchType.DFS_QUERY_THEN_FETCH)
        .setQuery(QueryBuilders.termQuery("multi", "test"))             // Query
        .setPostFilter(FilterBuilders.rangeFilter("age").from(12).to(18))   // Filter
        .setFrom(0).setSize(60).setExplain(true)
        .execute()
        .actionGet();
--------------------------------------------------

Note that all parameters are optional. Here is the smallest search call
you can write:

[source,java]
--------------------------------------------------
// MatchAll on the whole cluster with all default options
SearchResponse response = client.prepareSearch().execute().actionGet();
--------------------------------------------------

For more information on the search operation, check out the REST
{ref}/search.html[search] docs.


[[scrolling]]
=== Using scrolls in Java

Read the {ref}/search-request-scroll.html[scroll documentation]
first!

[source,java]
--------------------------------------------------
import static org.elasticsearch.index.query.FilterBuilders.*;
import static org.elasticsearch.index.query.QueryBuilders.*;

QueryBuilder qb = termQuery("multi", "test");

SearchResponse scrollResp = client.prepareSearch(test)
        .setSearchType(SearchType.SCAN)
        .setScroll(new TimeValue(60000))
        .setQuery(qb)
        .setSize(100).execute().actionGet(); //100 hits per shard will be returned for each scroll
//Scroll until no hits are returned
while (true) {

    for (SearchHit hit : scrollResp.getHits()) {
        //Handle the hit...
    }
    scrollResp = client.prepareSearchScroll(scrollResp.getScrollId()).setScroll(new TimeValue(600000)).execute().actionGet();
    //Break condition: No hits are returned
    if (scrollResp.getHits().getHits().length == 0) {
        break;
    }
}
--------------------------------------------------


=== Operation Threading

The search API allows one to set the threading model the operation will be
performed when the actual execution of the API is performed on the same
node (the API is executed on a shard that is allocated on the same
server).

There are three threading modes.The `NO_THREADS` mode means that the
search operation will be executed on the calling thread. The
`SINGLE_THREAD` mode means that the search operation will be executed on
a single different thread for all local shards. The `THREAD_PER_SHARD`
mode means that the search operation will be executed on a different
thread for each local shard.

The default mode is `THREAD_PER_SHARD`.


[[msearch]]
=== MultiSearch API

See {ref}/search-multi-search.html[MultiSearch API Query]
documentation

[source,java]
--------------------------------------------------
SearchRequestBuilder srb1 = node.client()
    .prepareSearch().setQuery(QueryBuilders.queryString("elasticsearch")).setSize(1);
SearchRequestBuilder srb2 = node.client()
    .prepareSearch().setQuery(QueryBuilders.matchQuery("name", "kimchy")).setSize(1);

MultiSearchResponse sr = node.client().prepareMultiSearch()
        .add(srb1)
        .add(srb2)
        .execute().actionGet();

// You will get all individual responses from MultiSearchResponse#getResponses()
long nbHits = 0;
for (MultiSearchResponse.Item item : sr.getResponses()) {
    SearchResponse response = item.getResponse();
    nbHits += response.getHits().getTotalHits();
}
--------------------------------------------------


[[java-search-aggs]]
=== Using Aggregations

The following code shows how to add two aggregations within your search:

[source,java]
--------------------------------------------------
SearchResponse sr = node.client().prepareSearch()
    .setQuery(QueryBuilders.matchAllQuery())
    .addAggregation(
            AggregationBuilders.terms("agg1").field("field")
    )
    .addAggregation(
            AggregationBuilders.dateHistogram("agg2")
                    .field("birth")
                    .interval(DateHistogram.Interval.YEAR)
    )
    .execute().actionGet();

// Get your facet results
Terms agg1 = sr.getAggregations().get("agg1");
DateHistogram agg2 = sr.getAggregations().get("agg2");
--------------------------------------------------

See <<java-aggs,Aggregations Java API>>
documentation for details.

[[java-search-template]]
=== Using Search Templates

See {ref}/search-template.html[Search Template] documentation

Define your template parameters as a `Map<String,Object>`:

[source,java]
--------------------------------------------------
Map<String, Object> template_params = new HashMap<>();
template_params.put("param_gender", "male");
--------------------------------------------------

You can use your stored search templates in `config/scripts`.
For example, if you have a file named `config/scripts/template_gender.mustache` containing:

[source,js]
--------------------------------------------------
{
    "template" : {
        "query" : {
            "match" : {
                "gender" : "{{param_gender}}"
            }
        }
    }
}
--------------------------------------------------

Execute it with:

[source,java]
--------------------------------------------------
SearchResponse sr = client.prepareSearch()
        .setTemplateName("template_gender")
        .setTemplateType(ScriptService.ScriptType.FILE)
        .setTemplateParams(template_params)
        .get();
--------------------------------------------------

You can also store your template in a special index named `.scripts`:

[source,java]
--------------------------------------------------
client.preparePutIndexedScript("mustache", "template_gender",
        "{\n" +
        "    \"template\" : {\n" +
        "        \"query\" : {\n" +
        "            \"match\" : {\n" +
        "                \"gender\" : \"{{param_gender}}\"\n" +
        "            }\n" +
        "        }\n" +
        "    }\n" +
        "}").get();
--------------------------------------------------

To execute an indexed templates, use `ScriptService.ScriptType.INDEXED`:

[source,java]
--------------------------------------------------
SearchResponse sr = client.prepareSearch()
        .setTemplateName("template_gender")
        .setTemplateType(ScriptService.ScriptType.INDEXED)
        .setTemplateParams(template_params)
        .get();
--------------------------------------------------