Elasticsearch Document APIs

As we already discussed in our early tutorial that Elasticsearch is a document-oriented database, which stores all data in document form. API uses JSON document format to store data. Document APIs are those APIs that perform the operation at the document level. So, if in case you want to perform some operation at document level, you have to make use of the document appear. With the help of document API, you can do that very well.

In Elasticsearch, Document API is classified into two categories that are single document API and multi-document API. We will discuss each API in detail with examples –

1. Single Document API

These APIs are useful if you want to perform operations on a single document instead of a group of documents. So, you can use these single document API when you want to perform operations on a single document. Single Document APIs is further classified into four APIs, which are listed below:

Index API
Get API
Update API
Delete API

Firstly, create an index to use all these API. Use the following command –

Copy Code

Here PUT is the request method and student is index name.

Response

Index API

This API helps to Add a document in a specified index when a request is made.
It also allows us to update the document if the document already exists.
Index API is used for the full replacement of an existing document.
Index API allows us to add and update the document.
We have to use the POST method to add the data where we need to specify the document id.

Example

Use the following code to add data in the index –

Copy Code

  POST student/_doc/02/  {  “name “: “Stan Lee”,  “gender”: “Male”,  “phone”: “9876543211”,  “street”: ” New Rochelle”,   “city”: “New York”,   “country”: “United States”,   “zip”: “10029”  }  

Here POST is request method and _doc is used for document type to add data in the index.

Response

The data provided in request body is successfully added if you get the following output in response body.

  {   “index”: “student”,  “type”: “_doc”,  “id”: “02”,  “version”: 1,  “result”: “created”,  “_shards”: {  “total”:2,  “successful”:1,  “failed”: 0  }  “_seq_no”: 0,  “_primary_term”: 1  }  

Look at the screenshot below in browser –

Get API

Get API helps to retrieve or read the data stored in an index.
This API is responsible for retrieving the specified JSON document from an index.

Example

In this example, we will use GET API to read a document. Create a new request and specify the index name and document id. It will fetch and display the result in response body.

Index name = student
Document id = 02

Copy Code

Select GET method and append the remaining code in the request string.

Response

The below output will show in response body for the above request –

  {   “index”: “student”,  “type”: “_doc”,  “id”: “02”,  “version”: 1,  “_seq_no”: 0,  “_primary_term”: 1,  “found”: true,  “_source”: {  “name “: “Stan Lee”,  “gender”: “Male”,  “phone”: “9876543211”,  “street”: “New Rochelle”,   “city”: “New York”,   “country”: “United States”,   “zip”: “10029”  }  }  

Look at the screenshot below how it will display on browser –

Update API

The Update API helps to update an existing document, which uses script and versioning. It allows passing a partial document that merges to the existing document. The _update is used while making a request.

Script keyword is used to create query request for performing this operation. It can modify, update, or delete the document. You can also use doc in place of script keyword to update the document.
Versioning is used to ensure that no update has occurred during the get and reindex.
Remember that it would update the single document only, not all.
It accepts to two parameters index name and document id, i.e., <index> and <id>.

Example

Elasticsearch provides _update API and POST request method to update the documents. In this example, we will replace the zip from 10029 to 94003.

Method: POST
API: _update
Index Name: student
Type: _doc
Data for update: zip code

Execute the following query and update the document.

Copy Code

Response

If you get the same output, the document is updated successfully.

  {   “index”: “student”,  “type”: “_doc”,  “id”: “02”,  “version”: 2,  “result”: “updated”,  “shards”: {  “total”: 2,  “successful”: 1,  “failed”: 0  }  “_seq_no”: 1,  “_primary_term”: 1  }  

See the below screenshot how it will look on the browser –

Delete API

You can use this API to delete a particular index, document, or mapping.
Send an HTTP DELETE request to Elasticsearch for executing delete operation.
It does not require a large statement to create a delete query.
Use the _delete API and specify the index name to delete.

Example

We will use DELETE API to delete a document stored in an index. So, just set the DELETE the request method and provide index name and document id, which you want to delete.

Copy Code

Response

If you get the below output, document 02 is deleted successfully.

  {   “index”: “student”,  “type”: “_doc”,  “id”: “02”,  “version”: 3,  “result”: “deleted”,  “shards”: {  “total”: 2,  “successful”: 1,  “failed”: 0  }  “_seq_no”: 2,  “_primary_term”: 1  }  

Look at the below screenshot to see the result on browser –

2. Multi-Document API

Unlike a single document API, you can use the multi-document APIs for querying across multiple documents. For example – delete or update data in bulk, and reindex, etc. Multi-document APIs is further classified into five APIs, which are listed below:

Multi Get API
Bulk API
Delete By Query API
Update By Query API
Reindex API

Multi Get API

It retrieves multiple documents using _docs array of index.
It offers the same functionality, similar to the Single Get API. The only difference is that this API returns more than one document.
To extract documents, we use the doc array for specifying the index, type, and id of all those documents.
We need to use POST API to retrieve multiple documents from an index. It is not enough; we also need to append _mget in request string and define document id query space to fetch multiple records.

Remember that more than three or four records must be added in an index (database) to perform this operation. See the example below –

Copy Code

  POST student/_mget/  {    “docs”: [     {           “_index”: “student”, “_type”: “_doc”, “_id”: “01”     },     {           “_index”: “student”, “_type”: “_doc”, “_id”: “03”     }    ]  }  

Here, we are getting the document for id 01 and 03.

Response

You will get the output like the below response.

  “docs”: [  {   “index”: “student”,  “type”: “_doc”,  “id”: “01”,  “version”: 1,  “_seq_no”: 0,  “_primary_term”: 1,  “found”: true,        “source”: {   “name”: “Alen Paul”,   “gender”: “Male”,   “phone”: “9876543210”,    “street”: “Malen Park”,   “city”: “California”,   “country”: “United State”,   “zip”: “94025”,                    }  }  “index”: “student”,  “type”: “_doc”,  “id”: “03”,  “version”: 1,  “_seq_no”: 3,  “_primary_term”: 1,  “found”: true,        “source”: {   “name”: “Stan Lee”,   “gender”: “Male”,   “phone”: “9876543211”,    “street”: “New Rochelle”,   “city”: “New York”,   “country”: “United State”,   “zip”: “10029”,                    }  }        ]  }  

Look at the below screenshot to see the result on browser –

BulkAPI

Bulk API helps to upload or delete the JSON object in bulk. To do this, make multiple index/delete operations in a single request. Bulk API is similar to the Get API and provides all other functionality same as it.

Add the “_bulk” keyword to call this API.
It is used to perform delete/update/index operations in bulk.

Below are some examples of bulk commands:

  { “delete”: { “_index” : “student”, “_type”: “_docs”, “_id”: “02”} }  { “update”: { “_index” : “student”, “_type”: “_docs”, “_id”: “04”} } {“doc”: {“field3”: “value3”} }   

Delete By Query API

The _delete_by_query request is used to delete all matching documents.
When this request processes, Elasticsearch (ES) perform multiple searches to find all the document to delete.

Example

Execute the following query and update the index. This will delete all those documents that have city = New York.

Copy Code

  POST student/_doc/  _delete_by_query  {    “query”: {      “match”: {          “city”: “New York”      }    }  }  

Response

If you get the same output, the document is deleted successfully.

  {   “took”: 9376,  “timed_out”: false,  “total”: 3,  “deleted”: 3,  “batches”: 1,  “version_conflicts”: 0,  “noops”: 0,  “retries”: {  “bulk”: 0,  “search”: 0  },  “throttled_millis”: 0,  “request_per_second”: -1,  “throttled_until_millis”: 0,  “faliures”: [ ]  }  

See the below screenshot for better understand how request and response will look on the browser –

In case if we use “script”: {} in place of field_name: value (i.e., “city”: “New York”), it will delete all the document present in student index. The request query will be like –

  {    “query”: {      “match”: {          “match_all”: {}      }    }  }  

Update By Query API

Update By Query API (_update_by_query) performs an update on each document present in the index without changing the source.
The script keyword is used to create a query request for performing this operation.

Example

In this example, we will update the zip code to 29001 in all documents where city is New York.

Method: POST
API: _update_by_query
Index Name: student
Type: _doc
Data for update: zip code

Execute the following query and update the documents.

Copy Code

  POST student/_doc/  _update_by_query  {  “script”: {      “inline”: “ctx._source.zip=29001”,      “lang”: “painless”    },    “query”: {      “match”: {          “city”: “New York”      }    }  }  

Response

If you get the same output, the document is updated successfully.

  {   “took”: 346,  “timed_out”: false,  “total”: 3,  “updated”: 3,  “deleted”: 0,  “batches”: 1,  “version_conflicts”: 0,  “noops”: 0,  “retries”: {  “bulk”: 0,  “search”: 0  },  “throttled_millis”: 0,  “request_per_second”: -1,  “throttled_until_millis”: 0,  “faliures”: [ ]  }  

The response will be same as the below screenshot –

Here, you can see that three records have been updated, which matched with the given condition.

Reindex API

This API is basically used when we need a document in another index. We copy the document data from one index to another using _reindex API. With the help of this API, we can easily to copy a document from an index and create a duplicate copy of it to another index. Below are some important points about reindex API:

Reindex API extracts the document from the source index and indexes that document to the destination index.
_source must be enabled for all documents present in the source index.
Before calling _reindex, you must set up the destination index first.

Example

Execute the following query to reindex the document from one index to another.
Method: POST
API: _reindex
Index Name: student
New index: new_student

Copy Code

  POST   _reindex  {  “source”: {      “index”: “student”    },    “dest”: {          “index”: “new_student”    }  }  

Response

If you get the same output, the document is copied successfully.

  {   “took”: 1748,  “timed_out”: false,  “total”: 2,  “updated”: 0,  “created”: 2,  “deleted”: 0,  “batches”: 1,  “version_conflicts”: 0,  “noops”: 0,  “retries”: {  “bulk”: 0,  “search”: 0  },  “throttled_millis”: 0,  “request_per_second”: -1,  “throttled_until_millis”: 0,  “faliures”: [ ]  }  

See the below screenshot, how it will look on the browser.

So, using the search API, you can see all the documents copied to a new index, i.e., new_student.

Next TopicElasticsearch Search APIs

Elasticsearch Document APIs

Elasticsearch Document APIs

1. Single Document API

Index API

Get API

Update API

Delete API

2. Multi-Document API

Multi Get API

BulkAPI

Delete By Query API

Update By Query API

Reindex API

Advanced Data Structure MCQ (Multiple Choice Questions)

Circular reference in Excel

You may also like