1. Overview
Full-text search queries and performs linguistic searches against documents. It includes single or multiple words or phrases and returns documents that match search condition.
ElasticSearch is a search engine based on Apache Lucene, a free and open-source information retrieval software library. It provides a distributed, full-text search engine with an HTTP web interface and schema-free JSON documents.
This article examines ElasticSearch REST API and demonstrates basic operations using HTTP requests only.
2. Setup
In order to install ElasticSearch on your machine, please refer to the official setup guide.
RESTfull API runs on port 9200. Let us test if it is running properly using the following curl command:
curl -XGET 'http://localhost:9200/'
If you observe the following response, the instance is properly running:
{
"name": "NaIlQWU",
"cluster_name": "elasticsearch",
"cluster_uuid": "enkBkWqqQrS0vp_NXmjQMQ",
"version": {
"number": "5.1.2",
"build_hash": "c8c4c16",
"build_date": "2017-01-11T20:18:39.146Z",
"build_snapshot": false,
"lucene_version": "6.3.0"
},
"tagline": "You Know, for Search"
}
3. Indexing Documents
ElasticSearch is document oriented. It stores and indexes documents. Indexing creates or updates documents. After indexing, you can search, sort, and filter complete documents—not rows of columnar data. This is a fundamentally different way of thinking about data and is one of the reasons ElasticSearch can perform a complex full-text search.
Documents are represented as JSON objects. JSON serialization is supported by most programming languages and has become the standard format used by the NoSQL movement. It is simple, concise, and easy to read.
We are going to use the following random entries to perform our full-text search:
{
"title": "He went",
"random_text": "He went such dare good fact. The small own seven saved man age."
}
{
"title": "He oppose",
"random_text":
"He oppose at thrown desire of no. \
Announcing impression unaffected day his are unreserved indulgence."
}
{
"title": "Repulsive questions",
"random_text": "Repulsive questions contented him few extensive supported."
}
{
"title": "Old education",
"random_text": "Old education him departure any arranging one prevailed."
}
Before we can index a document, we need to decide where to store it. It’s possible to have multiple indexes, which in turn contain multiple types. These types hold multiple documents, and each document has multiple fields.
We are going to store our documents using the following scheme:
text: The index name.
article: The type name.
id: The ID of this particular example text-entry.
To add a document we are going to run the following command:
curl -XPUT 'localhost:9200/text/article/1?pretty'
-H 'Content-Type: application/json' -d '
{
"title": "He went",
"random_text":
"He went such dare good fact. The small own seven saved man age."
}'
Here we are using id=1, we can add other entries using the same command and incremented id.
4. Retrieving Documents
After we add all our documents we can check how many documents, using the following command, we have in the cluster :
curl -XGET 'http://localhost:9200/_count?pretty' -d '
{
"query": {
"match_all": {}
}
}'
Also, we can get a document using its id with the following command:
curl -XGET 'localhost:9200/text/article/1?pretty'
And we should get the following answer from elastic search:
{
"_index": "text",
"_type": "article",
"_id": "1",
"_version": 1,
"found": true,
"_source": {
"title": "He went",
"random_text":
"He went such dare good fact. The small own seven saved man age."
}
}
As we can see this answer correspond with the entry added using the id 1.
5. Querying Documents
OK let’s perform a full-text search with the following command:
curl -XGET 'localhost:9200/text/article/_search?pretty'
-H 'Content-Type: application/json' -d '
{
"query": {
"match": {
"random_text": "him departure"
}
}
}'
And we get the following result:
{
"took": 32,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"failed": 0
},
"hits": {
"total": 2,
"max_score": 1.4513469,
"hits": [
{
"_index": "text",
"_type": "article",
"_id": "4",
"_score": 1.4513469,
"_source": {
"title": "Old education",
"random_text": "Old education him departure any arranging one prevailed."
}
},
{
"_index": "text",
"_type": "article",
"_id": "3",
"_score": 0.28582606,
"_source": {
"title": "Repulsive questions",
"random_text": "Repulsive questions contented him few extensive supported."
}
}
]
}
}
As we can see we are looking for “him departure” and we get two results with different scores. The first result is obvious because the text have the performed search inside of it and as we can see we have the score of 1.4513469.
The second result is retrieved because the target document contains the word “him”.
By default, ElasticSearch sorts matching results by their relevance score, that is, by how well each document matches the query. Note, that the score of the second result is small relative to the first hit, indicating lower relevance.
6. Fuzzy Search
Fuzzy matching treats two words that are “fuzzily” similar as if they were the same word. First, we need to define what we mean by fuzziness.
Elasticsearch supports a maximum edit distance, specified with the fuzziness parameter, of 2. The fuzziness parameter can be set to AUTO, which results in the following maximum edit distances:
- 0 for strings of one or two characters
- 1 for strings of three, four, or five characters
- 2 for strings of more than five characters
you may find that an edit distance of 2 returns results that don’t appear to be related.
You may get better results, and better performance, with a maximum fuzziness of 1. Distance refers to the Levenshtein distance that is a string metric for measuring the difference between two sequences. Informally, the Levenshtein distance between two words is the minimum number of single-character edits.
OK let us perform our search with fuzziness:
curl -XGET 'localhost:9200/text/article/_search?pretty' -H 'Content-Type: application/json' -d'
{
"took": 88,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"failed": 0
},
"hits": {
"total": 4,
"max_score": 1.4513469,
"hits": [
{
"_index": "text",
"_type": "article",
"_id": "4",
"_score": 1.4513469,
"_source": {
"title": "Old education",
"random_text": "Old education him departure any arranging one prevailed."
}
},
{
"_index": "text",
"_type": "article",
"_id": "2",
"_score": 0.39833328,
"_source": {
"title": "He oppose",
"random_text":
"He oppose at thrown desire of no.
\ Announcing impression unaffected day his are unreserved indulgence."
}
},
{
"_index": "text",
"_type": "article",
"_id": "3",
"_score": 0.28582606,
"_source": {
"title": "Repulsive questions",
"random_text": "Repulsive questions contented him few extensive supported."
}
},
{
"_index": "text",
"_type": "article",
"_id": "1",
"_score": 0.0,
"_source": {
"title": "He went",
"random_text": "He went such dare good fact. The small own seven saved man age."
}
}
]
}
}'
As we can see the fuzziness give us more results.
We need to use fuzziness carefully because it tends to retrieve results that look unrelated.
7. Conclusion
In this quick tutorial we focused on indexing documents and querying Elasticsearch for full-text search, directly via it’s REST API.
We of course have APIs available for multiple programming languages when we need to – but the API is still quite convenient and language agnostic.