You're viewing version 3.8 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Managing indexes

An index is the basic unit of data storage in OpenSearch: a collection of JSON documents, each identified by a unique ID, distributed across one or more shards. This section covers what you do with an index after your data is in it—creating and deleting indexes, grouping them behind aliases and data streams, automating their lifecycle, and tuning how they store and retrieve data.

If you are new to OpenSearch, start with Add and manage your data, which walks through creating an index, adding documents to it, and reading them back.

Indexing documents

OpenSearch creates an index automatically the first time you add a document to a name that does not yet exist, and generates a document ID if you do not supply one. The following request creates the movies index and indexes one document into it:

POST movies/_doc
{ "title": "Spirited Away" }

Specify the ID yourself when you expect to update or retrieve the document later. Sending the following request repeatedly leaves a single document in the index and increments its _version field, whereas repeating the preceding request creates a new document each time:

PUT movies/_doc/1
{ "title": "Spirited Away" }

A document ID must be 512 bytes or smaller.

To index many documents in one request, use the Bulk API. Each action is described by a metadata line followed by the document itself, and every line must end with a newline character (\n), including the last one:

POST _bulk
{ "index": { "_index": "movies", "_id": "2" } }
{ "title": "My Neighbor Totoro" }
{ "index": { "_index": "movies", "_id": "3" } }
{ "title": "Princess Mononoke" }

Bulk requests give better throughput than individual requests for large numbers of documents. If one action in a bulk request fails, OpenSearch runs the remaining actions and reports the outcome of each one in the items array of the response, in the order in which you specified the actions.

For the rest of the document operations, including retrieving, updating, and deleting documents, see Document APIs.

Naming restrictions for indexes

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 <

Names beginning with a period (.) are reserved for OpenSearch system indexes.

In this section

Each page in this section describes what an operation does and how to run it using the OpenSearch API, followed by the equivalent steps in OpenSearch Dashboards.

Related documentation

• Index APIs
• Index Management in OpenSearch Dashboards
• Ingest your data into OpenSearch
• Index settings