215 lines
6.1 KiB
Plaintext
215 lines
6.1 KiB
Plaintext
[[indices-create-index]]
|
|
=== Create index API
|
|
++++
|
|
<titleabbrev>Create index</titleabbrev>
|
|
++++
|
|
|
|
Creates a new index.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /twitter
|
|
--------------------------------------------------
|
|
|
|
|
|
[[indices-create-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /<index>`
|
|
|
|
[[indices-create-api-desc]]
|
|
==== {api-description-title}
|
|
You can use the create index API to add a new index to an {es} cluster. When
|
|
creating an index, you can specify the following:
|
|
|
|
* Settings for the index
|
|
* Mappings for fields in the index
|
|
* Index aliases
|
|
|
|
|
|
[[indices-create-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<index>`::
|
|
+
|
|
--
|
|
(Optional, string) Name of the index you wish to create.
|
|
|
|
// tag::index-name-reqs[]
|
|
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)
|
|
// end::index-name-reqs[]
|
|
--
|
|
|
|
|
|
[[indices-create-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
|
|
[[indices-create-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`aliases`::
|
|
(Optional, <<indices-aliases,alias object>>) Index aliases which include the
|
|
index. See <<indices-aliases>>.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=settings]
|
|
|
|
[[indices-create-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[[create-index-settings]]
|
|
===== Index settings
|
|
|
|
Each index created can have specific settings
|
|
associated with it, defined in the body:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /twitter
|
|
{
|
|
"settings" : {
|
|
"index" : {
|
|
"number_of_shards" : 3, <1>
|
|
"number_of_replicas" : 2 <2>
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> Default for `number_of_shards` is 1
|
|
<2> Default for `number_of_replicas` is 1 (ie one replica for each primary shard)
|
|
|
|
or more simplified
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /twitter
|
|
{
|
|
"settings" : {
|
|
"number_of_shards" : 3,
|
|
"number_of_replicas" : 2
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[NOTE]
|
|
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,index modules>> section.
|
|
|
|
[[mappings]]
|
|
===== Mappings
|
|
|
|
The create index API allows for providing a mapping definition:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /test
|
|
{
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
},
|
|
"mappings" : {
|
|
"properties" : {
|
|
"field1" : { "type" : "text" }
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
NOTE: 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-types>>.
|
|
|
|
[[create-index-aliases]]
|
|
===== Aliases
|
|
|
|
The create index API allows also to provide a set of <<indices-aliases,aliases>>:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /test
|
|
{
|
|
"aliases" : {
|
|
"alias_1" : {},
|
|
"alias_2" : {
|
|
"filter" : {
|
|
"term" : {"user" : "kimchy" }
|
|
},
|
|
"routing" : "kimchy"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[create-index-wait-for-active-shards]]
|
|
===== 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:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"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):
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /test
|
|
{
|
|
"settings": {
|
|
"index.write.wait_for_active_shards": "2"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[skip:requires two nodes]
|
|
|
|
or through the request parameter `wait_for_active_shards`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /test?wait_for_active_shards=2
|
|
--------------------------------------------------
|
|
// TEST[skip:requires two nodes]
|
|
|
|
A detailed explanation of `wait_for_active_shards` and its possible values can be found
|
|
<<index-wait-for-active-shards,here>>.
|