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.

ID metadata field

Each document in OpenSearch has a unique _id field. This field is indexed, allowing you to retrieve documents using the GET API or the ids query.

If you do not provide an _id value, then OpenSearch automatically generates one for the document.

The following example requests create an index named test-index1 and add two documents with different _id values.

The first request adds a document with an _id of 1:

PUT test-index1/_doc/1
{
  "text": "Document with ID 1"
}

The second request adds a document with an _id of 2 and refreshes the index so that both documents are immediately searchable:

PUT test-index1/_doc/2?refresh=true
{
  "text": "Document with ID 2"
}

You can then query the documents using the _id field, as shown in the following example request:

GET test-index1/_search
{
  "query": {
    "terms": {
      "_id": ["1", "2"]
    }
  }
}

The response returns both documents with _id values of 1 and 2:

{
  "took": 10,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "test-index1",
        "_id": "1",
        "_score": 1,
        "_source": {
          "text": "Document with ID 1"
        }
      },
      {
        "_index": "test-index1",
        "_id": "2",
        "_score": 1,
        "_source": {
          "text": "Document with ID 2"
        }
      }
    ]
  }

Limitations of the _id field

While the _id field can be used in various queries, it is restricted from use in aggregations, sorting, and scripting. If you need to sort or aggregate on the _id field, it is recommended to duplicate the _id content into another field with doc_values enabled. Refer to IDs query for an example.