Index document

Introduced 1.0

Before you can search for data, you must first add documents. This operation adds a single document to your index.

Example

  1. PUT sample-index/_doc/1
  2. {
  3. "Description": "To be or not to be, that is the question."
  4. }

copy

Path and HTTP methods

  1. PUT <index>/_doc/<_id>
  2. POST <index>/_doc
  3. PUT <index>/_create/<_id>
  4. POST <index>/_create/<_id>

URL parameters

In your request, you must specify the index you want to add your document to. If the index doesn’t already exist, OpenSearch automatically creates the index and adds in your document. All other URL parameters are optional.

ParameterTypeDescriptionRequired
<index>StringName of the index.Yes
<_id>StringA unique identifier to attach to the document. To automatically generate an ID, use POST <target>/doc in your request instead of PUT.No
if_seq_noIntegerOnly perform the index operation if the document has the specified sequence number.No
if_primary_termIntegerOnly perform the index operation if the document has the specified primary term.No
op_typeEnumSpecifies the type of operation to complete with the document. Valid values are create (create the index if it doesn’t exist) and index. If a document ID is included in the request, then the default is index. Otherwise, the default is create.No
pipelineStringRoute the index operation to a certain pipeline.No
routingStringvalue used to assign the index operation to a specific shard.No
refreshEnumIf true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are true, false, and wait_for, which tells OpenSearch to wait for a refresh before executing the operation. Default is false.No
timeoutTimeHow long to wait for a response from the cluster. Default is 1m.No
versionIntegerThe document’s version number.No
version_typeEnumAssigns a specific type to the document. Valid options are external (retrieve the document if the specified version number is greater than the document’s current version) and external_gte (retrieve the document if the specified version number is greater than or equal to the document’s current version). For example, to index version 3 of a document, use /_doc/1?version=3&version_type=external.No
wait_for_active_shardsStringThe number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to all or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed.No
require_aliasBooleanSpecifies whether the target index must be an index alias. Default is false.No

Request body

Your request body must contain the information you want to index.

  1. {
  2. "Description": "This is just a sample document"
  3. }

Response

  1. {
  2. "_index": "sample-index",
  3. "_id": "1",
  4. "_version": 1,
  5. "result": "created",
  6. "_shards": {
  7. "total": 2,
  8. "successful": 1,
  9. "failed": 0
  10. },
  11. "_seq_no": 0,
  12. "_primary_term": 1
  13. }

Response body fields

FieldDescription
_indexThe name of the index.
_idThe document’s ID.
_versionThe document’s version.
resultThe result of the index operation.
_shardsDetailed information about the cluster’s shards.
totalThe total number of shards.
successfulThe number of shards OpenSearch successfully added the document to.
failedThe number of shards OpenSearch failed to added the document to.
_seq_noThe sequence number assigned when the document was indexed.
_primary_termThe primary term assigned when the document was indexed.