Create index API
editCreate index API
editCreates a new index.
PUT /twitter
Request
editPUT /<index>
Description
editYou 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
Path parameters
edit-
<index>
-
(Required, string) Name of the index you wish to create.
Index names must meet the following criteria:
- Lowercase only
-
Cannot include
\
,/
,*
,?
,"
,<
,>
,|
, ` ` (space character),,
,#
-
Indices prior to 7.0 could contain a colon (
:
), but that’s been deprecated and won’t be supported in 7.0+ -
Cannot start with
-
,_
,+
-
Cannot be
.
or..
- Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster)
Query parameters
edit-
include_type_name
-
[7.0.0]
Deprecated in 7.0.0. Mapping types have been deprecated. See Removal of mapping types.
(Optional, boolean) If
true
, a mapping type is expected in the body of mappings. Defaults tofalse
. -
wait_for_active_shards
-
(Optional, string) 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
). Default: 1, the primary shard.See Active shards.
-
master_timeout
-
(Optional, time units) Specifies the period of time 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. Defaults to
30s
. -
timeout
-
(Optional, time units) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to
30s
.
Request body
edit-
aliases
- (Optional, alias object) Index aliases which include the index. See Update index alias.
-
mappings
-
(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:
- Field names
- Field datatypes
- Mapping parameters
See Mapping.
-
settings
- (Optional, index setting object) Configuration options for the index. See Index Settings.
Examples
editIndex settings
editEach index created can have specific settings associated with it, defined in the body:
Default for |
|
Default for |
or more simplified
PUT /twitter { "settings" : { "number_of_shards" : 3, "number_of_replicas" : 2 } }
You do not have to explicitly specify index
section inside the
settings
section.
For more information regarding all the different index level settings that can be set when creating an index, please check the index modules section.
Mappings
editThe create index API allows for providing a mapping definition:
PUT /test { "settings" : { "number_of_shards" : 1 }, "mappings" : { "properties" : { "field1" : { "type" : "text" } } } }
Before 7.0.0, the mappings definition used to include a type name. Although specifying types in requests is now deprecated, a type can still be provided if the request parameter include_type_name is set. For more details, please see Removal of mapping types.
Aliases
editThe create index API allows also to provide a set of aliases:
PUT /test { "aliases" : { "alias_1" : {}, "alias_2" : { "filter" : { "term" : {"user" : "kimchy" } }, "routing" : "kimchy" } } }
Wait For active shards
editBy 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:
{ "acknowledged": true, "shards_acknowledged": true, "index": "test" }
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 the index creation was successful.
These values simply indicate whether the operation completed before the timeout. If
acknowledged
is false
, then we 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 we 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 (i.e. acknowledged=true
).
We 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):
PUT /test { "settings": { "index.write.wait_for_active_shards": "2" } }
or through the request parameter wait_for_active_shards
:
PUT /test?wait_for_active_shards=2
A detailed explanation of wait_for_active_shards
and its possible values can be found
here.