Skip to content

Latest commit

 

History

History
143 lines (117 loc) · 5.33 KB

index-document.md

File metadata and controls

143 lines (117 loc) · 5.33 KB
layout title parent nav_order redirect_from
default
Index document
Document APIs
1
/opensearch/rest-api/document-apis/index-document/

Index document

Introduced 1.0 {: .label .label-purple}

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

Example

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

{% include copy-curl.html %}

Path and HTTP methods

PUT <index>/_doc/<_id>
POST <index>/_doc

PUT <index>/_create/<_id>
POST <index>/_create/<_id>
  • PUT adds or updates documents with a specified ID in the index. Used for controlled document creation or updates.
  • POST adds documents to the index with auto-generated IDs. Useful for adding new documents without specifying IDs.
  • _create is a type identifier indicating document creation should only occur if the document with the specified ID doesn't already exist.
  • <index> represents the name of the index where the document will be added.
  • <_id> represents the unique identifier of the document.

Adding a sample index and documents to use the HTTP methods

Before you can search for data, you must first add documents. To do this follow the steps:

  1. Open OpenSearch Dashboards
  2. Navigate to the hamburger menu
  3. In the Management section, choose Dev Tools
  4. Run the following commands in the Dev tools by pressing the green triangle play button to send the request.

Create a sample-index

PUT /sample-index

{% include copy-curl.html %}

Example PUT request

PUT /sample_index/_doc/1
{
  "name": "Example",
  "price": 29.99,
  "description": "To be or not to be, that is the question"
}

{% include copy-curl.html %}

Example POST request

POST /sample_index/_doc
{
  "name": "Another Example",
  "price": 19.99,
  "description": "We are such stuff as dreams are made on"
}

{% include copy-curl.html %}

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.

Parameter Type Description Required
<index> String Name of the index. Yes
<_id> String A 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_no Integer Only perform the index operation if the document has the specified sequence number. No
if_primary_term Integer Only perform the index operation if the document has the specified primary term. No
op_type Enum Specifies the type of operation to complete with the document. Valid values are create (index a document only 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
pipeline String Route the index operation to a certain pipeline. No
routing String value used to assign the index operation to a specific shard. No
refresh Enum If 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
timeout Time How long to wait for a response from the cluster. Default is 1m. No
version Integer The document's version number. No
version_type Enum Assigns 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_shards String The 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_alias Boolean Specifies 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.

{
  "Description": "This is just a sample document"
}

Response

{
  "_index": "sample-index",
  "_id": "1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Response body fields

Field Description
_index The name of the index.
_id The document's ID.
_version The document's version.
result The result of the index operation.
_shards Detailed information about the cluster's shards.
total The total number of shards.
successful The number of shards OpenSearch successfully added the document to.
failed The number of shards OpenSearch failed to add the document to.
_seq_no The sequence number assigned when the document was indexed.
_primary_term The primary term assigned when the document was indexed.