Search API

Introduced 1.0

The search API operation lets you search your cluster for data.

Endpoints

GET /<index>/_search
GET /_search

POST /<index>/_search
POST /_search

Query parameters

All parameters are optional.

Many of the parameters apply only when you use the URL q= parameter or a query_string query. See Query string query for more information.

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.

Example request

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

response = client.search(
  index = "movies",
  body =   {
    "query": {
      "match": {
        "text_entry": "I am the night"
      }
    }
  }
)

Response body fields

{
  "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 ext object contains 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"
    }
  }
}