The native APIs for managing document (index, delete, and update) are the most important after the search ones. In this recipe, we will see how to use them. In the next one we will evolve in executing bulk actions to improve performances.
You need a working ElasticSearch cluster and a working copy of Maven.
The code of this recipe is in chapter_10/nativeclient in the code bundle of this book available on Packt's website, and the referred class is DocumentOperations.
For managing documents, we will perform the steps given as follows:
- We'll execute all the document with CRUD operations (CReate, Update, Delete) via native client:
import org.elasticsearch.action.delete.DeleteResponse; import org.elasticsearch.action.get.GetResponse; import org.elasticsearch.action.index.IndexResponse; import org.elasticsearch.action.update.UpdateResponse; import org.elasticsearch.client.Client; import org.elasticsearch.common.xcontent.XContentFactory; import java.io.IOException; public class DocumentOperations { public static void main( String[] args ) { String index="mytest"; String type="mytype"; Client client =NativeClient.createTransportClient(); IndicesOperations io=new IndicesOperations(client); if(io.checkIndexExists(index)) io.deleteIndex(index); try { client.admin().indices().prepareCreate(index) .addMapping(type, XContentFactory.jsonBuilder() .startObject() .startObject(type) .startObject("_timestamp").field("enabled", true).field("store", "yes").endObject() .startObject("_ttl").field("enabled", true).field("store", "yes").endObject() .endObject() .endObject()) .execute().actionGet(); } catch (IOException e) { System.out.println("Unable to create mapping"); } // We index a document IndexResponse ir=client.prepareIndex("test", "type", "2").setSource("text", "value").execute().actionGet(); System.out.println("Version: "+ir.getVersion()); // We get a document GetResponse gr=client.prepareGet("test", "type", "2").execute().actionGet(); System.out.println("Version: "+gr.getVersion()); // We update a document UpdateResponse ur = client.prepareUpdate("test", "type", "2").setScript("ctx._source.text = 'v2'").execute().actionGet(); System.out.println("Version: "+ur.getVersion()); // We delete a document DeleteResponse dr = client.prepareDelete("test", "type", "2").execute().actionGet(); io.deleteIndex("test"); } } - The result will be:
Sep 24, 2013 10:58:20 PM org.elasticsearch.plugins INFO: [Masked Rose] loaded [], sites [] Version: 1 Version: 1 Version: 2
The document version, after an update action and if the document is re-indexed with new changes, is always incremented by one.
Before executing every document action, a client must be available and the index and document mapping must be created (the mapping is optional).
To index a document via native client, the method prepareIndex is created. It requires the index and the type as arguments. If an ID is provided, it will be used; otherwise a new one will be created. In the previous example, we have put the source in the form of a key value, but many forms are available to pass as source. They are:
- A JSON string:
"{"field": "value"}" - A string and a value (from one to four couples):
field1,value1,field2,value2,field3,value3,field4, andvalue4 - A builder:
jsonBuilder().startObject().field(field,value).endObject() - A byte arrays
Obviously it's possible to add all the parameters that we saw in the Indexing a document recipe in Chapter 4, Standard Operations, such as parent, and routing. In the previous example, the call was:
IndexResponse ir=client.prepareIndex("test", "type", "2").setSource("text", "value").execute().actionGet();The return value (IndexReponse) can be used in several ways:
- Checking if the index was successful
- Getting the ID of the indexed document, if it was not provided during index action
- Retrieving the document version
To retrieve a document, knowing the index/type/ID, the client method is prepareGet. It requires the usual triple (index, type, and ID), but a lot of other methods are available to control the routing (such as souring and parent) or fields as we have seen in the Getting a document in Chapter 4, Standard Operations. In the previous example, the call is:
GetResponse gr=client.prepareGet("test", "type", "2").execute().actionGet();The return type (GetResponse) contains all the requests (if the document exists) and document information (source, version, index, type, and ID).
To update a document, it's required to know the index/type/ID and provide a script or a document to be used for the update. The client method is prepareUpdate. In the previous example, there is:
UpdateResponse ur = client.prepareUpdate("test", "type", "2").setScript("ctx._source.text = 'v2'" ).execute().actionGet();The script code must be a string. If the script language is not defined, the default ("MVEL") is used. The returned response contains information about the execution and the new version value to manage concurrency.
To delete a document (without the need to execute a query), we must know the index/type/ID triple and we can use the client method prepareDelete to create or delete request. In the previous code, we used:
DeleteResponse dr = client.prepareDelete("test", "type", "2").execute().actionGet();The delete request allows passing to it all the parameters we saw in the Deleting a document recipe in Chapter 4, Standard Operations, to control routing and version.