A new document can be added using the Document API's. For the e-commerce example, to add a new product, we execute the following command. The body of the request is the product document we want to index.
PUT http://localhost:9200/chapter1/product/1
{
"title": "Learning Elasticsearch",
"author": "Abhishek Andhavarapu",
"category": "books"
}
Let's inspect the request:
INDEX |
chapter1 |
TYPE |
product |
IDENTIFIER |
1 |
DOCUMENT |
JSON |
HTTP METHOD |
PUT |
The document's properties, such as title, author, the category, are also known as fields, which are similar to SQL columns.
Elasticsearch will automatically create the index chapter1 and type product if they don't exist already. It will create the index with the default settings.
When we execute the preceding request, Elasticsearch responds with a JSON response, shown as follows:
{
"_index": "chapter1",
"_type": "product",
"_id": "1",
"_version": 1,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"created": true
}
In the response, you can see that Elasticsearch created the document and the version of the document is 1. Since you are creating the document using the HTTP PUT method, you are required to specify the document identifier. If you don’t specify the identifier, Elasticsearch will respond with the following error message:
No handler found for uri [/chapter1/product/] and method [PUT]
If you don’t have a unique identifier, you can let Elasticsearch assign an identifier for you, but you should use the POST HTTP method. For example, if you are indexing log messages, you will not have a unique identifier for each log message, and you can let Elasticsearch assign the identifier for you.
In general, we use the HTTP POST method for creating an object. The HTTP PUT method can also be used for object creation, where the client provides the unique identifier instead of the server assigning the identifier.
We can index a document without specifying a unique identifier as shown here:
POST http://localhost:9200/chapter1/product/
{
"title": "Learning Elasticsearch",
"author": "Abhishek Andhavarapu",
"category": "books"
}
In the above request, URL doesn't contain the unique identifier and we are using the HTTP POST method. Let's inspect the request:
INDEX |
chapter1 |
TYPE |
product |
DOCUMENT |
JSON |
HTTP METHOD |
POST |
The response from Elasticsearch is shown as follows:
{
"_index": "chapter1",
"_type": "product",
"_id": "AVmKvtPwWuEuqke_aRsm",
"_version": 1,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"created": true
}
You can see from the response that Elasticsearch assigned the unique identifier AVmKvtPwWuEuqke_aRsm to the document and created flag is set to true. If a document with the same unique identifier already exists, Elasticsearch replaces the existing document and increments the document version. If you have to run the same PUT request from the beginning of the section, the response from Elasticsearch would be this:
{
"_index": "chapter1",
"_type": "product",
"_id": "1",
"_version": 2,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"created": false
}
In the response, you can see that the created flag is false since the document with id: 1 already exists. Also, observe that the version is now 2.