Indexing a document (POST/PUT) in Elasticsearch - Step-by-Step Execution

Concept Flow - Indexing a document (POST/PUT)

Prepare JSON document

↓

Send POST or PUT request

↓

Elasticsearch receives request

↓

Store document in index

↓

Return response with status

↓

Client receives confirmation

This flow shows how a JSON document is sent to Elasticsearch using POST or PUT to store it in an index and get a confirmation response.

Execution Sample

Elasticsearch

PUT /my_index/_doc/1
{
  "name": "Alice",
  "age": 30
}

This code sends a PUT request to add or replace a document with id 1 in the 'my_index' index.

Execution Table

Step	Action	Request Content	Elasticsearch Action	Response
1	Client prepares JSON document	{"name": "Alice", "age": 30}	Waiting for request	No response yet
2	Client sends PUT request to /my_index/_doc/1	{"name": "Alice", "age": 30}	Receives request, parses JSON	Processing
3	Elasticsearch stores document in 'my_index' with id '1'	{"name": "Alice", "age": 30}	Document saved in index	Acknowledgement ready
4	Elasticsearch sends response	N/A	N/A	{"_index":"my_index","_id":"1","result":"created"}
5	Client receives response	N/A	N/A	Document indexed successfully

💡 Document is stored and response confirms success

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
document	empty	{"name": "Alice", "age": 30}	{"name": "Alice", "age": 30}	stored in index	stored in index
request_status	none	prepared	sent	received	response sent
response	none	none	none	ready	{"_index":"my_index","_id":"1","result":"created"}

Key Moments - 3 Insights

Why do we use POST or PUT to index a document?

POST adds a new document with an auto-generated or specified ID, while PUT creates or replaces a document at a specific ID. See execution_table steps 2 and 3.

What happens if the document ID already exists when using POST?

POST without specifying an ID creates a new document with a unique ID. If you specify an ID with POST, it will update the document. PUT always replaces or creates at the ID. This is shown in the request URL in step 2.

What does the response tell us?

The response confirms if the document was created or updated successfully. In step 4, the response shows 'result':'created' meaning the document was added.

Visual Quiz - 3 Questions

Look at the execution_table, what is the response content at step 4?

A {"_index":"my_index","_id":"1","result":"created"}

B Document saved in index

C Processing

D No response yet

💡 Hint

Check the 'Response' column in execution_table row for step 4

At which step does Elasticsearch store the document in the index?

A Step 1

B Step 2

C Step 3

D Step 5

💡 Hint

Look at the 'Elasticsearch Action' column to find when the document is saved

If the document JSON changes before sending, which variable in variable_tracker changes?

A request_status

B document

C response

D none

💡 Hint

Check the 'document' variable values across steps in variable_tracker

Concept Snapshot

Indexing a document in Elasticsearch:
- Use POST to add a new document (auto or specified ID)
- Use PUT to create or replace a document at a specific ID
- Send JSON body with document fields
- Elasticsearch stores document in the index
- Response confirms success or failure

Full Transcript

Indexing a document in Elasticsearch involves sending a JSON document using POST or PUT requests to a specific index and document ID. The client prepares the JSON data, sends it to Elasticsearch, which then stores the document in the index. Elasticsearch responds with a confirmation message indicating if the document was created or updated. POST can add new documents or update existing ones if an ID is specified, while PUT replaces or creates a document at the given ID. The response includes details like the index name, document ID, and result status. This process ensures data is stored and searchable in Elasticsearch.

Practice

1. What is the main difference between using POST and PUT when indexing a document in Elasticsearch?

easy

A. POST adds a document with an auto-generated ID, PUT adds or replaces a document with a specified ID.

B. POST deletes a document, PUT updates a document.

C. POST is used only for searching, PUT is used for indexing.

D. POST requires an ID, PUT never requires an ID.

Solution

1. Step 1: Understand POST behavior

   POST indexes a document and Elasticsearch generates a unique ID automatically.

2. Step 2: Understand PUT behavior

   PUT indexes a document with the ID you specify, replacing any existing document with that ID.

3. Final Answer:

   POST adds a document with an auto-generated ID, PUT adds or replaces a document with a specified ID. -> Option A

4. Quick Check:

   Method difference = auto ID vs specified ID [OK]

Hint: Remember: POST auto-IDs, PUT needs your ID [OK]

Common Mistakes:

• Thinking POST deletes documents
• Confusing PUT with search operation
• Assuming PUT never requires an ID

2. Which of the following is the correct syntax to index a document with ID "123" using PUT in Elasticsearch?

easy

A. POST /index/_doc {"field": "value"}

B. POST /index/_doc/123 {"field": "value"}

C. PUT /index/_doc {"field": "value"}

D. PUT /index/_doc/123 {"field": "value"}

Solution

1. Step 1: Identify correct HTTP method and URL

   To specify an ID, use PUT with the URL including the ID: /index/_doc/123.

2. Step 2: Confirm request body format

   The body contains the document fields as JSON, e.g., {"field": "value"}.

3. Final Answer:

   PUT /index/_doc/123 {"field": "value"} -> Option D

4. Quick Check:

   PUT + ID in URL = correct syntax [OK]

Hint: PUT with ID in URL, POST without ID [OK]

Common Mistakes:

• Using POST with an ID in URL
• Omitting the ID when using PUT
• Confusing URL structure

3. Given this request to index a document:

POST /products/_doc
{
  "name": "Coffee Mug",
  "price": 12.99
}

What will Elasticsearch do after this request?

medium

A. Index the document with an auto-generated ID under the 'products' index.

B. Replace any existing document with ID 'products'.

C. Return an error because ID is missing.

D. Create a new index named '_doc'.

Solution

1. Step 1: Analyze the HTTP method and URL

   The request uses POST on /products/_doc, which means index 'products' and type '_doc'.

2. Step 2: Understand ID assignment

   Since no ID is specified, Elasticsearch generates a unique ID automatically and indexes the document.

3. Final Answer:

   Index the document with an auto-generated ID under the 'products' index. -> Option A

4. Quick Check:

   POST without ID = auto-generated ID [OK]

Hint: POST without ID means auto ID assigned [OK]

Common Mistakes:

• Thinking missing ID causes error
• Assuming document replaces existing one
• Confusing index and type names

4. You tried to index a document with PUT /myindex/_doc without specifying an ID. What is the problem with this request?

medium

A. It will create a document with a random ID.

B. It will update all documents in the index.

C. It will cause a syntax error because ID is missing in the URL.

D. It will delete the entire index.

Solution

1. Step 1: Check the HTTP method and URL requirements

   PUT requires an explicit document ID in the URL to index or replace a document.

2. Step 2: Identify the error cause

   Since the ID is missing, Elasticsearch will reject the request with an error due to invalid URL syntax.

3. Final Answer:

   It will cause a syntax error because ID is missing in the URL. -> Option C

4. Quick Check:

   PUT needs ID in URL [OK]

Hint: PUT without ID in URL causes error [OK]

Common Mistakes:

• Assuming PUT auto-generates ID
• Thinking it deletes index
• Believing it updates all documents

5. You want to update a document if it exists or create it if it doesn't, using ID "789" in index "users". Which is the best way to do this in Elasticsearch?

hard

A. Use POST /users/_doc with the document body {"id": "789"}.

B. Use PUT /users/_doc/789 with the document body.

C. Use POST /users/_doc without ID.

D. Use DELETE /users/_doc/789 then POST /users/_doc.

Solution

1. Step 1: Understand update or create behavior

   PUT with a specified ID will create the document if missing or replace it if it exists.

2. Step 2: Compare options

   POST without ID creates new documents with auto IDs, so it won't update by ID. Deleting then posting is inefficient.

3. Final Answer:

   Use PUT /users/_doc/789 with the document body. -> Option B

4. Quick Check:

   PUT with ID updates or creates [OK]

Hint: PUT with ID updates or creates document [OK]

Common Mistakes:

• Specifying ID in the document body
• Omitting ID when update needed
• Deleting before posting wastes resources