Understanding What “Creating a Document” Means in Elasticsearch

In Elasticsearch, data is stored in the form of documents, and these documents are stored inside an index.

You can think of this analogy:

• Index → Database table
• Document → Row in the table
• Field → Column

However, Elasticsearch is schema-flexible, meaning it does not strictly require a predefined structure like relational databases.

Basic Idea of Adding a Document

To add a document in Elasticsearch, we use a POST request with the following structure:

POST /<index_name>/_doc

Along with this request, we send a JSON object that represents the data we want to store.

Example structure:

POST /products/_doc

{
  "field1": "value",
  "field2": 123,
  "field3": "some text"
}

Once this request is sent, Elasticsearch stores the document inside the specified index.

Sample output:

{
  "_index": "products",
  "_id": "pi8DgJsBbasCwocrpxL8",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Important Note About Schema (Mapping)

You might be wondering:

“Where do we define the schema?
How do we define data types like number, date, string, etc.?”

In Elasticsearch, this concept is called mapping.

Key points about mapping:

• Mapping defines field names and their data types.
• It is optional, not mandatory.
• If you do not define a mapping, Elasticsearch will automatically infer the data types based on the data you send.
• This feature is known as dynamic mapping.

Although Elasticsearch can infer types automatically, it is always a good practice to define mappings explicitly, especially in production systems.
We will cover mapping in detail later in a dedicated section, so for now, we will keep things simple.

Using Kibana Dev Tools

For this tutorial, we will use Kibana Dev Tools, which provides a clean interface to interact with Elasticsearch using REST APIs.

You do not need to manually add headers such as:

• Content-Type: application/json

Kibana automatically handles this for you behind the scenes.

Understanding the Response

After a successful request, you will see a response similar to this:

{
  "_index": "products",
  "_id": "pi8DgJsBbasCwocrpxL8",
  "result": "created"
}

Important things to note:

• The "result": "created" confirms that the document was successfully added.
• The _id field is automatically generated by Elasticsearch.

Understanding Document IDs

Every document in Elasticsearch has a unique ID.

Two important options exist:

1. Auto-generated ID (default)

If you do not specify an ID, Elasticsearch automatically generates a unique one.

Example:

"_id": "xYzAbC123"

This is the simplest and most commonly used approach.

2. Custom ID (optional)

If you want full control, you can provide your own ID:

POST /books/_doc/1

This means:

• The document ID will be 1
• You are responsible for ensuring uniqueness

This is useful when:

• You already have a unique identifier from another system
• You want predictable IDs like 1, 2, 3, etc.

Adding Multiple Documents

When you add another document using the same approach:

{
  "title": "Atomic Habits",
  "author": "James Clear",
  "price": 499,
  "published_year": 2018
}

Elasticsearch will again generate a new unique ID for it.

Each document is stored independently, even though they belong to the same index.