202 lines
6.0 KiB
Plaintext
202 lines
6.0 KiB
Plaintext
[[index_]]
|
|
== Index API
|
|
|
|
The index API allows one to index a typed JSON document into a specific
|
|
index and make it searchable.
|
|
|
|
|
|
=== Generate JSON document
|
|
|
|
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
|
|
http://wiki.fasterxml.com/JacksonHome[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 Yourself
|
|
|
|
Nothing really difficult here but note that you will have to encode
|
|
dates regarding to the
|
|
link:{ref}/mapping-date-format.html[Date Format].
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
String json = "{" +
|
|
"\"user\":\"kimchy\"," +
|
|
"\"postDate\":\"2013-01-30\"," +
|
|
"\"message\":\"trying out Elastic Search\"," +
|
|
"}";
|
|
--------------------------------------------------
|
|
|
|
|
|
==== Using Map
|
|
|
|
Map is a key:values pair collection. It represents very well 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 Elastic Search");
|
|
--------------------------------------------------
|
|
|
|
|
|
==== Serialize your beans
|
|
|
|
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 http://wiki.fasterxml.com/JacksonDownload[Jackson
|
|
Download Page].
|
|
|
|
For example:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
<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:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
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 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 Elastic Search")
|
|
.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.
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
String json = builder.string();
|
|
--------------------------------------------------
|
|
|
|
|
|
=== Index document
|
|
|
|
The following example indexes a JSON document into an index called
|
|
twitter, under a type called tweet, with id valued 1:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
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 Elastic Search")
|
|
.endObject()
|
|
)
|
|
.execute()
|
|
.actionGet();
|
|
--------------------------------------------------
|
|
|
|
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 Elastic Search\"," +
|
|
"}";
|
|
|
|
IndexResponse response = client.prepareIndex("twitter", "tweet")
|
|
.setSource(json)
|
|
.execute()
|
|
.actionGet();
|
|
--------------------------------------------------
|
|
|
|
`IndexResponse` object will give you report:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
// 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:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
IndexResponse response = client.prepareIndex("twitter", "tweet", "1")
|
|
.setSource(json)
|
|
.setPercolate("*")
|
|
.execute()
|
|
.actionGet();
|
|
|
|
List<String> matches = response.matches();
|
|
--------------------------------------------------
|
|
|
|
For more information on the index operation, check out the REST
|
|
link:{ref}/docs-index_.html[index] docs.
|
|
|
|
|
|
=== Operation Threading
|
|
|
|
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.
|