In this tutorial:
Creating a document in Elasticsearch with an existing ID Creating a document in Elasticsearch without an existing ID
Individual entries within Elasticsearch are referred to as documents. These documents contain various entries that relate to a single record and are stored in the appropriate index. For example, an index named customers may contain a document with records such as first_name, last_name, and email_address. Think of a document as an individual object and each entry describes a single item within that object.
Note: This article assumes that you have already installed Elasticsearch as well as have created an index within Elasticsearch.
As you may already know from our article on creating an index within Elasticsearch, data is both inserted as well as retrieved using simple HTTP requests. The same will be done in this article.
Creating a document in Elasticsearch with a pre-defined ID
If you already know the ID that you want associated with your new document, you can insert a new document with that ID. The following command line example will insert a new document into Elasticsearch with our predefined ID:
user@server [~]# curl -XPUT ‘localhost:9200/mynewindex/external/mynewid?pretty’ -d ‘
{
“first_name”: “John”,
“last_name”: “Doe”,
“email_address”: “[email protected]”
}’
As you can see in the above, we are making a simple PUT request using the curl command to our Elasticsearch server that is located at localhost on port 9200.
Then, we are defining an index that we want this document to be located in which is mynewindex. After this, we are stating the data type that we want to place the data within. In this case, our type is external.
We are then defining the ID within the last part of the URL which in this case, is mynewid. The last little bit (?pretty) is simply stating that we want a well-formatted response.
Lastly, is simply our data that we are placing into the document, formatted in JSON. As you can see, we are inserting an individual’s first name, last name, and email address.
If all goes well, you will get a response back that looks like this:
user@server [~]# curl -XPUT ‘localhost:9200/mynewindex/external/mynewid?pretty’ -d ‘
{
“first_name”: “John”,
“last_name”: “Doe”,
“email_address”: “[email protected]”
}’
{
“_index” : “mynewindex”,
“_type” : “external”,
“_id” : “mynewid”,
“_version” : 1,
“created” : true
}
As you can see in the above, our new document was successfully created in the index mynewindex with the type external and the ID mynewid.
What happens if you don’t have an ID that you specifically want to define? Follow our next section to learn how to insert a new document without defining an ID.
Inserting a document in Elasticsearch without defining an ID
Inserting a document without specifically defining an ID for it is quite easy. If an ID is not passed, it will simply create one for you. We can do so by executing the following command:
user@server [~]# curl -XPOST ‘localhost:9200/mynewindex/external?pretty’ -d ‘
{
“first_name”: “John”,
“last_name”: “Doe”,
“email_address”: “[email protected]”
}’
The above example is very similar to creating a document with a pre-defined ID but with a few minor changes.
First, we are sending a POST request instead of a PUT request. Next, we are simply removing the ID that we previously had defined.
When executing this, you should have the following response:
user@server [~]# curl -XPOST ‘localhost:9200/mynewindex/external?pretty’ -d ‘
{
“first_name”: “John”,
“last_name”: “Doe”,
“email_address”: “[email protected]”
}’
{
“_index” : “mynewindex”,
“_type” : “external”,
“_id” : “AUruRKQIWyBxgi2aaH34”,
“_version” : 1,
“created” : true
}
As you can see in the above example, the ID has been automatically created with a random string. This is especially useful if the data you are inserting does not have a way to uniquely identify it such as a list of customers.
You should now be able to insert new documents within Elasticsearch. If you have any questions or anything to add, leave a comment below.
