[[java-docs-index]]
=== Index API

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


[[java-docs-index-generate]]
==== Generate JSON document

There are several different ways of generating a JSON document:

* Manually (aka do it yourself) using native `byte[]` or as a `String`

* Using a `Map` that will be automatically converted to its JSON
equivalent

* Using a third party library to serialize your beans such as
https://github.com/FasterXML/jackson[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[]`.


[[java-docs-index-generate-diy]]
===== Do It Yourself

Nothing really difficult here but note that you will have to encode
dates according to the
{ref}/mapping-date-format.html[Date Format].

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


[[java-docs-index-generate-using-map]]
===== Using Map

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

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


[[java-docs-index-generate-beans]]
===== Serialize your beans

You can use https://github.com/FasterXML/jackson[Jackson] to serialize
your beans to JSON. Please add http://search.maven.org/#search%7Cga%7C1%7Cjackson-databind[Jackson Databind]
 to your project. Then you can use `ObjectMapper` to serialize your beans:

[source,java]
--------------------------------------------------
import com.fasterxml.jackson.databind.*;

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

// generate json
byte[] json = mapper.writeValueAsBytes(yourbeaninstance);
--------------------------------------------------


[[java-docs-index-generate-helpers]]
===== Use Elasticsearch helpers

Elasticsearch provides built-in helpers to generate JSON content.

[source,java]
--------------------------------------------------
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, the `field` method +
 accepts many object types. You can directly pass numbers, dates and even
other XContentBuilder objects.

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

[source,java]
--------------------------------------------------
import org.elasticsearch.common.Strings;

String json = Strings.toString(builder);
--------------------------------------------------


[[java-docs-index-doc]]
==== Index document

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

[source,java]
--------------------------------------------------
import static org.elasticsearch.common.xcontent.XContentFactory.*;

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

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

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

IndexResponse response = client.prepareIndex("twitter", "_doc")
        .setSource(json, XContentType.JSON)
        .get();
--------------------------------------------------

`IndexResponse` object will give you a report:

[source,java]
--------------------------------------------------
// Index name
String _index = response.getIndex();
// Type name
String _type = response.getType();
// Document ID (generated or not)
String _id = response.getId();
// Version (if it's the first time you index this document, you will get: 1)
long _version = response.getVersion();
// status has stored current instance statement.
RestStatus status = response.status();
--------------------------------------------------

For more information on the index operation, check out the REST
{ref}/docs-index_.html[index] docs.

