Elasticsearch Document APIs provide single document APIs and multi-document APIs, where the API call is targeting a single document and multiple documents respectively.
Index Of Elasticsearch Document APIs
It helps to add or update the JSON document in an index when a request is made to that respective index with specific mapping. For example, the following request will add the JSON object to index schools and under school mapping −
PUT schools/_doc/5
{
name":"City School", "description":"ICSE", "street":"West End",
"city":"Meerut",
"state":"UP", "zip":"250002", "location":[28.9926174, 77.692485],
"fees":3500,
"tags":["fully computerized"], "rating":"4.5"
}
On running the above code, we get the following result −
{
"_index" : "schools",
"_type" : "_doc",
"_id" : "5",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 2,
"_primary_term" : 1
}
Automatic Index Creation
When a request is made to add a JSON object to a particular index and if that index does not exist, then this API automatically creates that index and also the underlying mapping for that particular JSON object. This functionality can be disabled by changing the values of the following parameters to false, which are present in the elasticsearch.yml file.
action.auto_create_index:false index.mapper.dynamic:false
You can also restrict the auto-creation of the index, where only index names with specific patterns are allowed by changing the value of the following parameter −
action.auto_create_index:+acc*,-bank*
Note − Here + indicates allowed and – indicates not allowed.
Versioning
Elasticsearch also provides a version control facility. We can use a version query parameter to specify the version of a particular document.
PUT schools/_doc/5?version=7&version_type=external
{
"name":"Central School", "description":"CBSE Affiliation", "street":"Nagan",
"city":"paprola", "state":"HP", "zip":"176115", "location":[31.8955385, 76.8380405],
"fees":2200, "tags":["Senior Secondary", "beautiful campus"], "rating":"3.3"
}
On running the above code, we get the following result −
{
"_index" : "schools",
"_type" : "_doc",
"_id" : "5",
"_version" : 7,
"result" : "updated",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 3,
"_primary_term" : 1
}
Versioning is a real-time process and it is not affected by the real-time search operations.
There are two most important types of versioning −
Internal Versioning
Internal versioning is the default version that starts with 1 and increments with each update, deletes included.
External Versioning
It is used when the versioning of the documents is stored in an external system like third-party versioning systems. To enable this functionality, we need to set version_type to external. Here Elasticsearch will store version numbers as designated by the external system and will not increment them automatically.
Operation Type
The operation type is used to force a create operation. This helps to avoid the overwriting of an existing document.
PUT chapter/_doc/1?op_type=create
{
"Text":"this is chapter one"
}
On running the above code, we get the following result −
{
"_index" : "chapter",
"_type" : "_doc",
"_id" : "1",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 0,
"_primary_term" : 1
}
Automatic ID generation
When ID is not specified in index operation, then Elasticsearch automatically generates id for that document.
POST chapter/_doc/
{
"user" : "tpoint",
"post_date" : "2018-12-25T14:12:12",
"message" : "Elasticsearch Tutorial"
}
On running the above code, we get the following result −
{
"_index" : "chapter",
"_type" : "_doc",
"_id" : "PVghWGoB7LiDTeV6LSGu",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 1,
"_primary_term" : 1
}
Get API
API helps to extract type JSON objects by performing a get request for a particular document.
pre class="prettyprint notranslate" > GET schools/_doc/5
On running the above code, we get the following result −
{
"_index" : "schools",
"_type" : "_doc",
"_id" : "5",
"_version" : 7,
"_seq_no" : 3,
"_primary_term" : 1,
"found" : true,
"_source" : {
"name" : "Central School",
"description" : "CBSE Affiliation",
"street" : "Nagan",
"city" : "paprola",
"state" : "HP",
"zip" : "176115",
"location" : [
31.8955385,
76.8380405
],
"fees" : 2200,
"tags" : [
"Senior Secondary",
"beautiful campus"
],
"rating" : "3.3"
}
}
- This operation is real time and does not get affected by the refresh rate of Index.
- You can also specify the version, then Elasticsearch will fetch that version of document only.
- You can also specify the _all in the request, so that the Elasticsearch can search for that document id in every type and it will return the first matched document.
- You can also specify the fields you want in your result from that particular document.
GET schools/_doc/5?_source_includes=name,fees
On running the above code, we get the following result −
{
"_index" : "schools",
"_type" : "_doc",
"_id" : "5",
"_version" : 7,
"_seq_no" : 3,
"_primary_term" : 1,
"found" : true,
"_source" : {
"fees" : 2200,
"name" : "Central School"
}
}
You can also fetch the source part in your result by just adding _source part in your get request.
GET schools/_doc/5?_source
On running the above code, we get the following result −
{
"_index" : "schools",
"_type" : "_doc",
"_id" : "5",
"_version" : 7,
"_seq_no" : 3,
"_primary_term" : 1,
"found" : true,
"_source" : {
"name" : "Central School",
"description" : "CBSE Affiliation",
"street" : "Nagan",
"city" : "paprola",
"state" : "HP",
"zip" : "176115",
"location" : [
31.8955385,
76.8380405
],
"fees" : 2200,
"tags" : [
"Senior Secondary",
"beautiful campus"
],
"rating" : "3.3"
}
}
You can also refresh the shard before doing get operation by setting the refresh parameter to true.
Delete API
You can delete a particular index, mapping, or document by sending an HTTP DELETE request to Elasticsearch.
DELETE schools/_doc/4
On running the above code, we get the following result −
{
"found":true, "_index":"schools", "_type":"school", "_id":"4", "_version":2,
"_shards":{"total":2, "successful":1, "failed":0}
}
The version of the document can be specified to delete that particular version. Routing parameters can be specified to delete the document from a particular user and the operation fails if the document does not belong to that particular user. In this operation, you can specify refresh and timeout options same as GET API.
Update API
The script is used for performing this operation and versioning is used to make sure that no updates have happened during the get and re-index. For example, you can update the fees of school using script −
POST schools/_update/4
{
"script" : {
"source": "ctx._source.name = params.sname",
"lang": "painless",
"params" : {
"sname" : "City Wise School"
}
}
}
On running the above code, we get the following result −
{
"_index" : "schools",
"_type" : "_doc",
"_id" : "4",
"_version" : 3,
"result" : "updated",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 4,
"_primary_term" : 2
}
You can check the update by sending get request to the updated document.
Next Topic – Click Here
Pingback: Elasticsearch - API Conventions - Adglob Infosystem Pvt Ltd