Boolean queries

A Boolean (bool) query can combine several query clauses into one advanced query. The clauses are combined with Boolean logic to find matching documents returned in the results.

Use the following query clauses within a bool query:

ClauseBehavior
mustLogical and operator. The results must match all queries in this clause.
must_notLogical not operator. All matches are excluded from the results.
shouldLogical or operator. The results must match at least one of the queries. Matching more should clauses increases the document’s relevance score. You can set the minimum number of queries that must match using the minimum_should_match parameter. If a query contains a must or filter clause, the default minimum_should_match value is 0. Otherwise, the default minimum_should_match value is 1.
filterLogical and operator that is applied first to reduce your dataset before applying the queries. A query within a filter clause is a yes or no option. If a document matches the query, it is returned in the results; otherwise, it is not. The results of a filter query are generally cached to allow for a faster return. Use the filter query to filter the results based on exact matches, ranges, dates, or numbers.

A Boolean query has the following structure:

  1. GET _search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": [
  6.         {}
  7.       ],
  8.       "must_not": [
  9.         {}
  10.       ],
  11.       "should": [
  12.         {}
  13.       ],
  14.       "filter": {}
  15.     }
  16.   }
  17. }

For example, assume you have the complete works of Shakespeare indexed in an OpenSearch cluster. You want to construct a single query that meets the following requirements:

  1. The text_entry field must contain the word love and should contain either life or grace.
  2. The speaker field must not contain ROMEO.
  3. Filter these results to the play Romeo and Juliet without affecting the relevance score.

These requirements can be combined in the following query:

  1. GET shakespeare/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": [
  6.         {
  7.           "match": {
  8.             "text_entry": "love"
  9.           }
  10.         }
  11.       ],
  12.       "should": [
  13.         {
  14.           "match": {
  15.             "text_entry": "life"
  16.           }
  17.         },
  18.         {
  19.           "match": {
  20.             "text_entry": "grace"
  21.           }
  22.         }
  23.       ],
  24.       "minimum_should_match": 1,
  25.       "must_not": [
  26.         {
  27.           "match": {
  28.             "speaker": "ROMEO"
  29.           }
  30.         }
  31.       ],
  32.       "filter": {
  33.         "term": {
  34.           "play_name": "Romeo and Juliet"
  35.         }
  36.       }
  37.     }
  38.   }
  39. }

The response contains matching documents:

  1. {
  2.   "took": 12,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 4,
  6.     "successful": 4,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 11.356054,
  16.     "hits": [
  17.       {
  18.         "_index": "shakespeare",
  19.         "_id": "88020",
  20.         "_score": 11.356054,
  21.         "_source": {
  22.           "type": "line",
  23.           "line_id": 88021,
  24.           "play_name": "Romeo and Juliet",
  25.           "speech_number": 19,
  26.           "line_number": "4.5.61",
  27.           "speaker": "PARIS",
  28.           "text_entry": "O love! O life! not life, but love in death!"
  29.         }
  30.       }
  31.     ]
  32.   }
  33. }

If you want to identify which of these clauses actually caused the matching results, name each query with the _name parameter. To add the _name parameter, change the field name in the match query to an object:

  1. GET shakespeare/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": [
  6.         {
  7.           "match": {
  8.             "text_entry": {
  9.               "query": "love",
  10.               "_name": "love-must"
  11.             }
  12.           }
  13.         }
  14.       ],
  15.       "should": [
  16.         {
  17.           "match": {
  18.             "text_entry": {
  19.               "query": "life",
  20.               "_name": "life-should"
  21.             }
  22.           }
  23.         },
  24.         {
  25.           "match": {
  26.             "text_entry": {
  27.               "query": "grace",
  28.               "_name": "grace-should"
  29.             }
  30.           }
  31.         }
  32.       ],
  33.       "minimum_should_match": 1,
  34.       "must_not": [
  35.         {
  36.           "match": {
  37.             "speaker": {
  38.               "query": "ROMEO",
  39.               "_name": "ROMEO-must-not"
  40.             }
  41.           }
  42.         }
  43.       ],
  44.       "filter": {
  45.         "term": {
  46.           "play_name": "Romeo and Juliet"
  47.         }
  48.       }
  49.     }
  50.   }
  51. }

OpenSearch returns a matched_queries array that lists the queries that matched these results:

  1. "matched_queries": [
  2.   "love-must",
  3.   "life-should"
  4. ]

If you remove the queries not in this list, you will still see the exact same result. By examining which should clause matched, you can better understand the relevance score of the results.

You can also construct complex Boolean expressions by nesting bool queries. For example, use the following query to find a text_entry field that matches (love OR hate) AND (life OR grace) in the play Romeo and Juliet:

  1. GET shakespeare/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": [
  6.         {
  7.           "bool": {
  8.             "should": [
  9.               {
  10.                 "match": {
  11.                   "text_entry": "love"
  12.                 }
  13.               },
  14.               {
  15.                 "match": {
  16.                   "text": "hate"
  17.                 }
  18.               }
  19.             ]
  20.           }
  21.         },
  22.         {
  23.           "bool": {
  24.             "should": [
  25.               {
  26.                 "match": {
  27.                   "text_entry": "life"
  28.                 }
  29.               },
  30.               {
  31.                 "match": {
  32.                   "text": "grace"
  33.                 }
  34.               }
  35.             ]
  36.           }
  37.         }
  38.       ],
  39.       "filter": {
  40.         "term": {
  41.           "play_name": "Romeo and Juliet"
  42.         }
  43.       }
  44.     }
  45.   }
  46. }

The response contains matching documents:

  1. {
  2.   "took": 10,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 2,
  6.     "successful": 2,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": 1,
  12.     "max_score": 11.37006,
  13.     "hits": [
  14.       {
  15.         "_index": "shakespeare",
  16.         "_type": "doc",
  17.         "_id": "88020",
  18.         "_score": 11.37006,
  19.         "_source": {
  20.           "type": "line",
  21.           "line_id": 88021,
  22.           "play_name": "Romeo and Juliet",
  23.           "speech_number": 19,
  24.           "line_number": "4.5.61",
  25.           "speaker": "PARIS",
  26.           "text_entry": "O love! O life! not life, but love in death!"
  27.         }
  28.       }
  29.     ]
  30.   }
  31. }