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

[role="xpack"]
[[search-application-render-query]]
=== Render Search Application Query

preview::[]

++++
<titleabbrev>Render Search Application Query</titleabbrev>
++++

Given specified query parameters, generates 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).
Returns the specific {es} query that would be generated and executed by calling
<<search-application-search,search application search>>.

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

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

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

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

[[search-application-render-query-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-render-query-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-render-query-example]]
==== {api-examples-title}

The following example generates a query for 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 _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/_render_query
{
  "params": {
    "query_string": "my first query",
    "text_fields": [
      {"name": "title", "boost": 5},
      {"name": "description", "boost": 1}
    ]
  }
}
----

A sample response:

[source,console-result]
----
{
  "from": 0,
  "size": 10,
  "query": {
    "multi_match": {
      "query": "my first query",
      "fields": [
        "description^1.0",
        "title^5.0"
      ]
    }
  },
  "explain": false
}
----
// TEST[continued]

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.