elasticsearch/docs/reference/search-application/apis/search-application-search.asciidoc

[role="xpack"]
[[search-application-search]]
=== Search Application Search

beta::[]

++++
<titleabbrev>Search Application Search</titleabbrev>
++++

Given specified query parameters, generates and executes an {es} query using the search template associated
with the search application or a default template if none is specified.
Unspecified template parameters will be assigned their default values (if applicable).

[[search-application-search-request]]
==== {api-request-title}

`POST _application/search_application/<name>/_search`

[[search-application-search-prereqs]]
==== {api-prereq-title}

Requires read privileges on the backing alias of the search application.

[[search-application-search-path-params]]
==== {api-path-parms-title}

`typed_keys`::
(Optional, Boolean) If `true`, aggregation and suggester names are prefixed
by their respective types in the response. Defaults to `false`.

[[search-application-search-request-body]]
==== {api-request-body-title}

`params`::
(Optional, map of strings to objects)
Query parameters used to generate the {es} query from the search template associated with the search application.
If a parameter used in the search template is not specified in `params`, the parameter's default value will be used.

[NOTE]
====
The search application can be configured to validate search template parameters.
See the `dictionary` parameter in the <<put-search-application-dictionary-param, put search application>> API for more
information.
====

[[search-application-search-response-codes]]
==== {api-response-codes-title}

`400`::
Invalid parameter passed to search template.
Examples include:

- Missing required parameter
- Invalid parameter data type
- Invalid parameter value

`404`::
Search Application `<name>` does not exist.

[[search-application-search-example]]
==== {api-examples-title}

The following example executes a search against a search application called `my-app` that uses the search template from
the <<search-application-api-bm25-template, text search example>>:

////
[source,console]
----
PUT /index1

PUT /index1/_doc/1?refresh=true
{
  "title": "Sample document",
  "description": "A sample document that matches my first query"
}

PUT _application/search_application/my-app
{
  "indices": ["index1"],
  "template": {
    "script": {
      "lang": "mustache",
      "source": """
      {
        "query": {
          "multi_match": {
            "query": "{{query_string}}",
            "fields": [{{#text_fields}}"{{name}}^{{boost}}",{{/text_fields}}]
          }
        },
        "explain": "{{explain}}",
        "from": "{{from}}",
        "size": "{{size}}"
      }
      """,
      "params": {
        "query_string": "*",
        "text_fields": [
          {"name": "title", "boost": 10},
          {"name": "description", "boost": 5}
        ],
        "explain": false,
        "from": 0,
        "size": 10
      }
    }
  }
}
----
// TESTSETUP
//////////////////////////

[source,console]
--------------------------------------------------
DELETE _application/search_application/my-app

DELETE /index1
--------------------------------------------------
// TEARDOWN

////

[source,console]
----
POST _application/search_application/my-app/_search
{
  "params": {
    "query_string": "my first query",
    "text_fields": [
      {"name": "title", "boost": 5},
      {"name": "description", "boost": 1}
    ]
  }
}
----

The generated {es} query would look like:

[source,console-result]
----
{
  "from": 0,
  "size": 10,
  "query": {
    "multi_match": {
      "query": "my first query",
      "fields": [
        "description^1.0",
        "title^5.0"
      ]
    }
  },
  "explain": false
}
----
// TESTRESPONSE[skip:result of request not run in this document]

In this case, the `from`, `size`, and `explain` parameters are not specified in the request, so the default values
specified in the search template are used.

The expected response is the search results from the {es} query that was generated & executed.
The response format is the same as that used by the <<search-api-response-body,{es} Search API>>:

[source,console-result]
----
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.8630463,
    "hits": ...
  }
}
----
// TESTRESPONSE[s/"took": 5/"took": $body.$_path/]
// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.$_path/]