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

Search

Introduced 1.0

The Search API operation lets you execute a search request to search your cluster for data.

Example

GET /movies/_search
{
  "query": {
    "match": {
      "text_entry": "I am the night"
    }
  }
}

copy

Path and HTTP Methods

GET /<target-index>/_search
GET /_search
POST /<target-index>/_search
POST /_search

URL Parameters

All URL parameters are optional.

The preference query parameter

The preference query parameter specifies the shards or nodes on which OpenSearch should perform the search. The following are valid values:

• _primary: Perform the search only on primary shards.
• _replica: Perform the search only on replica shards.
• _primary_first: Perform the search on primary shards but fail over to other available shards if primary shards are not available.
• _replica_first: Perform the search on replica shards but fail over to other available shards if replica shards are not available.
• _local: If possible, perform the search on the local node’s shards.
• _prefer_nodes:<node-id-1>,<node-id-2>: If possible, perform the search on the specified nodes. Use a comma-separated list to specify multiple nodes.
• _shards:<shard-id-1>,<shard-id-2>: Perform the search only on the specified shards. Use a comma-separated list to specify multiple shards. When combined with other preferences, the _shards preference must be listed first. For example, _shards:1,2|_replica.
• _only_nodes:<node-id-1>,<node-id-2>: Perform the search only on the specified nodes. Use a comma-separated list to specify multiple nodes.
• <string>: Specifies a custom string to use for the search. The string cannot start with an underscore character (_). Searches with the same custom string are routed to the same shards.

Request body

All fields are optional.

Response body

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "superheroes",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "superheroes": [
            {
              "Hero name": "Superman",
              "Real identity": "Clark Kent",
              "Age": 28
            },
            {
              "Hero name": "Batman",
              "Real identity": "Bruce Wayne",
              "Age": 26
            },
            {
              "Hero name": "Flash",
              "Real identity": "Barry Allen",
              "Age": 28
            },
            {
              "Hero name": "Robin",
              "Real identity": "Dick Grayson",
              "Age": 15
            }
          ]
        }
      }
    ]
  }
}

The ext object

Starting with OpenSearch 2.10, plugin authors can add an ext object to the search response. The purpose of the ext object is to contain plugin-specific response fields. For example, in conversational search, the result of Retrieval Augmented Generation (RAG) is a single “hit” (answer). Plugin authors can include this answer in the search response as part of the ext object so that it is separate from the search hits. In the following example response, the RAG result is in the ext.retrieval_augmented_generation.answer field:

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 3,
    "successful": 3,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 110,
      "relation": "eq"
    },
    "max_score": 0.55129033,
    "hits": [
      {
       "_index": "...",
        "_id": "...",
        "_score": 0.55129033,
        "_source": {
          "text": "...",
          "title": "..."
        }
      },
      {
      ...
      }
      ...
      {
      ...
      }
    ],
  }, // end of hits
  "ext": {
    "retrieval_augmented_generation": { // a search response processor
      "answer": "RAG answer"
    }
  }
}