With the release of Elasticsearch 1.1.0, we were given the possibility of defining a template. Let's get back to our example library e-commerce store that we started working on in the beginning of this book. Let's assume that we already know what type of queries should be sent to Elasticsearch, but the query structure is not final—we will still work on the queries and improve them. By using the query templates, we can quickly supply the basic version of the query, let application specify the parameters, and modify the query on the Elasticsearch side until the query parameters change.

Let's assume that one of our queries needs to return the most relevant books from our library index. We also allow users to choose whether they are interested in books that are available or the ones that are not available. In such a case, we will need to provide two parameters—the phrase itself and the Boolean that specifies the availability. The first, simplified example of our query could looks as follows:

{
 "query": {
  "filtered": {
   "query": {
    "match": {
     "_all": "QUERY"
    }
   },
   "filter": {
    "term": {
     "available": BOOLEAN
    }
   }
  }
 }
}

The QUERY and BOOLEAN are placeholders for variables that will be passed to the query by the application. Of course, this query is too simple for our use case, but as we already said, this is only its first version—we will improve it in just a second.

Having our first query, we can now create our first template. Let's change our query a bit so that it looks as follows:

{
  "template": {
   "query": {
    "filtered": {
     "query": {
      "match": {
       "_all": "{{phrase}}"
      }
     },
     "filter": {
      "term": {
       "available": "{{avail}}"
      }
     }
    }
   }
  },
  "params": {
   "phrase": "front",
   "avail": true
  }
}

You can see that our placeholders were replaced by {{phrase}} and {{avail}}, and a new section params was introduced. When encountering a section like {{phrase}}, Elasticsearch will go to the params section and look for a parameter called phrase and use it. In general, we've moved the parameter values to the params section, and in the query itself we use references using the {{var}} notation, where var is the name of the parameter from the params section. In addition, the query itself is nested in the template element. This way we can parameterize our queries.

Let's now send the preceding query to the /library/_search/template REST endpoint (not the /library/_search as we usually do) using the GET HTTP method. To do this, we will use the following command:

curl -XGET 'localhost:9200/library/_search/template?pretty' -d '{
 "template": {
   "query": {
    "filtered": {
     "query": {
      "match": {
       "_all": "{{phrase}}"
      }
     },
     "filter": {
      "term": {
       "available": "{{avail}}"
      }
     }
    }
   }
  },
  "params": {
   "phrase": "front",
   "avail": true
  }
}'

{
  "template": "{ "query": { "filtered": { "query": {  "match": { "_all": "{{phrase}}" } }, "filter": {  "term": { "available": "{{avail}}" } } } } }",
   "params": {
      "phrase": "front",
      "avail": true
   }
}

Elasticsearch uses Mustache templates (see: http://mustache.github.io/) to generate resulting queries from templates. As you have already seen, every variable is surrounded by double curly brackets and this is specific to Mustache and is a method of dereferencing variables in this template engine. The full syntax of the Mustache template engine is beyond the scope of this book, but we would like to briefly introduce you to the most interesting parts of it: conditional expression, loops, and default values.

curl -XGET 'localhost:9200/library/_search/template?pretty' -d '{
  "template": "{ {{#limit}}"size": 2 {{/limit}}}",
  "params": {
   "limit": false
  }
}'

curl -XGET 'localhost:9200/library/_search/template?pretty' -d '{
  "template": {
   "query": {
    "terms": {
     "title": [
      "{{#title}}",
      "{{.}}",
      "{{/title}}"
     ]
    }
   }
  },
  "params": {
   "title": [ "front", "crime" ]
  }
}'

{{var}}{{^var}}default value{{/var}}

curl -XGET 'localhost:9200/library/_search/template?pretty' -d '{
  "template": {
   "query": {
    "term": {
     "title": "{{phrase}}{{^phrase}}crime{{/phrase}}"
    }
   }
  },
  "params": {
   "phrase": "front"
  }
}'

Regardless of the way we defined our templates previously, we were still a long way from decoupling them from the application. We still needed to store the whole query in the application, we were only able to parameterize the query. Fortunately, there is a simple way to change the query definition so it can be read dynamically by Elasticsearch from the config/scripts directory.

For example, let's create a file called bookList.mustache (in the config/scripts/ directory) with the following contents:

{
 "query": {
  "filtered": {
   "query": {
    "match": {
     "_all": "{{phrase}}"
    }
   },
   "filter": {
    "term": {
     "available": "{{avail}}"
    }
   }
  }
 }
}

We can now use the contents of that file in a query by specifying the template name (the name of the template is the name of the file without the .mustache extension). For example, if we would like to use our bookList template, we would send the following command:

curl -XGET 'localhost:9200/library/_search/template?pretty' -d '{
  "template": "bookList",
  "params": {
   "phrase": "front",
   "avail": true
  }
}'