Query DSL

While you can use HTTP request parameters to perform simple searches, you can also use the OpenSearch query domain-specific language (DSL), which provides a wider range of search options. The query DSL uses the HTTP request body, so you can more easily customize your queries to get the exact results that you want.

For example, the following request performs a simple search to search for a speaker field that has a value of queen.

Sample request

  1. GET _search?q=speaker:queen

Sample response

  1. {
  2.   "took": 87,
  3.   "timed_out": false,
  4.   "_shards": {
  5.   "total": 68,
  6.   "successful": 68,
  7.   "skipped": 0,
  8.   "failed": 0
  9.   },
  10.   "hits": {
  11.   "total": {
  12.     "value": 4080,
  13.     "relation": "eq"
  14.   },
  15.   "max_score": 4.4368687,
  16.   "hits": [
  17.     {
  18.     "_index": "new_shakespeare",
  19.     "_id": "28559",
  20.     "_score": 4.4368687,
  21.     "_source": {
  22.       "type": "line",
  23.       "line_id": 28560,
  24.       "play_name": "Cymbeline",
  25.       "speech_number": 20,
  26.       "line_number": "1.1.81",
  27.       "speaker": "QUEEN",
  28.       "text_entry": "No, be assured you shall not find me, daughter,"
  29.     }
  30.     }

With query DSL, however, you can include an HTTP request body to look for results more tailored to your needs. The following example shows how to search for speaker and text_entry fields that have a value of QUEEN.

Sample request

  1. GET _search
  2. {
  3.   "query": {
  4.   "multi_match": {
  5.     "query": "QUEEN",
  6.     "fields": ["speaker", "text_entry"]
  7.     }
  8.   }
  9. }

Sample Response

  1. {
  2.   "took": 39,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 68,
  6.     "successful": 68,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 5837,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 7.8623476,
  16.     "hits": [
  17.       {
  18.         "_index": "new_shakespeare",
  19.         "_id": "100763",
  20.         "_score": 7.8623476,
  21.         "_source": {
  22.           "type": "line",
  23.           "line_id": 100764,
  24.           "play_name": "Troilus and Cressida",
  25.           "speech_number": 43,
  26.           "line_number": "3.1.68",
  27.           "speaker": "PANDARUS",
  28.           "text_entry": "Sweet queen, sweet queen! thats a sweet queen, i faith."
  29.         }
  30.       },
  31.       {
  32.         "_index": "shakespeare",
  33.         "_id": "28559",
  34.         "_score": 5.8923807,
  35.         "_source": {
  36.           "type": "line",
  37.           "line_id": 28560,
  38.           "play_name": "Cymbeline",
  39.           "speech_number": 20,
  40.           "line_number": "1.1.81",
  41.           "speaker": "QUEEN",
  42.           "text_entry": "No, be assured you shall not find me, daughter,"
  43.         }
  44.       }
  45.     ]
  46.   }
  47. }

The OpenSearch query DSL comes in three varieties: term-level queries, full-text queries, and boolean queries. You can even perform more complicated searches by using different elements from each variety to find whatever data you need.

A note on Unicode special characters in text fields

Due to word boundaries associated with Unicode special characters, the Unicode standard analyzer cannot index a text field type value as a whole value when it includes one of these special characters. As a result, a text field value that includes a special character is parsed by the standard analyzer as multiple values separated by the special character, effectively tokenizing the different elements on either side of it. This can lead to unintentional filtering of documents and potentially compromise control over their access.

The examples below illustrate values containing special characters that will be parsed improperly by the standard analyzer. In this example, the existence of the hyphen/minus sign in the value prevents the analyzer from distinguishing between the two different users for user.id and interprets them as one and the same:

  1. {
  2.   "bool": {
  3.     "must": {
  4.       "match": {
  5.         "user.id": "User-1"
  6.       }
  7.     }
  8.   }
  9. }
  1. {
  2.   "bool": {
  3.     "must": {
  4.       "match": {
  5.         "user.id": "User-2"
  6.       }
  7.     }
  8.   }
  9. }

To avoid this circumstance when using either query DSL or the REST API, you can use a custom analyzer or map the field as keyword, which performs an exact-match search. See Keyword field type for the latter option.

For a list of characters that should be avoided when field type is text, see Word Boundaries.