lqb
/
elasticsearch
mirror of https://gitee.com/mirrors/elasticsearch.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228
							[role="xpack"]
[[put-search-application]]
=== Put Search Application

beta::[]

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

Creates or updates a Search Application.

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

`PUT _application/search_application/<name>`

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

Requires the `manage_search_application` cluster privilege.
Also requires <<privileges-list-indices,manage privileges>> on all indices that are added to the Search Application.

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


`create`::
(Optional, Boolean) If `true`, this request cannot replace or update existing Search Applications.
Defaults to `false`.

`<body>`::
(Required, object)
Contains parameters for a search application:
+
.Properties of `<body>` objects
[%collapsible%open]
====
`indices`::
(Required, array of strings)
The <<indices,indices>> associated with this search application. All indices need to exist in order to be added to a search application.

`template`::
(Optional, object)
The <<search-template,search template>> associated with this search application. The search application's template is only stored and accessible through the search application.

- This search template must be a Mustache template.
- The template must contain a Mustache script and script source.
- The template may be modified with subsequent <<put-search-application,put search application>> requests.
- If no template is specified when creating a search application, or if a template is removed from a search application, we use the <<query-string-query-ex-request,query_string>> defined in the template examples as a default.
- This template will be used by the <<search-application-search,search application search>> API to execute searches.
- The template accepts an optional `dictionary` parameter which defines a https://json-schema.org[JSON schema] used for validating parameters sent to the <<search-application-search,search application search>> API.

.Properties of `<template>`
[%collapsible%open]
=====

`script`::
(Required, object)
The associated mustache template.

`dictionary`::
(Optional, object)
The dictionary used to validate the parameters used with the <<search-application-search, search application search>> API. The dictionary must be a valid JSON schema.
If `dictionary` is not specified, then the parameters will not be validated before being applied in the template.
=====
====


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

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

`409`::
Search Application `<name>` exists and `create` is `true`.

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

The following example creates or updates a new Search Application called `my-app`:

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

PUT /index2

PUT _application/search_application/my-app
{
  "indices": [ "index1", "index2" ],
  "template": {
    "script": {
      "source": {
        "query": {
          "query_string": {
            "query": "{{query_string}}",
            "default_field": "{{default_field}}"
          }
        }
      },
      "params": {
        "query_string": "*",
        "default_field": "*"
      }
    },
    "dictionary": {
      "properties": {
        "query_string": {
          "type": "string"
        },
        "default_field": {
          "type": "string",
          "enum": [
            "title",
            "description"
          ]
        },
        "additionalProperties": false
      },
      "required": [
        "query_string"
      ]
    }
  }
}
----
// TESTSETUP

//////////////////////////

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

DELETE /index1

DELETE /index2
--------------------------------------------------
// TEARDOWN

////

[source,console]
----
PUT _application/search_application/my-app
{
  "indices": [ "index1", "index2" ],
  "template": {
    "script": {
      "source": {
        "query": {
          "query_string": {
            "query": "{{query_string}}",
            "default_field": "{{default_field}}"
          }
        }
      },
      "params": {
        "query_string": "*",
        "default_field": "*"
      }
    },
    "dictionary": {
      "properties": {
        "query_string": {
          "type": "string"
        },
        "default_field": {
          "type": "string",
          "enum": [
            "title",
            "description"
          ]
        },
        "additionalProperties": false
      },
      "required": [
        "query_string"
      ]
    }
  }
}
----

When the above `dictionary` parameter is specified, the <<search-application-search, search application search>> API will perform the following parameter validation:

* It accepts only the `query_string` and `default_field` parameters
* It verifies that `query_string` and `default_field` are both strings
* It accepts `default_field` only if it takes the values `title` or `description`

If the parameters are not valid, the the <<search-application-search, search application search>> API will return an error.
[source,console]
----
POST _application/search_application/my-app/_search
{
  "params": {
    "default_field": "author",
    "query_string": "Jane"
  }
}
----
// TEST[catch:bad_request]

In the above example, the value of the `default_field` parameter is not valid, therefore Elasticsearch will return an error:

[source,JSON]
----
{
  "error": {
    "root_cause": [
      {
        "type": "validation_exception",
        "reason": 'Validation Failed: 1: $.default_field: does not have a value in the enumeration [title, description];',
        "stack_trace": ...
      }
    ],
    "type": "validation_exception",
    "reason": 'Validation Failed: 1: $.default_field: does not have a value in the enumeration [title, description];',
    "stack_trace": ...
  },
  "status": 400
}
----
// TESTRESPONSE[s/"stack_trace": \.\.\./"stack_trace": $body.$_path/]
// Need to use source,JSON above instead console-result, as $ fields are replaced in console-result snippets