Elasticsearch Indexes and Documents

An index stores your data. A document is the individual record inside an index. Knowing how to create, view, and manage both is the first practical skill in Elasticsearch.

Think of a Filing Cabinet

Filing Cabinet  =  Elasticsearch Cluster
Drawer          =  Index
Folder          =  Shard (Elasticsearch manages this automatically)
Sheet of paper  =  Document
Line on paper   =  Field

You create a drawer (index), then place sheets of paper (documents) inside it. Elasticsearch handles the internal filing (shards) for you.

Creating an Index

Use a PUT request to create an index. Index names must be lowercase with no spaces.

PUT /products

Elasticsearch responds with:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "products"
}

acknowledged: true means the index was created successfully.

Adding a Document

Use a POST request to add a document. Elasticsearch generates a random ID for it.

POST /products/_doc
{
  "name": "Wireless Keyboard",
  "brand": "TechCo",
  "price": 1299,
  "in_stock": true
}

To assign your own ID, use PUT instead and include the ID in the URL:

PUT /products/_doc/101
{
  "name": "Wireless Keyboard",
  "brand": "TechCo",
  "price": 1299,
  "in_stock": true
}

Retrieving a Document by ID

GET /products/_doc/101

Elasticsearch returns the full document wrapped in metadata:

{
  "_index": "products",
  "_id": "101",
  "_version": 1,
  "found": true,
  "_source": {
    "name": "Wireless Keyboard",
    "brand": "TechCo",
    "price": 1299,
    "in_stock": true
  }
}

The actual data lives inside the _source field. The fields starting with underscore are Elasticsearch metadata.

Document Metadata Fields

Listing All Documents in an Index

GET /products/_search
{
  "query": {
    "match_all": {}
  }
}

This returns every document in the index — up to 10 by default. You will learn to paginate and filter results in later topics.

Deleting a Document

DELETE /products/_doc/101

Deleting an Entire Index

DELETE /products

This removes the index and every document inside it permanently. There is no undo.

Checking Index Information

GET /products

Elasticsearch returns the index's mappings, settings, and aliases — all the metadata about the index structure.

Listing All Indexes in the Cluster

GET /_cat/indices?v

The ?v flag adds column headers to the output. You see each index name, its health status, number of documents, and disk space used.

health status index    docs.count store.size
green  open   products      5         12kb
green  open   employees    42        108kb

Index Naming Rules

Index names must follow these rules or Elasticsearch rejects them:

• Lowercase letters only — no uppercase
• No spaces — use hyphens or underscores
• No special characters except hyphens, underscores, and dots
• Cannot start with a hyphen or underscore
• Good examples: products, web-logs-2024, user_events