elasticsearch/docs/reference/indices/create-index.asciidoc

[[indices-create-index]]
=== Create index API
++++
<titleabbrev>Create index</titleabbrev>
++++

Creates a new index.

[source,console]
--------------------------------------------------
PUT /my-index-000001
--------------------------------------------------


[[indices-create-api-request]]
==== {api-request-title}

`PUT /<index>`

[[indices-create-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `create_index`
or `manage` <<privileges-list-indices,index privilege>> for the target index. To
add the index to an alias, you must have the `manage` index privilege for the
alias.

[[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>`::
+
--
(Required, 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)
- Names starting with `.` are deprecated, except for <<index-hidden,hidden indices>> and internal indices managed by plugins
// end::index-name-reqs[]
--


[[indices-create-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

[role="child_attributes"]
[[indices-create-api-request-body]]
==== {api-request-body-title}

`aliases`::
(Optional, object of objects) Aliases for the index.
+
--
// tag::aliases-props[]
[%collapsible%open]
.Properties of `aliases` objects
=======
`<alias>`::
(Required, object) The key is the alias name. Supports
<<date-math-index-names,date math>>.
+
The object body contains options for the alias. Supports an empty object.
+
.Properties of `<alias>`
[%collapsible%open]
======
`filter`::
(Optional, <<query-dsl,Query DSL object>>) Query used to limit documents the
alias can access.

`index_routing`::
(Optional, string) Value used to route indexing operations to a specific shard.
If specified, this overwrites the `routing` value for indexing operations.

`is_hidden`::
(Optional, Boolean) If `true`, the alias is <<hidden,hidden>>. Defaults to
`false`. All indices for the alias must have the same `is_hidden` value.

`is_write_index`::
(Optional, Boolean) If `true`, the index is the <<write-index,write index>> for
the alias. Defaults to `false`.

`routing`::
(Optional, string) Value used to route indexing and search operations to a
specific shard.

`search_routing`::
(Optional, string) Value used to route search operations to a specific shard. If
specified, this overwrites the `routing` value for search operations.
======
=======
// end::aliases-props[]
--

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings]

include::{es-repo-dir}/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 /my-index-000001
{
  "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 /my-index-000001
{
  "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" }
    }
  }
}
--------------------------------------------------

[[create-index-aliases]]
===== Aliases

The create index API allows also to provide a set of <<alias,aliases>>:

[source,console]
--------------------------------------------------
PUT /test
{
  "aliases": {
    "alias_1": {},
    "alias_2": {
      "filter": {
        "term": { "user.id": "kimchy" }
      },
      "routing": "shard-1"
    }
  }
}
--------------------------------------------------

Index alias names also support <<date-math-index-names,date math>>.

[source,console]
----
PUT /logs
{
  "aliases": {
    "<logs_{now/M}>": {}
  }
}
----

[[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": "logs"
}
--------------------------------------------------

`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>>.