From cbd2a97abd74a4c592723002f70c8f12dada70b6 Mon Sep 17 00:00:00 2001 From: Brian Murphy Date: Wed, 16 Jul 2014 10:46:55 +0100 Subject: [PATCH] [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 | 78 +++++++++++++++++++ .../query-dsl/queries/template-query.asciidoc | 40 ++++++++++ .../reference/search/search-template.asciidoc | 71 ++++++++++++++++- rest-api-spec/api/indexed_script.create.json | 8 +- rest-api-spec/api/indexed_script.delete.json | 8 +- rest-api-spec/api/indexed_script.get.json | 8 +- .../api/indexed_template.create.json | 4 +- .../api/indexed_template.delete.json | 4 +- rest-api-spec/api/indexed_template.get.json | 4 +- rest-api-spec/test/script/10_basic.yaml | 10 +-- rest-api-spec/test/template/10_basic.yaml | 8 +- rest-api-spec/test/template/20_search.yaml | 2 +- .../script/RestDeleteIndexedScriptAction.java | 2 +- .../script/RestGetIndexedScriptAction.java | 2 +- .../script/RestPutIndexedScriptAction.java | 9 +-- 15 files changed, 221 insertions(+), 37 deletions(-) diff --git a/docs/reference/modules/scripting.asciidoc b/docs/reference/modules/scripting.asciidoc index 5ec55fa7070..16c86f1a50c 100644 --- a/docs/reference/modules/scripting.asciidoc +++ b/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 diff --git a/docs/reference/query-dsl/queries/template-query.asciidoc b/docs/reference/query-dsl/queries/template-query.asciidoc index e10faebaeb9..2f6e086528e 100644 --- a/docs/reference/query-dsl/queries/template-query.asciidoc +++ b/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 <> 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 <> for more details. diff --git a/docs/reference/search/search-template.asciidoc b/docs/reference/search/search-template.asciidoc index 91bc01e8887..103ee87dd97 100644 --- a/docs/reference/search/search-template.asciidoc +++ b/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`. \ No newline at end of file +<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/ +{ + "template": { + "query": { + "match": { + "title": "{{query_string}}" + } + } + } +} + +This template can be retrieved by + +[source,js] +------------------------------------------ +GET /_search/template/ +------------------------------------------ + +which is rendered as: + +[source,js] +------------------------------------------ +{ + "template": { + "query": { + "match": { + "title": "{{query_string}}" + } + } + } +} +------------------------------------------ + +This template can be deleted by + +[source,js] +------------------------------------------ +DELETE /_search/template/ +------------------------------------------ + +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. \ No newline at end of file diff --git a/rest-api-spec/api/indexed_script.create.json b/rest-api-spec/api/indexed_script.create.json index eb8a42b8a5e..c7ae9510eca 100644 --- a/rest-api-spec/api/indexed_script.create.json +++ b/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", diff --git a/rest-api-spec/api/indexed_script.delete.json b/rest-api-spec/api/indexed_script.delete.json index c62238d34a5..07dcdbb8b91 100644 --- a/rest-api-spec/api/indexed_script.delete.json +++ b/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", diff --git a/rest-api-spec/api/indexed_script.get.json b/rest-api-spec/api/indexed_script.get.json index c83bbe32e53..ad913cd27fb 100644 --- a/rest-api-spec/api/indexed_script.get.json +++ b/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", diff --git a/rest-api-spec/api/indexed_template.create.json b/rest-api-spec/api/indexed_template.create.json index 77d7f89e545..e3daf88bcb1 100644 --- a/rest-api-spec/api/indexed_template.create.json +++ b/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}", diff --git a/rest-api-spec/api/indexed_template.delete.json b/rest-api-spec/api/indexed_template.delete.json index a52cbb2cbf5..7c66d787a01 100644 --- a/rest-api-spec/api/indexed_template.delete.json +++ b/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}", diff --git a/rest-api-spec/api/indexed_template.get.json b/rest-api-spec/api/indexed_template.get.json index 05977de6c9a..42a5b03d684 100644 --- a/rest-api-spec/api/indexed_template.get.json +++ b/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}", diff --git a/rest-api-spec/test/script/10_basic.yaml b/rest-api-spec/test/script/10_basic.yaml index e95e2080e38..110ee8e20a3 100644 --- a/rest-api-spec/test/script/10_basic.yaml +++ b/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" } diff --git a/rest-api-spec/test/template/10_basic.yaml b/rest-api-spec/test/template/10_basic.yaml index 2e65dad6c25..867f2b11a81 100644 --- a/rest-api-spec/test/template/10_basic.yaml +++ b/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.*/ } diff --git a/rest-api-spec/test/template/20_search.yaml b/rest-api-spec/test/template/20_search.yaml index f9303341f8f..bcfe0203bf6 100644 --- a/rest-api-spec/test/template/20_search.yaml +++ b/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" } diff --git a/src/main/java/org/elasticsearch/rest/action/script/RestDeleteIndexedScriptAction.java b/src/main/java/org/elasticsearch/rest/action/script/RestDeleteIndexedScriptAction.java index c7e8b4c73d2..8a48bfba13c 100644 --- a/src/main/java/org/elasticsearch/rest/action/script/RestDeleteIndexedScriptAction.java +++ b/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; } diff --git a/src/main/java/org/elasticsearch/rest/action/script/RestGetIndexedScriptAction.java b/src/main/java/org/elasticsearch/rest/action/script/RestGetIndexedScriptAction.java index 9fae4ac3061..1d383b49060 100644 --- a/src/main/java/org/elasticsearch/rest/action/script/RestGetIndexedScriptAction.java +++ b/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 diff --git a/src/main/java/org/elasticsearch/rest/action/script/RestPutIndexedScriptAction.java b/src/main/java/org/elasticsearch/rest/action/script/RestPutIndexedScriptAction.java index c83f1519065..09ed78a5999 100644 --- a/src/main/java/org/elasticsearch/rest/action/script/RestPutIndexedScriptAction.java +++ b/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 {