Search

Introduced 1.0

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

Example

  1. GET /movies/_search
  2. {
  3. "query": {
  4. "match": {
  5. "text_entry": "I am the night"
  6. }
  7. }
  8. }

Path and HTTP Methods

  1. GET /<target-index>/_search
  2. GET /_search
  3. POST /<target-index>/_search
  4. POST /_search

URL Parameters

All URL parameters are optional.

ParameterTypeDescription
allow_no_indicesBooleanWhether to ignore wildcards that don’t match any indexes. Default is true.
allow_partial_search_resultsBooleanWhether to return partial results if the request runs into an error or times out. Default is true.
analyzerStringAnalyzer to use in the query string.
analyze_wildcardBooleanWhether the update operation should include wildcard and prefix queries in the analysis. Default is false.
batched_reduce_sizeIntegerHow many shard results to reduce on a node. Default is 512.
cancel_after_time_intervalTimeThe time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval cluster setting. Default is -1.
css_minimize_roundtripsBooleanWhether to minimize roundtrips between a node and remote clusters. Default is true.
default_operatorStringIndicates whether the default operator for a string query should be AND or OR. Default is OR.
dfStringThe default field in case a field prefix is not provided in the query string.
docvalue_fieldsStringThe fields that OpenSearch should return using their docvalue forms.
expand_wildcardsStringSpecifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open.
explainBooleanWhether to return details about how OpenSearch computed the document’s score. Default is false.
fromIntegerThe starting index to search from. Default is 0.
ignore_throttledBooleanWhether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is true.
ignore_unavailableBooleanSpecifies whether to include missing or closed indexes in the response. Default is false.
lenientBooleanSpecifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
max_concurrent_shard_requestsIntegerHow many concurrent shard requests this request should execute on each node. Default is 5.
pre_filter_shard_sizeIntegerA prefilter size threshold that triggers a prefilter operation if the request exceeds the threshold. Default is 128 shards.
preferenceStringSpecifies which shard or node OpenSearch should perform the count operation on.
qStringLucene query string’s query.
request_cacheBooleanSpecifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings.
rest_total_hits_as_intBooleanWhether to return hits.total as an integer. Returns an object otherwise. Default is false.
routingStringValue used to route the update by query operation to a specific shard.
scrollTimeHow long to keep the search context open.
search_typeStringWhether OpenSearch should use global term and document frequencies when calculating revelance scores. Valid choices are query_then_fetch and dfs_query_then_fetch. query_then_fetch scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. dfs_query_then_fetch scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is query_then_fetch.
seq_no_primary_termBooleanWhether to return sequence number and primary term of the last operation of each document hit.
sizeIntegerHow many results to include in the response.
sortListA comma-separated list of <field> : <direction> pairs to sort by.
_sourceStringWhether to include the _source field in the response.
_source_excludesListA comma-separated list of source fields to exclude from the response.
_source_includesListA comma-separated list of source fields to include in the response.
statsStringValue to associate with the request for additional logging.
stored_fieldsBooleanWhether the get operation should retrieve fields stored in the index. Default is false.
suggest_fieldStringFields OpenSearch can use to look for similar terms.
suggest_modeStringThe mode to use when searching. Available options are always (use suggestions based on the provided terms), popular (use suggestions that have more occurrences), and missing (use suggestions for terms not in the index).
suggest_sizeIntegerHow many suggestions to return.
suggest_textStringThe source that suggestions should be based off of.
terminate_afterIntegerThe maximum number of documents OpenSearch should process before terminating the request. Default is 0.
timeoutTimeHow long the operation should wait for a response from active shards. Default is 1m.
track_scoresBooleanWhether to return document scores. Default is false.
track_total_hitsBoolean or IntegerWhether to return how many documents matched the query.
typed_keysBooleanWhether returned aggregations and suggested terms should include their types in the response. Default is true.
versionBooleanWhether to include the document version as a match.

Request body

All fields are optional.

FieldTypeDescription
docvalue_fieldsArray of objectsThe fields that OpenSearch should return using their docvalue forms. Specify a format to return results in a certain format, such as date and time.
fieldsArrayThe fields to search for in the request. Specify a format to return results in a certain format, such as date and time.
explainStringWhether to return details about how OpenSearch computed the document’s score. Default is false.
fromIntegerThe starting index to search from. Default is 0.
indices_boostArray of objectsScores used to boost specified indices’ scores. Specify in the format of <index> : <boost-multiplier>
min_scoreIntegerSpecify a score threshold to return only documents above the threshold.
queryObjectThe DSL query to use in the request.
seq_no_primary_termBooleanWhether to return sequence number and primary term of the last operation of each document hit.
sizeIntegerHow many results to return. Default is 10.
_source Whether to include the _source field in the response.
statsStringValue to associate with the request for additional logging.
terminate_afterIntegerThe maximum number of documents OpenSearch should process before terminating the request. Default is 0.
timeoutTimeHow long to wait for a response. Default is no timeout.
versionBooleanWhether to include the document version in the response.

Response body

  1. {
  2. "took": 3,
  3. "timed_out": false,
  4. "_shards": {
  5. "total": 1,
  6. "successful": 1,
  7. "skipped": 0,
  8. "failed": 0
  9. },
  10. "hits": {
  11. "total": {
  12. "value": 1,
  13. "relation": "eq"
  14. },
  15. "max_score": 1.0,
  16. "hits": [
  17. {
  18. "_index": "superheroes",
  19. "_id": "1",
  20. "_score": 1.0,
  21. "_source": {
  22. "superheroes": [
  23. {
  24. "Hero name": "Superman",
  25. "Real identity": "Clark Kent",
  26. "Age": 28
  27. },
  28. {
  29. "Hero name": "Batman",
  30. "Real identity": "Bruce Wayne",
  31. "Age": 26
  32. },
  33. {
  34. "Hero name": "Flash",
  35. "Real identity": "Barry Allen",
  36. "Age": 28
  37. },
  38. {
  39. "Hero name": "Robin",
  40. "Real identity": "Dick Grayson",
  41. "Age": 15
  42. }
  43. ]
  44. }
  45. }
  46. ]
  47. }
  48. }