Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Branch: master
Fetching contributors…
Cannot retrieve contributors at this time
358 lines (250 sloc) 9.37 KB


Jest is a Java HTTP Rest client for ElasticSearch.

ElasticSearch is an Open Source (Apache 2), Distributed, RESTful, Search Engine built on top of Apache Lucene.

ElasticSearch already has a Java API which is also used by ElasticSearch internally, but Jest fills a gap, it is the missing client for ElasticSearch Http Rest interface.


Jest maven repository is hosted on Sonatype.

Add Sonatype repository definition to your root pom.xml

   <name>Sonatype Groups</name>

Add Jest as a dependency to your project.


Continuous Integration

build status


Jest has a sample application can be found here.

To start using Jest first we need a JestClient;

 // Configuration
 ClientConfig clientConfig = new ClientConfig();
 LinkedHashSet<String> servers = new LinkedHashSet<String>();

 // Construct a new Jest client according to configuration via factory
 JestClientFactory factory = new JestClientFactory();
 JestClient client = factory.getObject();

Creating an Index

You can create an index via Jest with ease;

client.execute(new CreateIndex("articles"));

Index setting can be passed as a JSON file or ElasticSearch Settings;

via JSON;

String settings = "\"settings\" : {\n" +
                "        \"number_of_shards\" : 5,\n" +
                "        \"number_of_replicas\" : 1\n" +
                "    }\n";

client.execute(new CreateIndex("articles"), settings)                        

via SetingsBuilder;

import org.elasticsearch.common.settings.ImmutableSettings;

ImmutableSettings.Builder settingsBuilder = ImmutableSettings.settingsBuilder();

client.execute(new CreateIndex("articles"),;

Indexing Documents

ElasticSearch requires index data as JSON. There are several ways to create documents to index via Jest. From now on, we will refer documents as source. Source objects can be String, Map or POJOs.

as JSON String;

String source = "{\"user\":\"kimchy\"}";

or creating JSON via ElasticSearch JSONBuilder;

String source = jsonBuilder()
.field("user", "kimchy")
.field("postDate", "date")
.field("message", "trying out Elastic Search")

as Map;

Map<String, String> source = new LinkedHashMap<String,String>()
source.put("user", "kimchy");

as POJO;

Article source = new Article();
source.setAuthor("John Ronald Reuel Tolkien");
source.setContent("The Lord of the Rings is an epic high fantasy novel");

An example of indexing given source to twitter index with type tweet;

Index index = new Index.Builder(source).index("twitter").type("tweet").build();

Index id can be typed explicitly;

Index index = new Index.Builder(source).index("twitter").type("tweet").id("1").build();

@JestId annotation can be used to mark a property of a bean as id;

class Article {

private Long documentId;


Now whenever an instance of Article is indexed, index id will be value of documentId.

Searching Documents

Search queries can be either JSON String or ElasticSearch QueryBuilder object. Jest works with default ElasticSearch queries, it simply keeps things as is.


String query = "{\n" +
            "    \"query\": {\n" +
            "        \"filtered\" : {\n" +
            "            \"query\" : {\n" +
            "                \"query_string\" : {\n" +
            "                    \"query\" : \"test\"\n" +
            "                }\n" +
            "            },\n" +
            "            \"filter\" : {\n" +
            "                \"term\" : { \"user\" : \"kimchy\" }\n" +
            "            }\n" +
            "        }\n" +
            "    }\n" +

Search search = new Search(query);
// multiple index or types can be added.

JestResult result = client.execute(search);                       

By using QueryBuilder;

QueryBuilder queryBuilder = QueryBuilders.queryString("kimchy"); 

Search search = new Search(queryBuilder);

JestResult result = client.execute(search);

Result can be cast to List of domain object;

JestResult result = client.execute(search);
List<Article> articles = result.getSourceAsObjectList(Article.class);

Please refer ElasticSearch Query DSL documentation to work with complex queries.

Getting Documents

Get get = new Get.Builder("1").index("twitter").type("tweet").build();

JestResult result = client.execute(get);

Result can be cast to domain object;

Get get = new Get.Builder("1").index("twitter").type("tweet").build();

JestResult result = client.execute(get);

Article article = result.getSourceAsObject(Article.class);

Updating Documents

String script = "{\n" +
                "    \"script\" : \"ctx._source.tags += tag\",\n" +
                "    \"params\" : {\n" +
                "        \"tag\" : \"blue\"\n" +
                "    }\n" +

client.execute(new Update.Builder(script).index("twitter").type("tweet").id("1").build());

Deleting Documents

client.execute(new Delete.Builder("1").index("twitter").type("tweet").build());

Bulk Operations

ElasticSearch's bulk API makes it possible to perform many index/delete operations in a single API call. This can greatly increase the indexing speed.

Bulk bulk = new Bulk("twitter", "tweet");
bulk.addIndex(new Index.Builder(article1).build());
bulk.addIndex(new Index.Builder(article2).build());

bulk.addDelete(new Delete.Builder("1").build());


Action Parameters

ElasticSearch offers request parameters to set properties like routing, versioning, operation type etc.

For instance you can set "refresh" property to "true" while indexing a document as below;

Index index = new Index.Builder("{\"user\":\"kimchy\"}").index("cvbank").type("candidate").id("1").build();
index.addParameter(Parameters.REFRESH, true);

Further Reading

Integration Tests are best place to see things in action.

Experimental Features

Jest has a HttpClient object which implements ElasticSearch Client interface. It provides a bridge between ElasticSearch Java API and Jest. Simply you can use ElasticSearch Java API over ElasticSearch HTTP Rest API.

Below sample uses Java API but it works over HTTP;

JestHttpClient jestClient = (JestHttpClient) new JestClientFactory().getObject();

Client client = new HttpClient(jestClient);

CountResponse response = client.prepareCount()
  .setQuery(textQuery("message", "JEST"))

Here is the search sample;

JestHttpClient jestClient = (JestHttpClient) new JestClientFactory().getObject();
Client client = new HttpClient(jestClient);

SearchResponse response = client.prepareSearch("articles")
     .setQuery(textQuery("message", "JEST"))

These features are experimental and it is not advised to use them at live.


Jest is using slf4j for logging and expects you to plug in your own implementation, so log4j dependency is in "provided" scope.

For instance to use log4j implementation, add below dependency to your pom.xml


Please read slf4j manual here.


Jest is developed by @dogukansonmez and team.

Copyright and License

Copyright 2012

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Jump to Line
Something went wrong with that request. Please try again.