Main Tutorials

ElasticSearch Hello World Example

ElasticSearch is an Open-source Enterprise REST based Real-time Search and Analytics Engine. It’s core Search Functionality is built using Apache Lucene, but supports many other features.

It is written in Java Language. It supports Store, Index, Search and Analyze Data in Real-time. Like MongoDB, ElasticSearch is also a Document-based NoSQL Data Store.

Note
ElasticSearch website: www.elastic.co. The latest version of ElasticSearch is 5.2.1, which was released on 14th Feb 2017.

ElasticSearch Features:-

  • An Open-source
  • Supports Full-text Simple and Powerful Search
  • Supports REST Based API (JSON over HTTP)
  • Supports Real-time Search and Analytics
  • By Definition, Distributed
  • Supports Multi Tenancy Feature
  • Support Cloud and Big Data Environments
  • Supports Cross-platform
  • Denormalized NoSQL Data Store

Advantages or Benefits of ElasticSearch:-

  • An Open-source
  • Light Weight with REST API
  • Highly Available. Easily and Highly Scalable
  • Supports Caching Data
  • Schema Free
  • Fast Search Performance
  • Supports both Structured and UN-Structured Data
  • Supports Distributed, Sharding, Replication, Clustering and Multi-Node Architecture
  • Supports Bulk Operations
  • Build Charts and Dashboards within no time

Drawbacks or Limitations of ElasticSearch:-

  • Does NOT support MapReduce operations
  • Not useful as a Primary Data Store
  • Not an ACID compliant Data Store
  • Does not support Transactions and Distributed Transactions
  • Does NOT have built-in authentication or authorization feature

Popular Clients who are using ElasticSearch:-

  • Github.com, Quora.com, Stackoverflow.com
  • eBay, DELL, Cisco, Mozilla, Wikimedia
  • Netflix, Symatics, Facebook
  • UK HMRC (HM Revenue & Customs)

For instance, Github.com uses ElasticSearch to search files, history, ticket numbers etc. Most of the companies uses ELK stack to manage their logs and to monitor their systems. ELK stands for ElasticSearch Logstash and Kibana.

Note
You can find a more Customer’s use-cases at https://www.elastic.co/use-cases

1. Install ElasticSearch Locally

Note
As we know, ElasticSearch is written in Java. So, we should have Java/JRE in our System Path to use it. Please install and setup Java Environment properly.

To install ElasticSearch to your local File System, please follow these instructions.

1.1 Download ElasticSearch from https://www.elastic.co/downloads/elasticsearch

1.2 Windows

  • Download and extract Zip file to local File system: elasticsearch-5.2.1.zip
  • Extracted Zip file to F:\elasticsearch-5.2.1
  • Set Environment Variable
  • 
         PATH = F:\elasticsearch-5.2.1\bin
    	
  • Start ElasticSearch
  • 
    	 F:/>elasticsearch.bat      
    	
  • Access the ElasticSearch with http://localhost:9200 from browser. We can use Ctrl + C to stop the ElasticSearch from CMD prompt.

1.3 Ubuntu Linux: Install with tar file

  • Download and extract Tar file to local File system
  • 
        tar -xvf elasticsearch-5.2.1.tar.gz
    	
  • Start ElasticSearch
  • 
        $ ./elasticsearch	
    	
  • Access the ElasticSearch with http://localhost:9200 from browser

1.4 Ubuntu Linux: Install with commands

  • Execute the following command to download ElasticSearch
  •     
    	$ sudo wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-5.2.1.deb
    	

    It downloads ElasticSearch DEB file: elasticsearch-5.2.1.deb

  • Execute the following dpkg command to install ElasticSearch
  • 
    	$ sudo dpkg -i elasticsearch-5.2.1.deb
    	

    By default, it installs ElasticSearch at “/usr/share/elasticsearch”.

  • Start ElasticSearch
  • 
        $ ./elasticsearch
    	
  • Access the ElasticSearch with http://localhost:9200 from browser
Note
ElasticSearch default port number is 9200. If required, we can change this port number.

1.5 After ElasticSearch is started, access the default URL, we will get the following default Response

Browser : http://localhost:9200

{
  "name" : "rBvi0Hs",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "kOQQ_nqfTW-b4vQ00XSvdg",
  "version" : {
    "number" : "5.2.1",
    "build_hash" : "db0d481",
    "build_date" : "2017-02-09T22:05:32.386Z",
    "build_snapshot" : false,
    "lucene_version" : "6.4.1"
  },
  "tagline" : "You Know, for Search"
}
Note
You can find ElasticSearch source code at https://github.com/elastic/elasticsearch

2. ElasticSearch REST API URL Basics

ElasticSearch REST API URL should follow the following format.

Here

  • Server means any server name or host name like “myserver”. Sometimes we use Node + Port number like “myhost:9999”.
  • Index must be in lower case, otherwise it throws an Exception.
  • It is recommended to use Type also in lower case.

We will discuss more about this REST API usage and Exception with some examples in the coming sections.

3. ElasticSearch Terminology

We will discuss few important ElasticSearch Terminology: Index, Type, Document, Key, Value etc.

3.1 What is an Index in ElasticSearch?
In ElasticSearch, an Index is a collection of Documents. For instance, “bookstore” is a Document. Index is used for indexing, searching, updating and deleting Documents. It must be in lower case.

An Index is similar to Database in Relation Database World.

3.2 What is a Type in ElasticSearch?
In ElasticSearch, a Type is a category of similar Documents. That means we can group a set of similar Documents into a Type. As we know in real-world, a “bookstore” contains different kinds of items: a collection of “Books”, a collections Pens, Pencils, CDs etc. In the same way, “bookstore” Document (One kind of Index) can contain a collection of Types: books, pens,CDs etc.

A Type is similar to Table in Relation Database World.

3.3 What is a Document in ElasticSearch?
In ElasticSearch, a Document is an instance of a Type. It contains Data with Key and Value fairs. For instance, “title”:”Functional Programming In Java” is a Key:Value fair of a Document of Type:”Books”. Each Document has an id.

A Document is similar to a Row in a Table in Relation Database World. Key is Column name and value is Column value.

4. ElasticSearch Commands Basics

As we know, ElasticSearch supports REST-Based API (JSON Over HTTP Protocol) to support CRUD (Create Read Update Delete) operations. It uses HTTP methods to perform its operations.

HTTP Request Mothod Usage
GET To get or select or read data from ElasticSearch
POST To create or update data to ElasticSearch
PUT To create or update data to ElasticSearch
DELETE To delete or remove existing data from ElasticSearch
Note
To test ElasticSearch Operations, We can use any REST clients like POSTMAN, Fiddler, CURL command, Sense etc. I’m going to use Google Chrome POSTMAN to explore the ElasticSearch REST APIs. You can install POSTMAN or Sense as Chrome Extensions.

5. ElasticSearch CRUD Operations

Let us develop a Search functionality for Mkyong.com website using ElasticSearch to search Posts details, Author details etc.

5.1 CREATE Operation Example
To insert a new Document with /mkyong/posts/1001 and the following Request Data:


{
  "title": "Java 8 Optional In Depth",
  "category":"Java",
  "published_date":"23-FEB-2017",
  "author":"Rambabu Posa"
}

Here 1001 is Document id. It is used to identify it uniquely.

Description:-

  • To create a new Document, we use an HTTP POST request method.
  • Our Node:Port Number: http://localhost:9200
  • Index name: mkyong
  • Type name: posts
  • As Request body type as JSON or add request header: “Content-Type” : “application/json”
  • Click on “SEND” button to the Response.
  • We can observe the following Key:Value pairs in Response data.
  • 
    "_index":"mkyong"
    "_type":"posts"
    "result":"created"
    "created":true
    
  • We can observe the following logs in CMD prompt.
  • 
    [2017-02-26T21:10:33,941][INFO ][o.e.c.m.MetaDataCreateIndexService] [aH4GiIP] [mkyong] creating index, cause [auto(index api)], templates [], shards [5]/[1], mappings []
    [2017-02-26T21:10:35,790][INFO ][o.e.c.m.MetaDataMappingService] [aH4GiIP] [mkyong/KJsGZgF-Try0k4OHWAgARQ] create_mapping [posts]
    

Plese insert the following Documents in the same way:


"/mkyong/posts/1002"
{
  "title": "Elastic Search Basics",
  "category":"ElasticSearch",
  "published_date":"03-MAR-2017",
  "author":"Rambabu Posa"
}
"/mkyong/posts/1003"
{
  "title": "Spring + Spring Data + ElasticSearch",
  "category":"Spring",
  "published_date":"11-MAR-2017",
  "author":"Rambabu Posa"
}
"/mkyong/posts/1004"
{
  "title": "Spring + Spring Data + ElasticSearch",
  "category":"Spring Boot",
  "published_date":"23-MAR-2017",
  "author":"Rambabu Posa"
}

5.2 READ Operation Example
To read or query or select data from ElasticSearch, we should use “_search” at the end of the REAT API URL.

Description:-

  • You can observe “_search” in the URL.
  • Response shows: “total”:4 (Total 4 records found with that Index and Type.)

5.3 READ Operation With Query Parameters Example
We can use query parameters using “?q=:” syntax in Query to filter the records.

Description:-

  • We can observe the following Key:Value pairs in Response data. It tells total one record found in this search.
  • 
    "total":"1"
    "_id":"1002"
    

5.4 UPDATE Operation Example
Would like to update an existing Document data as shown below:

Description:-

  • We can observe the following Key:Value pairs in Response data. It tells Document is updated, but not created.
  • 
    "result":"updated"
    "created":"false"
    

Check the same Document

5.5 DELETE Operation Example
Would like to remove one Document whose _id = 1004

Description:-

  • We can observe the following Key:Value pairs in Response data. It tells Document is deleted successfully.
  • 
    "result":"deleted"
    "successful":"1"
    

6. Index must be in lower case

As we discussed, Index must be in lower case. Otherwise, it throws an error as shown below:

As we are NOT using Index: “Mkyong” in lower case, it throws a very meaningful error message: “Invalid index name [Mkyong], must be lowercase”.

Note
Type may be in upper case, but it is not recommended.

References

  1. Wikipedia ElasticSearch
  2. ElasticSearch Doc
  3. Google Chrome POSTMAN

About Author

author image
Rambabu Posa have 12+ years of RICH experience as Sr Agile Lead Java/Scala/BigData/NoSQL Developer. Apart from Java and Java EE, he is good at Spring, Hibernate, RESTful WebServices, NoSQL, BigData Hadoop Stack, Cloud, Scala, Groovy, Play Framework, Akka, TDD, BDD,Agile and much more. He likes sharing his knowledge through writing tutorials.

Comments

Subscribe
Notify of
17 Comments
Most Voted
Newest Oldest
Inline Feedbacks
View all comments
Mitch
6 years ago

But how would someone concatenate filter parameters?

For example sending a GET request where it must match 2 or more fields? So far all I see is the ability to match a single parameter.

IE: http://localhost//elasticsearch/posts/post/_search?q=country:Canada

But you cant do:
http://localhost//elasticsearch/posts/post/_search?q=country:Canada&city:vancouver

Enes Aç?ko?lu
6 years ago

Thanks for quick introduction.

viveke
6 years ago

Hi, the tutorial is good. I would like to take advantage to connect database directly in Android.. It is possible ?
What are all the library need be included

Mangani
6 years ago

for( ; ; ){
console.log(“Thanks mkyong!”);
}

Jickson P
6 years ago

Nice tutorial.

Richard Luo
6 years ago

Nice tutorial. Thanks for all the work.

Phong
5 years ago

Thanks you very much.

Rocky
6 years ago

Thanks for it!

mukesh kaviyath
3 months ago

Hi Rambabu, I dont get the “started” output. I am using Windows 10.

[2023-12-08T16:28:10,665][INFO ][o.e.l.ClusterStateLicenseService] [CSEGOTLD147275L] license [9f0aa7da-ae24-4b72-8bfd-491201a79c42] mode [basic] – valid
[2023-12-08T16:28:10,666][INFO ][o.e.x.s.a.Realms ] [CSEGOTLD147275L] license mode is [basic], currently licensed security realms are [reserved/reserved,file/default_file,native/default_native]
[2023-12-08T16:28:10,686][INFO ][o.e.g.GatewayService ] [CSEGOTLD147275L] recovered [1] indices into cluster_state
[2023-12-08T16:28:11,096][INFO ][o.e.i.m.MapperService ] [CSEGOTLD147275L] [.security-7] reloading search analyzers
[2023-12-08T16:28:11,489][INFO ][o.e.h.n.s.HealthNodeTaskExecutor] [CSEGOTLD147275L] Node [{CSEGOTLD147275L}{YbIOC1DNTpi7d09xjxtN-Q}] is selected as the current health node.
[2023-12-08T16:28:11,565][INFO ][o.e.c.r.a.AllocationService] [CSEGOTLD147275L] current.health=”GREEN” message=”Cluster health status changed from [RED] to [GREEN] (reason: [shards started [[.security-7][0]]]).” previous.health=”RED” reason=”shards started [[.security-7][0]]”

Could you please see the logs and let me know.

Ajay dev
1 year ago

Great..!!! point to point explanations sir,

triveni
3 years ago

Thanks.

rajeev
4 years ago

“http://127.0.0.1:9200/traininglocations/_search?pretty=true&q=distcode:16 AND trgtype:1” is this a correct URI for elasticsearch?

Ganesan Sundareswaran
4 years ago

Can we pass types as 2 values like https://server/index/vehicle/car. For this URL is coming as https://server/index/vehicle%2Fcar and it leads to 404.

thilaga
5 years ago

Nice tutorial

pavan
5 years ago

Nice tutorials…it helps a lot to me.

Rahul
5 years ago

Thanks, it was really helpful.

Roland
6 years ago

Remember that there is X-Pack which includes authentication (according to their website, I did not try it yet).