[DOCS] : Indexed scripts/templates

These are the docs for the indexed scripts/templates feature.
Also moved the namespace for the REST endpoints.

Closes #6851

docs/reference/modules/scripting.asciidoc

@@ -76,6 +76,84 @@ exists under, and the file name without the lang extension. For example,
 a script placed under `config/scripts/group1/group2/test.py` will be
 named `group1_group2_test`.
 
+[float]
+=== Indexed Scripts
+If dynamic scripting is enabled, Elasticsearch allows you to store scripts
+in an internal index known as `.scripts` and reference them by id. There are
+REST endpoints to manage indexed scripts as follows:
+
+Requests to the scripts endpoint look like :
+[source,js]
+-----------------------------------
+/_scripts/{lang}/{id}
+-----------------------------------
+Where the `lang` part is the language the script is in and the `id` part is the id
+of the script. In the `.scripts` index the type of the document will be set to the `lang`.
+
+
+[source,js]
+-----------------------------------
+curl -XPOST localhost:9200/_scripts/mvel/indexedCalculateScore -d '{
+     "script": "log(_score * 2) + my_modifier"
+}'
+-----------------------------------
+
+This will create a document with id: `indexedCalculateScore` and type: `mvel` in the
+`.scripts` index. The type of the document is the language used by the script.
+
+This script can be accessed at query time by appending `_id` to
+the script parameter and passing the script id. So `script` becomes `script_id`.:
+
+[source,js]
+--------------------------------------------------
+curl -XPOST localhost:9200/_search -d '{
+  "query": {
+    "function_score": {
+      "query": {
+        "match": {
+          "body": "foo"
+        }
+      },
+      "functions": [
+        {
+          "script_score": {
+            "script_id": "indexedCalculateScore",
+            "params": {
+              "my_modifier": 8
+            }
+          }
+        }
+      ]
+    }
+  }
+}'
+--------------------------------------------------
+Note that you must have dynamic scripting enabled to use indexed scripts
+at query time.
+
+The script can be viewed by:
+[source,js]
+-----------------------------------
+curl -XGET localhost:9200/_scripts/mvel/calculate-score
+-----------------------------------
+
+This is rendered as:
+
+[source,js]
+-----------------------------------
+'{
+     "script": "log(_score * 2) + my_modifier"
+}'
+-----------------------------------
+
+Indexed scripts can be deleted by:
+[source,js]
+-----------------------------------
+curl -XDELETE localhost:9200/_scripts/mvel/calculate-score
+-----------------------------------
+
+
+
 [float]
 === Enabling dynamic scripting
 

docs/reference/query-dsl/queries/template-query.asciidoc

@@ -95,6 +95,46 @@ which is then turned into:
 }
 ------------------------------------------
 
+added[1.3.0]
+
+You can register a template by storing it in the elasticsearch index `.scripts` or by using the REST API. (See <<search-template>> for more details)
+In order to execute the stored template, reference it by name in the `query`
+parameter:
+
+
+[source,js]
+------------------------------------------
+GET /_search
+{
+    "query": {
+        "template": {
+            "query": "templateName", <1>
+            "params" : {
+                "template" : "all"
+            }
+        }
+    }
+}
+------------------------------------------
+<1> Name of the the query template stored in the index.
+
+[source,js]
+------------------------------------------
+GET /_search
+{
+    "query": {
+        "template": {
+            "query": "storedTemplate", <1>
+            "params" : {
+                "template" : "all"
+            }
+        }
+    }
+}
+
+------------------------------------------
+
+
 There is also a dedicated `template` endpoint, allows you to template an entire search request.
 Please see <<search-template>> for more details.
 

docs/reference/search/search-template.asciidoc

@@ -213,11 +213,78 @@ In order to execute the stored template, reference it by it's name under the `te
 ------------------------------------------
 GET /_search/template
 {
-    "template": "storedTemplate" <1>,
+    "template": {
+        "file": "storedTemplate" <1>,
+    },
     "params": {
         "query_string": "search for these words"
     }
 }
 ------------------------------------------
 
-<1> Name of the the query template in `config/scripts/`, i.e., `storedTemplate.mustache`.
+<1> Name of the the query template in `config/scripts/`, i.e., `storedTemplate.mustache`.
+
+added[1.3.0]
+
+You can also register search templates by storing it in the elasticsearch cluster in a special index named `.scripts`.
+There are REST APIs to manage these indexed templates.
+
+[source,js]
+------------------------------------------
+POST /_search/template/<templatename>
+{
+    "template": {
+        "query": {
+            "match": {
+                "title": "{{query_string}}"
+            }
+        }
+    }
+}
+
+This template can be retrieved by
+
+[source,js]
+------------------------------------------
+GET /_search/template/<templatename>
+------------------------------------------
+
+which is rendered as:
+
+[source,js]
+------------------------------------------
+{
+    "template": {
+        "query": {
+            "match": {
+                "title": "{{query_string}}"
+            }
+        }
+    }
+}
+------------------------------------------
+
+This template can be deleted by
+
+[source,js]
+------------------------------------------
+DELETE /_search/template/<templatename>
+------------------------------------------
+
+To use an indexed template at search time use:
+
+
+[source,js]
+------------------------------------------
+GET /_search/template
+{
+    "template": {
+        "id": "templateName" <2>,
+    },
+    "params": {
+        "query_string": "search for these words"
+    }
+}
+------------------------------------------
+
+<2> Name of the the query template stored in the .scripts index.

rest-api-spec/api/indexed_script.create.json

@@ -1,10 +1,10 @@
 {
-  "indexed_script.create": {
-    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/indexed-scripts.html",
+  "put_script": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-scripting.html",
     "methods": ["PUT", "POST"],
     "url": {
-      "path": "/_search/script/{lang}/{id}",
-      "paths": [ "/_search/script/{lang}/{id}" ],
+      "path": "/_scripts/{lang}/{id}",
+      "paths": [ "/_scripts/{lang}/{id}" ],
       "parts": {
         "id": {
           "type" : "string",

rest-api-spec/api/indexed_script.delete.json

@@ -1,10 +1,10 @@
 {
-  "indexed_script.delete": {
-    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/indexed-scripts.html",
+  "delete_script": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-scripting.html",
     "methods": ["DELETE"],
     "url": {
-      "path": "/_search/script/{lang}/{id}",
-      "paths": [ "/_search/script/{lang}/{id}" ],
+      "path": "/_scripts/{lang}/{id}",
+      "paths": [ "/_scripts/{lang}/{id}" ],
       "parts": {
         "id": {
           "type" : "string",

rest-api-spec/api/indexed_script.get.json

@@ -1,10 +1,10 @@
 {
-  "indexed_script.get": {
-    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/indexed-scripts.html",
+  "get_script": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/modules-scripting.html",
     "methods": ["GET"],
     "url": {
-      "path": "/_search/script/{lang}/{id}",
-      "paths": [ "/_search/script/{lang}/{id}" ],
+      "path": "/_scripts/{lang}/{id}",
+      "paths": [ "/_scripts/{lang}/{id}" ],
       "parts": {
         "id": {
           "type" : "string",

rest-api-spec/api/indexed_template.create.json

@@ -1,6 +1,6 @@
 {
-  "indexed_template.create": {
-    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/indexed-scripts.html",
+  "put_template": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/search-template.html",
     "methods": ["PUT", "POST"],
     "url": {
       "path": "/_search/template/{id}",

rest-api-spec/api/indexed_template.delete.json

@@ -1,6 +1,6 @@
 {
-  "indexed_template.delete": {
-    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/indexed-scripts.html",
+  "delete_template": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/search-template.html",
     "methods": ["DELETE"],
     "url": {
       "path": "/_search/template/{id}",

rest-api-spec/api/indexed_template.get.json

@@ -1,6 +1,6 @@
 {
-  "indexed_template.get": {
-    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/indexed-scripts.html",
+  "get_template": {
+    "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/search-template.html",
     "methods": ["GET"],
     "url": {
       "path": "/_search/template/{id}",

rest-api-spec/test/script/10_basic.yaml

@@ -2,20 +2,20 @@
 "Indexed script":
 
   - do:
-      indexed_script.create:
+      put_script:
         id: "1"
         lang: "groovy"
         body: { "script":  "_score * doc[\"myParent.weight\"].value" }
   - match: { _id: "1" }
 
   - do:
-     indexed_script.get:
+     get_script:
        id: "1"
        lang: "groovy"
   - match: { "script":  "_score * doc[\"myParent.weight\"].value" }
 
   - do:
-     indexed_script.delete:
+     delete_script:
        id: "1"
        lang: "groovy"
   - match: { found: true }
@@ -24,7 +24,7 @@
 
   - do:
       catch: request
-      indexed_script.create:
+      put_script:
         id: "1"
         lang: "groovy"
         body: { "script":  "_score * foo bar + doc[\"myParent.weight\"].value" }
@@ -33,7 +33,7 @@
 
   - do:
       catch: request
-      indexed_script.create:
+      put_script:
         id: "1"
         lang: "foobar"
         body: { "script" :  "_score * doc[\"myParent.weight\"].value" }

rest-api-spec/test/template/10_basic.yaml

@@ -2,19 +2,19 @@
 "Indexed template":
 
   - do:
-      indexed_template.create:
+      put_template:
         id: "1"
         body: { "template": { "query": { "match_all": {}}, "size": "{{my_size}}" } }
   - match: { _id: "1" }
 
   - do:
-     indexed_template.get:
+     get_template:
        id: 1
   - match: { template: /.*query\S\S\S\Smatch_all.*/ }
 
 
   - do:
-     indexed_template.delete:
+     delete_template:
        id: "1"
   - match: { found: true }
   - match: { _index: ".scripts" }
@@ -22,7 +22,7 @@
 
   - do:
       catch: request
-      indexed_template.create:
+      put_template:
         id: "1"
         body: { "template": { "query": { "match{{}}_all": {}}, "size": "{{my_size}}" } }
   - match: { "error": /ElasticsearchIllegalArgumentException\SUnable\sto\sparse.*/ }

rest-api-spec/test/template/20_search.yaml

@@ -17,7 +17,7 @@
       indices.refresh: {}
 
   - do:
-      indexed_template.create:
+      put_template:
         id: "1"
         body: { "template": { "query": { "match" : { "text": "{{my_value}}" } }, "size": "{{my_size}}" } }
   - match: { _id: "1" }

src/main/java/org/elasticsearch/rest/action/script/RestDeleteIndexedScriptAction.java

@@ -42,7 +42,7 @@ public class RestDeleteIndexedScriptAction extends BaseRestHandler {
     public RestDeleteIndexedScriptAction(Settings settings, Client client,
                                          ScriptService scriptService, RestController controller) {
         super(settings, client);
-        controller.registerHandler(DELETE, "/_search/script/{lang}/{id}", this);
+        controller.registerHandler(DELETE, "/_scripts/{lang}/{id}", this);
         this.scriptService = scriptService;
     }
 

src/main/java/org/elasticsearch/rest/action/script/RestGetIndexedScriptAction.java

@@ -50,7 +50,7 @@ public class RestGetIndexedScriptAction extends BaseRestHandler {
     public RestGetIndexedScriptAction(Settings settings, Client client,
                                       ScriptService scriptService, RestController controller) {
         super(settings, client);
-        controller.registerHandler(GET, "/_search/script/{lang}/{id}", this);
+        controller.registerHandler(GET, "/_scripts/{lang}/{id}", this);
     }
 
     @Override

src/main/java/org/elasticsearch/rest/action/script/RestPutIndexedScriptAction.java

@@ -45,12 +45,11 @@ public class RestPutIndexedScriptAction extends BaseRestHandler {
     public RestPutIndexedScriptAction(Settings settings, Client client, RestController controller) {
         super(settings, client);
 
-        //controller.registerHandler(GET, "/template", this);
-        controller.registerHandler(POST, "/_search/script/{lang}/{id}", this);
-        controller.registerHandler(PUT, "/_search/script/{lang}/{id}", this);
+        controller.registerHandler(POST, "/_scripts/{lang}/{id}", this);
+        controller.registerHandler(PUT, "/_scripts/{lang}/{id}", this);
 
-        controller.registerHandler(PUT, "/_search/script/{lang}/{id}/_create", new CreateHandler(settings, client));
-        controller.registerHandler(POST, "/_search/script/{lang}/{id}/_create", new CreateHandler(settings, client));
+        controller.registerHandler(PUT, "/_scripts/{lang}/{id}/_create", new CreateHandler(settings, client));
+        controller.registerHandler(POST, "/_scripts/{lang}/{id}/_create", new CreateHandler(settings, client));
     }
 
     final class CreateHandler extends BaseRestHandler {