How to create an index in Elasticsearch

Creating an index in Elasticsearch gives a dataset a named storage and search boundary before documents arrive. It is useful when an application needs explicit shard counts, field mappings, or a plain index instead of relying on automatic index creation.

The Create index API accepts the index name in PUT /{index} and can store settings and mappings in the same request. A one-node validation cluster can use one primary shard, zero replicas, and explicit date, keyword, and text fields so later document writes use the intended field types.

On secured clusters, use the HTTPS endpoint with Basic, Bearer, or API key credentials. Names that match built-in data-stream templates, including logs-*-*, should use the data stream workflow unless the cluster has a deliberate template override.

1. Choose a standalone index name that does not match built-in data-stream templates.

   A name such as logs-sgtest-default can be rejected because current Elasticsearch clusters install built-in templates for log data streams. Use an application-specific plain index name unless the target is intentionally a data stream.

2. Create the index with explicit settings and field mappings.

   $ curl --silent --show-error --fail --header "Content-Type: application/json" --request PUT "http://localhost:9200/app-events-2026.04?pretty" --data '{
     "settings": {
       "number_of_shards": 1,
       "number_of_replicas": 0
     },
     "mappings": {
       "properties": {
         "timestamp": { "type": "date" },
         "level": { "type": "keyword" },
         "message": { "type": "text" }
       }
     }
   }'
   {
     "acknowledged" : true,
     "shards_acknowledged" : true,
     "index" : "app-events-2026.04"
   }

   Explicit settings and mappings in the create request override matching template values for this new index.

   Related: How to create and manage index templates in Elasticsearch
   Tool: JSON Validator

3. Confirm the index exists and the single-node shard layout is green.

   $ curl --silent --show-error --fail "http://localhost:9200/_cat/indices/app-events-2026.04?v"
   health status index              uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
   green  open   app-events-2026.04 Hx3M8bQkRmaz3-Ar9wqHig   1   0          0            0       227b           227b         227b

   Using number_of_replicas 0 keeps the sample index green on a one-node cluster. Raise the replica count when another data node should hold a copy.

4. Review the mapping returned by Elasticsearch.

   $ curl --silent --show-error --fail "http://localhost:9200/app-events-2026.04/_mapping?pretty"
   {
     "app-events-2026.04" : {
       "mappings" : {
         "properties" : {
           "level" : {
             "type" : "keyword"
           },
           "message" : {
             "type" : "text"
           },
           "timestamp" : {
             "type" : "date"
           }
         }
       }
     }
   }

5. Index a test document with a fixed document ID.

   $ curl --silent --show-error --fail --header "Content-Type: application/json" --request PUT "http://localhost:9200/app-events-2026.04/_doc/test-event-1?refresh=wait_for&pretty&filter_path=_index,_id,result,_shards.total,_shards.successful,_shards.failed" --data '{
     "timestamp": "2026-04-02T07:40:00Z",
     "level": "INFO",
     "message": "index created"
   }'
   {
     "_index" : "app-events-2026.04",
     "_id" : "test-event-1",
     "result" : "created",
     "_shards" : {
       "total" : 1,
       "successful" : 1,
       "failed" : 0
     }
   }

   refresh=wait_for waits for the next refresh cycle so the document is searchable immediately after the write without forcing an immediate refresh.

6. Search the new index for the test document.

   $ curl --silent --show-error --fail --header "Content-Type: application/json" --request POST "http://localhost:9200/app-events-2026.04/_search?pretty&filter_path=hits.total,hits.hits._id,hits.hits._source" --data '{
     "query": {
       "match": {
         "message": "created"
       }
     }
   }'
   {
     "hits" : {
       "total" : {
         "value" : 1,
         "relation" : "eq"
       },
       "hits" : [
         {
           "_id" : "test-event-1",
           "_source" : {
             "timestamp" : "2026-04-02T07:40:00Z",
             "level" : "INFO",
             "message" : "index created"
           }
         }
       ]
     }
   }

   Related: How to perform a search query in Elasticsearch

7. Remove the test document after verification.

   $ curl --silent --show-error --fail --request DELETE "http://localhost:9200/app-events-2026.04/_doc/test-event-1?refresh=wait_for&pretty&filter_path=_index,_id,result"
   {
     "_index" : "app-events-2026.04",
     "_id" : "test-event-1",
     "result" : "deleted"
   }

   The index, settings, and mappings remain in place after the verification document is removed.