Elasticsearch provides the capability of providing a template and some parameters to fill it. This functionality is very useful, because it allows managing query templates stored on the server filesystem or in the .scripts index and allows changing them without change in the application code.
You need a working Elasticsearch cluster and an index populated with the chapter_05/populate_query.sh geo script available in the online code.
The template query is composed of two components: the query and the parameters that must be filled in. We can execute a template query in several ways.
Using the new REST entrypoint _search/template is the best way to use the templates. To use it, perform the following steps:
- We execute the query as follows:
curl -XPOST 'http://127.0.0.1:9200/_search/template?pretty' -d' { "inline": { "query": { "term": { "uuid": "{{value}}" } } }, "params": { "value": "22222" } }' - The result returned by Elasticsearch, if everything is alright, should be:
{ "took" : 1, "timed_out" : false, "_shards" : { "total" : 10, "successful" : 10, "failed" : 0 }, "hits" : { "total" : 1, "max_score" : 0.2876821, "hits" : [ { "_index" : "test-index", "_type" : "test-type", "_id" : "2", "_score" : 0.2876821, "_source" : { "position" : 2, "parsedtext" : "Bill Testere nice guy", "name" : "Bill Baloney", "uuid" : "22222", "price" : 5.0 } } ] } }
If we want to use an indexed stored template, the steps are as follows:
- We store the template in the
.scriptsindex:curl -XPOST 'http://127.0.0.1:9200/_search/template/ myTemplate' -d ' { "template": { "query": { "term": { "uuid": "{{value}}" } } } }' - Now we can call the template with the following code:
curl -XPOST 'http://127.0.0.1:9200/test-index/test- type/_search/template?pretty=true' -d '{ "id": "myTemplate", "params": { "value": "22222" } }'
If you have a stored template and you want to validate it, you can use the REST render entry-point.
For the preceding result, the following are the steps:
- We render the template via the
_render/templateREST:curl -XPOST 'http://127.0.0.1:9200/_render/template? pretty' -d'{ "id": "myTemplate", "params": { "value": "22222" } }' - The result will be :
{ "template_output" : { "query" : { "term" : { "uuid" : "22222" } } } }
A template query is composed of two components:
- A template is a query object that is supported by Elasticsearch. The template uses the
mustache(http://mustache.github.io/) syntax, a very common syntax to express templates. - An optional dictionary of parameters that is used to fill the template.
When the search query is called, the template is loaded, populated with the parameters data, and executed as a normal query. The template query is a shortcut to use the same query with different values.
Typically, the template is generated executing the query in the standard way and then adding parameters if required in the process of templating it; the template query allows also defining the template as a string, but the user must pay attention to escaping it (refer to the official documentation at https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-template-query.html for escaping templates).
It allows removing the query execution from application code and putting it on the filesystem or indices.
The template query can retrieve a previous stored template from disk (it must be stored in the config/scripts directory with the .mustache extension) or in the special index .scripts.
The search template can be managed in Elasticsearch via the special end points /_search/template. They are used as follows:
- To store a template type the following command:
curl -XPOST
'http://127.0.0.1:9200/_search/template/<template_name>' -d
<template_body>
- To retrieve a template type the following command:
curl -XGET
'http://127.0.0.1:9200/_search/template/<template_name>'
- To delete a template type the following command:
curl -XDELETE
'http://127.0.0.1:9200/_search/template/<template_name>'
- Check the official mustache documentation at http://mustache.github.io/to learn the template syntax.
- Check the official Elasticsearch documentation about search template at https://www.elastic.co/guide/en/elasticsearch/reference/master/search-template.html for more samples using the template syntax.
- Check the official Elasticsearch documentation about query template at https://www.elastic.co/guide/en/elasticsearch/reference/master/query-dsl-template-query.html with some samples of query usage.