Create an index

Auth

You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:

  • Settings for the index.
  • Mappings for fields in the index.
  • Index aliases

Wait for active shards

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out. The index creation response will indicate what happened. For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out. Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful. These values simply indicate whether the operation completed before the timeout. If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon. If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).

You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards. Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.

Required authorization

Index privileges create_index manage

Path parameters

index string required

Name of the index you wish to create.

Query parameters

master_timeout string · default: 30s

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

timeout string · default: 30s

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

wait_for_active_shards union oneOf · default: 1

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Values: all index-setting

Request body

aliases map string to object

Aliases for the index.

<string> object
filter {} Query

Query used to limit documents the alias can access.

index_routing string

Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.

is_hidden boolean · default: false

If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

is_write_index boolean · default: false

If true, the index is the write index for the alias.

routing string

Value used to route indexing and search operations to a specific shard.

search_routing string

Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.

mappings object

Mapping for fields in the index. If specified, this mapping can include:

  • Field names
  • Field data types
  • Mapping parameters
all_field object
analyzer string required
enabled boolean required
omit_norms boolean required
search_analyzer string required
similarity string required
store boolean required
store_term_vector_offsets boolean required
store_term_vector_payloads boolean required
store_term_vector_positions boolean required
store_term_vectors boolean required
date_detection boolean
dynamic enum
Values: strict runtime true false
dynamic_date_formats string[]
dynamic_templates string to object[]
_field_names object
enabled boolean required
index_field object
enabled boolean required
_meta object
numeric_detection boolean
properties map string to oneOf
_routing object
required boolean required
_size object
enabled boolean required
_source object
compress boolean
compress_threshold string
enabled boolean
excludes string[]
includes string[]
mode enum

Supported values include:

  • disabled
  • stored
  • synthetic: Instead of storing source documents on disk exactly as you send them, Elasticsearch can reconstruct source content on the fly upon retrieval.
Values: disabled stored synthetic
runtime map string to object
<string> object
fields map string to object

For type composite

<string> object
type enum required
Values: boolean composite date double geo_point geo_shape ip keyword long lookup
fetch_fields object[]

For type lookup

field string required
format string
format string

A custom format for date type runtime fields.

input_field string

For type lookup

target_field string

For type lookup

target_index string

For type lookup

script string

Painless script executed at query time.

on_script_error enum
Values: fail continue
type enum required

Field type, which can be: boolean, composite, date, double, geo_point, ip,keyword, long, or lookup.

Values: boolean composite date double geo_point geo_shape ip keyword long lookup
enabled boolean
subobjects enum
Values: true false
_data_stream_timestamp object
enabled boolean required
settings object

Configuration options for the index.

Response

application/json
index string required
shards_acknowledged boolean required
acknowledged boolean required