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.

Search stats groups

You can associate a search request with one or more stats groups by specifying group names in the stats field of the request body or as a query parameter. OpenSearch maintains per-group search statistics that you can retrieve using the Index Stats API.

The following example associates a search request with two groups:

POST /my-index/_search
{
  "query": {
    "match_all": {}
  },
  "stats": ["group1", "group2"]
}

To retrieve search statistics for specific groups, use the groups query parameter of the Index Stats API:

GET /my-index/_stats/search?groups=group1,group2

To return statistics for all groups, use _all:

GET /my-index/_stats/search?groups=_all

Example request

GET /movies/_search
{
  "query": {
    "match": {
      "director": "Christopher Nolan"
    }
  }
}

response = client.search(
  index = "movies",
  body =   {
    "query": {
      "match": {
        "director": "Christopher Nolan"
      }
    }
  }
)

Example response

The following example response shows the structure of a search response:

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.42727602,
    "hits": [
      {
        "_index": "movies",
        "_id": "1",
        "_score": 0.42727602,
        "_source": {
          "title": "The Dark Knight",
          "director": "Christopher Nolan",
          "year": 2008,
          "genre": "Action"
        }
      },
      {
        "_index": "movies",
        "_id": "2",
        "_score": 0.42727602,
        "_source": {
          "title": "Inception",
          "director": "Christopher Nolan",
          "year": 2010,
          "genre": "Science Fiction"
        }
      }
    ]
  }
}

Response body fields

The following table lists the top-level response body fields.

The following table lists the fields in the _shards object.

The following table lists the fields in the hits object.

The following table lists the fields in each object in the hits.hits array.

Source filtering

Each hit in the response contains a _source object holding the original JSON document. Returning the full document for every hit transfers more data than most applications need. Source filtering limits the fields that OpenSearch returns in _source.

The following table lists the accepted values for the _source request body parameter.

To filter the source in the request URL instead of the request body, use the _source, _source_includes, and _source_excludes query parameters.

For examples and limitations, see Using source filtering.

Track total hits

Counting matching documents exactly requires visiting every match, which is expensive for queries that match many documents. The track_total_hits parameter limits how many matches OpenSearch counts. Specify it either as a query parameter or in the request body.

By default, OpenSearch counts matches accurately up to 10000. When more documents match, hits.total.value reports 10000 and hits.total.relation is gte, indicating that the query matched at least that many documents.

The following table lists the accepted values for track_total_hits.

Counting every match slows down searches that match many documents. Increase the threshold only when your application requires an exact count.

Example: Default hit counting

The following example searches a logs index containing 10,500 documents without specifying track_total_hits:

GET /logs/_search
{
  "size": 0,
  "query": {
    "match_all": {}
  }
}

Because relation is gte, the index contains at least 10,000 matching documents:

{
  "hits": {
    "total": {
      "value": 10000,
      "relation": "gte"
    },
    "max_score": null,
    "hits": []
  }
}

Example: Counting every matching document

To count every match, set track_total_hits to true:

GET /logs/_search
{
  "size": 0,
  "track_total_hits": true,
  "query": {
    "match_all": {}
  }
}

Because relation is eq, value is the exact number of matching documents:

{
  "hits": {
    "total": {
      "value": 10500,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  }
}

The ext object

Introduced 2.10

Plugin authors can add an ext object to both search requests and search responses. The ext object contains plugin-specific fields that allow plugins to pass additional parameters in requests or return additional information in responses.

Using ext in search responses

Plugins can add an ext object to the search response to include 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"
    }
  }
}

Using ext in search requests

Plugins can also accept an ext object in search requests to provide plugin-specific parameters. The structure and content of the ext object in requests depends on the plugin implementation. Consult your plugin’s documentation for the specific fields supported in the request ext object.

The following example shows a search request that includes an ext object. The exact fields within ext depend on which plugins are installed and what parameters they accept:

POST /my-index/_search
{
  "query": {
    "match": {
      "field": "value"
    }
  },
  "ext": {
    "my_plugin": {
      "custom_parameter": "value"
    }
  }
}

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: indices:data/read/search.