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
-
Name of the index you wish to create. Index names must meet the following criteria:
- Lowercase only
- Cannot include
\,/,*,?,",<,>,|,(space character),,, or# - Indices prior to 7.0 could contain a colon (
:), but that has been deprecated and will not be supported in later versions - Cannot start with
-,_, or+ - Cannot be
.or.. - Cannot be longer than 255 bytes (note thtat it is bytes, so multi-byte characters will reach the limit faster)
- Names starting with
.are deprecated, except for hidden indices and internal indices managed by plugins
Query parameters
-
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.
Values are
-1or0.External documentation -
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are
-1or0.External documentation -
The number of shard copies that must be active before proceeding with the operation. Set to
allor any positive integer up to the total number of shards in the index (number_of_replicas+1).Values are
allorindex-setting.
Body
-
Aliases for the index.
Hide aliases attribute Show aliases attribute object
-
Hide * attributes Show * attributes object
-
Query used to limit documents the alias can access.
External documentation Hide filter attributes Show filter attributes object
-
Returns documents that contain terms similar to the search term, as measured by a Levenshtein edit distance.
External documentation -
Matches
geo_pointandgeo_shapevalues that intersect a grid cell from a GeoGrid aggregation. -
Returns documents based on the order and proximity of matching terms.
External documentation -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
External documentation -
Analyzes its input and constructs a
boolquery from the terms. Each term except the last is used in atermquery. The last term is used in a prefix query.External documentation -
Analyzes the text and creates a phrase query out of the analyzed text.
External documentation -
Returns documents that contain the words of a provided text, in the same order as provided. The last term of the provided text is treated as a prefix, matching any words that begin with that term.
External documentation -
Returns documents that contain a specific prefix in a provided field.
External documentation -
Returns documents that contain terms within a provided range.
External documentation -
Returns documents that contain terms matching a regular expression.
External documentation -
Matches spans containing a term.
External documentation -
Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
External documentation -
Returns documents that contain a minimum number of exact terms in a provided field. To return a document, a required number of terms must exactly match the field values, including whitespace and capitalization.
External documentation -
Uses a natural language processing model to convert the query text into a list of token-weight pairs which are then used in a query against a sparse vector or rank features field.
External documentation -
Supports returning text_expansion query results by sending in precomputed tokens with the query.
External documentation -
Returns documents that contain terms matching a wildcard pattern.
External documentation
-
Value used to route indexing operations to a specific shard. If specified, this overwrites the
routingvalue for indexing operations. -
If
true, the alias is hidden. All indices for the alias must have the sameis_hiddenvalue.Default value is
false. -
If
true, the index is the write index for the alias.Default value is
false. -
Value used to route indexing and search operations to a specific shard.
-
Value used to route search operations to a specific shard. If specified, this overwrites the
routingvalue for search operations.
-
-
-
Mapping for fields in the index. If specified, this mapping can include:
- Field names
- Field data types
- Mapping parameters
Hide mappings attributes Show mappings attributes object
-
Hide all_field attributes Show all_field attributes object
-
Values are
strict,runtime,true, orfalse. -
-
Hide runtime attribute Show runtime attribute object
-
Hide * attributes Show * attributes object
-
For type
composite -
For type
lookup -
A custom format for
datetype runtime fields. -
For type
lookup -
For type
lookup -
For type
lookup -
Painless script executed at query time.
-
Field type, which can be:
boolean,composite,date,double,geo_point,ip,keyword,long, orlookup.Values are
boolean,composite,date,double,geo_point,geo_shape,ip,keyword,long, orlookup.
-
-
-
Values are
trueorfalse.
-
Configuration options for the index.
Hide settings attributes Show settings attributes object
-
Hide soft_deletes attributes Show soft_deletes attributes object
-
Indicates whether soft deletes are enabled on the index.
Default value is
true. -
The maximum period to retain a shard history retention lease before it is considered expired. Shard history retention leases ensure that soft deletes are retained during merges on the Lucene index. If a soft delete is merged away before it can be replicated to a follower the following process will fail due to incomplete history on the leader.
-
-
Hide sort attributes Show sort attributes object
-
Values are
true,false, orchecksum. -
Default value is
LZ4. -
Default value is
true. auto_expand_replicas
string | null -
A duration. Units can be
nanos,micros,ms(milliseconds),s(seconds),m(minutes),h(hours) andd(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.External documentation -
Default value is
10000.0. -
Default value is
100.0. -
Default value is
10000.0. -
Default value is
100.0. -
Default value is
32.0. -
Default value is
1.0. -
Default value is
3.0. -
Hide blocks attributes Show blocks attributes object
-
Settings to define analyzers, tokenizers, token filters and character filters. Refer to the linked documentation for step-by-step examples of updating analyzers on existing indices.
External documentation Hide analyze attribute Show analyze attribute object
-
Default value is
65536.0. -
Default value is
1000.0. -
A duration. Units can be
nanos,micros,ms(milliseconds),s(seconds),m(minutes),h(hours) andd(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.External documentation -
Hide lifecycle attributes Show lifecycle attributes object
-
The name of the policy to use to manage the index. For information about how Elasticsearch applies policy changes, see Policy updates.
-
If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds.
Default value is
0.0. -
Set to true to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern .*-{date_format}-\d+, where the date_format is yyyy.MM.dd and the trailing digits are optional. An index that was rolled over would normally match the full format, for example logs-2016.10.31-000002). If the index name doesn’t match the pattern, index creation fails.
-
The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see Rollover.
Default value is empty.
-
-
Hide translog attributes Show translog attributes object
-
How often the translog is fsynced to disk and committed, regardless of write operations. Values less than 100ms are not allowed.
External documentation -
Whether or not to
fsyncand commit the translog after every index, delete, update, or bulk request.Values are
request,REQUEST,async, orASYNC. flush_threshold_size
number | string The translog stores all operations that are not yet safely persisted in Lucene (i.e., are not part of a Lucene commit point). Although these operations are available for reads, they will need to be replayed if the shard was stopped and had to be recovered. This setting controls the maximum total size of these operations, to prevent recoveries from taking too long. Once the maximum size has been reached a flush will happen, generating a new Lucene commit point.
-
-
Hide query_string attribute Show query_string attribute object
-
Configure custom similarity settings to customize how search results are scored.
-
Enable or disable dynamic mapping for an index.
Hide mapping attributes Show mapping attributes object
-
Hide depth attribute Show depth attribute object
-
Hide nested_fields attribute Show nested_fields attribute object
-
The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index.
Default value is
50.0.
-
-
Hide nested_objects attribute Show nested_objects attribute object
-
Hide field_name_length attribute Show field_name_length attribute object
-
Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is
Long.MAX_VALUE(no limit).
-
-
Hide dimension_fields attribute Show dimension_fields attribute object
-
Configure indexing back pressure limits.
Hide indexing_pressure attribute Show indexing_pressure attribute object
-
Hide memory attribute Show memory attribute object
-
Number of outstanding bytes that may be consumed by indexing requests. When this limit is reached or exceeded, the node will reject new coordinating and primary operations. When replica operations consume 1.5x this limit, the node will reject new replica operations. Defaults to 10% of the heap.
-
-
-
The store module allows you to control how index data is stored and accessed on disk.
Hide store attributes Show store attributes object
-
You can restrict the use of the mmapfs and the related hybridfs store type via the setting node.store.allow_mmap. This is a boolean setting indicating whether or not memory-mapping is allowed. The default is to allow it. This setting is useful, for example, if you are in an environment where you can not control the ability to create a lot of memory maps so you need disable the ability to use memory-mapping.
-
How often store statistics are refreshed
External documentation
curl \
--request PUT 'http://api.example.com/{index}' \
--header "Content-Type: application/json" \
--data '"{\n \"settings\": {\n \"number_of_shards\": 3,\n \"number_of_replicas\": 2\n }\n}"'{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 2
}
}{
"settings": {
"number_of_shards": 1
},
"mappings": {
"properties": {
"field1": { "type": "text" }
}
}
}{
"aliases": {
"alias_1": {},
"alias_2": {
"filter": {
"term": {
"user.id": "kimchy"
}
},
"routing": "shard-1"
}
}
}