Index APIedit

The index API allows one to index a typed JSON document into a specific index and make it searchable.

Generate JSON documentedit

There are different way of generating JSON document:

  • Manually (aka do it yourself) using native byte[] or as a String
  • Using Map that will be automatically converted to its JSON equivalent
  • Using a third party library to serialize your beans such as Jackson
  • Using built-in helpers XContentFactory.jsonBuilder()

Internally, each type is converted to byte[] (so a String is converted to a byte[]). Therefore, if the object is in this form already, then use it. The jsonBuilder is highly optimized JSON generator that directly constructs a byte[].

Do It Yourselfedit

Nothing really difficult here but note that you will have to encode dates regarding to the Date Format.

String json = "{" +
        "\"user\":\"kimchy\"," +
        "\"postDate\":\"2013-01-30\"," +
        "\"message\":\"trying out Elasticsearch\"" +
    "}";

Using Mapedit

Map is a key:values pair collection. It represents very well a JSON structure:

Map<String, Object> json = new HashMap<String, Object>();
json.put("user","kimchy");
json.put("postDate",new Date());
json.put("message","trying out Elasticsearch");

Serialize your beansedit

Elasticsearch already use Jackson but shade it under org.elasticsearch.common.jackson package. So, you can add your own Jackson version in your pom.xml file or in your classpath. See Jackson Download Page.

For example:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.1.3</version>
</dependency>

Then, you can start serializing your beans to JSON:

import com.fasterxml.jackson.databind.*;

// instance a json mapper
ObjectMapper mapper = new ObjectMapper(); // create once, reuse

// generate json
String json = mapper.writeValueAsString(yourbeaninstance);

Use Elasticsearch helpersedit

Elasticsearch provides built-in helpers to generate JSON content.

import static org.elasticsearch.common.xcontent.XContentFactory.*;

XContentBuilder builder = jsonBuilder()
    .startObject()
        .field("user", "kimchy")
        .field("postDate", new Date())
        .field("message", "trying out Elasticsearch")
    .endObject()

Note that you can also add arrays with startArray(String) and endArray() methods. By the way, field method accept many object types. You can pass directly numbers, dates and even other XContentBuilder objects.

If you need to see the generated JSON content, you can use the string() method.

String json = builder.string();

Index documentedit

The following example indexes a JSON document into an index called twitter, under a type called tweet, with id valued 1:

import static org.elasticsearch.common.xcontent.XContentFactory.*;

IndexResponse response = client.prepareIndex("twitter", "tweet", "1")
        .setSource(jsonBuilder()
                    .startObject()
                        .field("user", "kimchy")
                        .field("postDate", new Date())
                        .field("message", "trying out Elasticsearch")
                    .endObject()
                  )
        .execute()
        .actionGet();

Note that you can also index your documents as JSON String and that you don’t have to give an ID:

String json = "{" +
        "\"user\":\"kimchy\"," +
        "\"postDate\":\"2013-01-30\"," +
        "\"message\":\"trying out Elasticsearch\"" +
    "}";

IndexResponse response = client.prepareIndex("twitter", "tweet")
        .setSource(json)
        .execute()
        .actionGet();

IndexResponse object will give you report:

// Index name
String _index = response.index();
// Type name
String _type = response.type();
// Document ID (generated or not)
String _id = response.id();
// Version (if it's the first time you index this document, you will get: 1)
long _version = response.version();

If you use percolation while indexing, IndexResponse object will give you percolator that have matched:

IndexResponse response = client.prepareIndex("twitter", "tweet", "1")
        .setSource(json)
        .execute()
        .actionGet();

List<String> matches = response.matches();

For more information on the index operation, check out the REST index docs.

Operation Threadingedit

The index API allows to set the threading model the operation will be performed when the actual execution of the API is performed on the same node (the API is executed on a shard that is allocated on the same server).

The options are to execute the operation on a different thread, or to execute it on the calling thread (note that the API is still async). By default, operationThreaded is set to true which means the operation is executed on a different thread.