Create Index API

Introduced 1.0

The Create Index API creates a new index in an OpenSearch cluster.

You can use the Create Index API to specify the following index configurations:

• Index settings that control the index behavior, such as the number of shards and replicas.
• Field mappings that define the data types and properties for fields in documents stored in the index.
• Index aliases that provide alternate names for querying the index.

Endpoints

PUT /{index}

Index naming restrictions

OpenSearch indexes have the following naming restrictions:

• All letters must be lowercase.
• Index names can’t begin with underscores (_) or hyphens (-).

• Index names can’t contain spaces, commas, or the following characters:

  :, ", *, +, /, \, |, ?, #, >, or <

Path parameters

The following table lists the available path parameters.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Request body fields

You can include the following request body fields to configure the new index. All request body fields are optional.

Note: You do not have to explicitly specify the index section inside the settings section. You can use the simplified syntax instead.

Example: Creating a basic index

You typically do not need to explicitly create an empty index. OpenSearch automatically creates an index when you index a document into a non-existent index. However, explicitly creating an index is useful when you want to configure specific settings, mappings, or aliases before indexing data.

The following example request creates an index named sample-index without any settings, mappings, or aliases:

PUT /sample-index
{}

response = client.indices.create(
  index = "sample-index",
  body =   {}
)

Example: Creating an index with settings

The following example request creates an index named books with specific settings for the number of shards and replicas:

PUT /books
{
  "settings": {
    "index": {
      "number_of_shards": 2,
      "number_of_replicas": 1
    }
  }
}

response = client.indices.create(
  index = "books",
  body =   {
    "settings": {
      "index": {
        "number_of_shards": 2,
        "number_of_replicas": 1
      }
    }
  }
)

Example: Creating an index with simplified settings

The following example request creates an index named books-simplified using the simplified settings syntax without the index prefix:

PUT /books-simplified
{
  "settings": {
    "number_of_shards": 2,
    "number_of_replicas": 1
  }
}

response = client.indices.create(
  index = "books-simplified",
  body =   {
    "settings": {
      "number_of_shards": 2,
      "number_of_replicas": 1
    }
  }
)

Example: Creating an index with mappings

The following example request creates an index named employees with field mappings:

PUT /employees
{
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "age": {
        "type": "integer"
      },
      "department": {
        "type": "keyword"
      }
    }
  }
}

response = client.indices.create(
  index = "employees",
  body =   {
    "mappings": {
      "properties": {
        "name": {
          "type": "text"
        },
        "age": {
          "type": "integer"
        },
        "department": {
          "type": "keyword"
        }
      }
    }
  }
)

Example: Creating an index with aliases

The following example request creates an index named orders with two aliases, including a filtered alias:

PUT /orders
{
  "aliases": {
    "current-orders": {},
    "recent-orders": {
      "filter": {
        "range": {
          "timestamp": {
            "gte": "now-7d"
          }
        }
      }
    }
  }
}

response = client.indices.create(
  index = "orders",
  body =   {
    "aliases": {
      "current-orders": {},
      "recent-orders": {
        "filter": {
          "range": {
            "timestamp": {
              "gte": "now-7d"
            }
          }
        }
      }
    }
  }
)

Example response

OpenSearch returns the following response when the create index request is successful:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "books"
}

Response body fields

The following table lists all response body fields.

Wait for active shards

By default, the create index operation returns a response to the client only after the primary copies of each shard have been started or the request times out. You can use the response fields to understand the result of the operation.

The acknowledged field indicates whether the index was successfully created in the cluster state. The shards_acknowledged field indicates whether the target number of shard copies became active before the timeout. Both fields can be false if the operation times out, but the index creation may still succeed.

If acknowledged is false, the cluster state update timed out, but the index will likely be created soon. If shards_acknowledged is false, the target number of shard copies did not become active before the timeout, regardless of whether the cluster state was updated successfully.

You can change the default behavior of waiting only for primary shards to start by using one of the following methods:

• Set the index.write.wait_for_active_shards index setting when creating the index. This setting also affects the wait_for_active_shards behavior for subsequent write operations.
• Use the wait_for_active_shards query parameter in the create index request.

Example: Using the index.write.wait_for_active_shards setting

The following example request creates an index with the index.write.wait_for_active_shards setting, which waits for two shard copies to be active before returning. This setting also affects subsequent write operations on the index:

PUT /inventory
{
  "settings": {
    "index.write.wait_for_active_shards": "2",
    "number_of_shards": 1,
    "number_of_replicas": 1
  }
}

response = client.indices.create(
  index = "inventory",
  body =   {
    "settings": {
      "index.write.wait_for_active_shards": "2",
      "number_of_shards": 1,
      "number_of_replicas": 1
    }
  }
)

Example: Using the wait_for_active_shards query parameter

The following example request creates an index and uses the wait_for_active_shards query parameter to wait for two shard copies (primary and one replica) to be active before returning:

PUT /catalog?wait_for_active_shards=2
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  }
}

response = client.indices.create(
  index = "catalog",
  params = { "wait_for_active_shards": "2" },
  body =   {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1
    }
  }
)