The suggest API is one of the important APIs in Elasticsearch. It is used extensively in search solutions to tremendously improve the user experience. Ranging from normal autocomplete to context based suggestions, this API has many interesting use cases, which we will explore. In this tutorial, we show how to implement a simple autocomplete with elasticsearch.

Document Sample

A sample document for populating the index for this blog is given below:

{
fullName: "Alex Sat",
city : "New York"
}

Here we plan to implement the auto complete feature on the field "city".

The data set we use in this tutorial, containing 1000 such documents, can be found here.

Index Creation and Mapping

For the purpose of this tutorial, create an index with the name "autosuggest".

curl -XPUT "http://localhost:9200/autosuggest"

Create the mapping for the above documents along with the suggest field in consideration.

curl -X PUT localhost:9200/autosuggest/mytype/_mapping -d ' {
 "mytype": {
   "properties": {
     "fullName": {
       "type": "string"
     },
     "city": {
       "type": "string"
     },
     "citySuggest": {
       "type": "completion",
       "analyzer": "simple",
       "search_analyzer": "simple",
       "payloads": true
     }
   }
 }
}’

In the above mapping, you can see that along with the fields "fullName" and "city" which are in the document, another field called "citySuggest" is also given within the mapping. This field is not in our data, and is specific for autosuggest. The reason for its existence and usage is explained in the next section.

Indexing the Documents

Here is how a sample document was indexed:

curl -X PUT 'localhost:9200/autosuggest/mytype/44' -d '{
 "fullName": "Anna Reyes",
 "city": "At Tall al Kabīr",
 "citySuggest": {
   "input": [
     "At",
     "Tall",
     "al",
     "Kabir"
   ],
   "output": "At Tall al Kabīr"
 }
}'

In the above example, you can see that there is the extra field called "citySuggest" in our indexed documents. This field was not present in the original document. Also, you can see in the new field there are two lists named "input" and "output". In the input section, we are giving the space split values in the field "city". In the output, the expected output for the value of the field "city" is given.

The code for indexing the entire data set can be found in this repo.

How Auto Suggestion Works

In the above section, you saw how the documents were indexed with an extra field, of which contained the "input" and "output" list. This implementation is for aiding the FST, (finite state transducers). In the FST method, we have two bands, which are the "input" and the "output" band. Each specific state defines a binary relation between the input and the output values. In the above indexing example, we can see such a relation, where any input of "At", "Tall", "al""Kabir" is related to output word "At Tall al Kabir".

We can query such an occurrence with the query below:

curl -XPOST 'http://localhost:9233/autosuggest/_suggest' -d ' {
 "city-suggest": {
"text": "luis",
"completion": {
 "field": "citySuggest"
}
 }
}’
For the above query we get the results like below:
{
 "_shards": {
   "total": 5,
   "successful": 5,
   "failed": 0
 },
 "city-suggest": [
   {
     "text": "luis",
     "offset": 0,
     "length": 4,
     "options": [
       {
         "text": "Fray Luis A. Beltrán",
         "score": 1
       },
       {
         "text": "Luisiana",
         "score": 1
       }
     ]
   }
 ]
}

In the above response, you can see that there are suggestions with the text "luis" in it. We can consider another scenario where we replace the "luis" with "At" and see the results we get. In that result set, you can see the suggestions with the names starting with "At" or having "at" in them.

Conclusion

In this tutorial, we have covered the most basic Suggest API of Elasticsearch, along with some examples. In future tutorials, we will cover phrase suggesters, and context-based autocomplete. 

comments powered by Disqus