Boolean query

Boolean query

A query that matches documents matching boolean combinations of other queries. The bool query maps to Lucene BooleanQuery. It is built using one or more boolean clauses, each clause with a typed occurrence. The occurrence types are:

OccurDescription

must

The clause (query) must appear in matching documents and will contribute to the score.

filter

The clause (query) must appear in matching documents. However unlike must the score of the query will be ignored. Filter clauses are executed in filter context, meaning that scoring is ignored and clauses are considered for caching.

should

The clause (query) should appear in the matching document.

must_not

The clause (query) must not appear in the matching documents. Clauses are executed in filter context meaning that scoring is ignored and clauses are considered for caching. Because scoring is ignored, a score of 0 for all documents is returned.

The bool query takes a more-matches-is-better approach, so the score from each matching must or should clause will be added together to provide the final _score for each document.

  1. resp = client.search(
  2.     query={
  3.         "bool": {
  4.             "must": {
  5.                 "term": {
  6.                     "user.id": "kimchy"
  7.                 }
  8.             },
  9.             "filter": {
  10.                 "term": {
  11.                     "tags": "production"
  12.                 }
  13.             },
  14.             "must_not": {
  15.                 "range": {
  16.                     "age": {
  17.                         "gte": 10,
  18.                         "lte": 20
  19.                     }
  20.                 }
  21.             },
  22.             "should": [
  23.                 {
  24.                     "term": {
  25.                         "tags": "env1"
  26.                     }
  27.                 },
  28.                 {
  29.                     "term": {
  30.                         "tags": "deployed"
  31.                     }
  32.                 }
  33.             ],
  34.             "minimum_should_match": 1,
  35.             "boost": 1
  36.         }
  37.     },
  38. )
  39. print(resp)
  1. response = client.search(
  2.   body: {
  3.     query: {
  4.       bool: {
  5.         must: {
  6.           term: {
  7.             'user.id' => 'kimchy'
  8.           }
  9.         },
  10.         filter: {
  11.           term: {
  12.             tags: 'production'
  13.           }
  14.         },
  15.         must_not: {
  16.           range: {
  17.             age: {
  18.               gte: 10,
  19.               lte: 20
  20.             }
  21.           }
  22.         },
  23.         should: [
  24.           {
  25.             term: {
  26.               tags: 'env1'
  27.             }
  28.           },
  29.           {
  30.             term: {
  31.               tags: 'deployed'
  32.             }
  33.           }
  34.         ],
  35.         minimum_should_match: 1,
  36.         boost: 1
  37.       }
  38.     }
  39.   }
  40. )
  41. puts response
  1. const response = await client.search({
  2.   query: {
  3.     bool: {
  4.       must: {
  5.         term: {
  6.           "user.id": "kimchy",
  7.         },
  8.       },
  9.       filter: {
  10.         term: {
  11.           tags: "production",
  12.         },
  13.       },
  14.       must_not: {
  15.         range: {
  16.           age: {
  17.             gte: 10,
  18.             lte: 20,
  19.           },
  20.         },
  21.       },
  22.       should: [
  23.         {
  24.           term: {
  25.             tags: "env1",
  26.           },
  27.         },
  28.         {
  29.           term: {
  30.             tags: "deployed",
  31.           },
  32.         },
  33.       ],
  34.       minimum_should_match: 1,
  35.       boost: 1,
  36.     },
  37.   },
  38. });
  39. console.log(response);
  1. POST _search
  2. {
  3.   "query": {
  4.     "bool" : {
  5.       "must" : {
  6.         "term" : { "user.id" : "kimchy" }
  7.       },
  8.       "filter": {
  9.         "term" : { "tags" : "production" }
  10.       },
  11.       "must_not" : {
  12.         "range" : {
  13.           "age" : { "gte" : 10, "lte" : 20 }
  14.         }
  15.       },
  16.       "should" : [
  17.         { "term" : { "tags" : "env1" } },
  18.         { "term" : { "tags" : "deployed" } }
  19.       ],
  20.       "minimum_should_match" : 1,
  21.       "boost" : 1.0
  22.     }
  23.   }
  24. }

Using minimum_should_match

You can use the minimum_should_match parameter to specify the number or percentage of should clauses returned documents must match.

If the bool query includes at least one should clause and no must or filter clauses, the default value is 1. Otherwise, the default value is 0.

For other valid values, see the minimum_should_match parameter.

Scoring with bool.filter

Queries specified under the filter element have no effect on scoring — scores are returned as 0. Scores are only affected by the query that has been specified. For instance, all three of the following queries return all documents where the status field contains the term active.

This first query assigns a score of 0 to all documents, as no scoring query has been specified:

  1. $params = [
  2.     'body' => [
  3.         'query' => [
  4.             'bool' => [
  5.                 'filter' => [
  6.                     'term' => [
  7.                         'status' => 'active',
  8.                     ],
  9.                 ],
  10.             ],
  11.         ],
  12.     ],
  13. ];
  14. $response = $client->search($params);
  1. resp = client.search(
  2.     query={
  3.         "bool": {
  4.             "filter": {
  5.                 "term": {
  6.                     "status": "active"
  7.                 }
  8.             }
  9.         }
  10.     },
  11. )
  12. print(resp)
  1. response = client.search(
  2.   body: {
  3.     query: {
  4.       bool: {
  5.         filter: {
  6.           term: {
  7.             status: 'active'
  8.           }
  9.         }
  10.       }
  11.     }
  12.   }
  13. )
  14. puts response
  1. res, err := es.Search(
  2.     es.Search.WithBody(strings.NewReader(`{
  3.       "query": {
  4.         "bool": {
  5.           "filter": {
  6.             "term": {
  7.               "status": "active"
  8.             }
  9.           }
  10.         }
  11.       }
  12.     }`)),
  13.     es.Search.WithPretty(),
  14. )
  15. fmt.Println(res, err)
  1. const response = await client.search({
  2.   query: {
  3.     bool: {
  4.       filter: {
  5.         term: {
  6.           status: "active",
  7.         },
  8.       },
  9.     },
  10.   },
  11. });
  12. console.log(response);
  1. GET _search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "filter": {
  6.         "term": {
  7.           "status": "active"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }

This bool query has a match_all query, which assigns a score of 1.0 to all documents.

  1. $params = [
  2.     'body' => [
  3.         'query' => [
  4.             'bool' => [
  5.                 'must' => [
  6.                     'match_all' => [
  7.                     ],
  8.                 ],
  9.                 'filter' => [
  10.                     'term' => [
  11.                         'status' => 'active',
  12.                     ],
  13.                 ],
  14.             ],
  15.         ],
  16.     ],
  17. ];
  18. $response = $client->search($params);
  1. resp = client.search(
  2.     query={
  3.         "bool": {
  4.             "must": {
  5.                 "match_all": {}
  6.             },
  7.             "filter": {
  8.                 "term": {
  9.                     "status": "active"
  10.                 }
  11.             }
  12.         }
  13.     },
  14. )
  15. print(resp)
  1. response = client.search(
  2.   body: {
  3.     query: {
  4.       bool: {
  5.         must: {
  6.           match_all: {}
  7.         },
  8.         filter: {
  9.           term: {
  10.             status: 'active'
  11.           }
  12.         }
  13.       }
  14.     }
  15.   }
  16. )
  17. puts response
  1. res, err := es.Search(
  2.     es.Search.WithBody(strings.NewReader(`{
  3.       "query": {
  4.         "bool": {
  5.           "must": {
  6.             "match_all": {}
  7.           },
  8.           "filter": {
  9.             "term": {
  10.               "status": "active"
  11.             }
  12.           }
  13.         }
  14.       }
  15.     }`)),
  16.     es.Search.WithPretty(),
  17. )
  18. fmt.Println(res, err)
  1. const response = await client.search({
  2.   query: {
  3.     bool: {
  4.       must: {
  5.         match_all: {},
  6.       },
  7.       filter: {
  8.         term: {
  9.           status: "active",
  10.         },
  11.       },
  12.     },
  13.   },
  14. });
  15. console.log(response);
  1. GET _search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "must": {
  6.         "match_all": {}
  7.       },
  8.       "filter": {
  9.         "term": {
  10.           "status": "active"
  11.         }
  12.       }
  13.     }
  14.   }
  15. }

This constant_score query behaves in exactly the same way as the second example above. The constant_score query assigns a score of 1.0 to all documents matched by the filter.

  1. $params = [
  2.     'body' => [
  3.         'query' => [
  4.             'constant_score' => [
  5.                 'filter' => [
  6.                     'term' => [
  7.                         'status' => 'active',
  8.                     ],
  9.                 ],
  10.             ],
  11.         ],
  12.     ],
  13. ];
  14. $response = $client->search($params);
  1. resp = client.search(
  2.     query={
  3.         "constant_score": {
  4.             "filter": {
  5.                 "term": {
  6.                     "status": "active"
  7.                 }
  8.             }
  9.         }
  10.     },
  11. )
  12. print(resp)
  1. response = client.search(
  2.   body: {
  3.     query: {
  4.       constant_score: {
  5.         filter: {
  6.           term: {
  7.             status: 'active'
  8.           }
  9.         }
  10.       }
  11.     }
  12.   }
  13. )
  14. puts response
  1. res, err := es.Search(
  2.     es.Search.WithBody(strings.NewReader(`{
  3.       "query": {
  4.         "constant_score": {
  5.           "filter": {
  6.             "term": {
  7.               "status": "active"
  8.             }
  9.           }
  10.         }
  11.       }
  12.     }`)),
  13.     es.Search.WithPretty(),
  14. )
  15. fmt.Println(res, err)
  1. const response = await client.search({
  2.   query: {
  3.     constant_score: {
  4.       filter: {
  5.         term: {
  6.           status: "active",
  7.         },
  8.       },
  9.     },
  10.   },
  11. });
  12. console.log(response);
  1. GET _search
  2. {
  3.   "query": {
  4.     "constant_score": {
  5.       "filter": {
  6.         "term": {
  7.           "status": "active"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }

Named queries

Each query accepts a _name in its top level definition. You can use named queries to track which queries matched returned documents. If named queries are used, the response includes a matched_queries property for each hit.

Supplying duplicate _name values in the same request results in undefined behavior. Queries with duplicate names may overwrite each other. Query names are assumed to be unique within a single request.

  1. resp = client.search(
  2.     query={
  3.         "bool": {
  4.             "should": [
  5.                 {
  6.                     "match": {
  7.                         "name.first": {
  8.                             "query": "shay",
  9.                             "_name": "first"
  10.                         }
  11.                     }
  12.                 },
  13.                 {
  14.                     "match": {
  15.                         "name.last": {
  16.                             "query": "banon",
  17.                             "_name": "last"
  18.                         }
  19.                     }
  20.                 }
  21.             ],
  22.             "filter": {
  23.                 "terms": {
  24.                     "name.last": [
  25.                         "banon",
  26.                         "kimchy"
  27.                     ],
  28.                     "_name": "test"
  29.                 }
  30.             }
  31.         }
  32.     },
  33. )
  34. print(resp)
  1. response = client.search(
  2.   body: {
  3.     query: {
  4.       bool: {
  5.         should: [
  6.           {
  7.             match: {
  8.               'name.first' => {
  9.                 query: 'shay',
  10.                 _name: 'first'
  11.               }
  12.             }
  13.           },
  14.           {
  15.             match: {
  16.               'name.last' => {
  17.                 query: 'banon',
  18.                 _name: 'last'
  19.               }
  20.             }
  21.           }
  22.         ],
  23.         filter: {
  24.           terms: {
  25.             'name.last' => [
  26.               'banon',
  27.               'kimchy'
  28.             ],
  29.             _name: 'test'
  30.           }
  31.         }
  32.       }
  33.     }
  34.   }
  35. )
  36. puts response
  1. const response = await client.search({
  2.   query: {
  3.     bool: {
  4.       should: [
  5.         {
  6.           match: {
  7.             "name.first": {
  8.               query: "shay",
  9.               _name: "first",
  10.             },
  11.           },
  12.         },
  13.         {
  14.           match: {
  15.             "name.last": {
  16.               query: "banon",
  17.               _name: "last",
  18.             },
  19.           },
  20.         },
  21.       ],
  22.       filter: {
  23.         terms: {
  24.           "name.last": ["banon", "kimchy"],
  25.           _name: "test",
  26.         },
  27.       },
  28.     },
  29.   },
  30. });
  31. console.log(response);
  1. GET /_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "should": [
  6.         { "match": { "name.first": { "query": "shay", "_name": "first" } } },
  7.         { "match": { "name.last": { "query": "banon", "_name": "last" } } }
  8.       ],
  9.       "filter": {
  10.         "terms": {
  11.           "name.last": [ "banon", "kimchy" ],
  12.           "_name": "test"
  13.         }
  14.       }
  15.     }
  16.   }
  17. }

The request parameter named include_named_queries_score controls whether scores associated with the matched queries are returned or not. When set, the response includes a matched_queries map that contains the name of the query that matched as a key and its associated score as the value.

Note that the score might not have contributed to the final score of the document, for instance named queries that appear in a filter or must_not contexts, or inside a clause that ignores or modifies the score like constant_score or function_score_query.

  1. resp = client.search(
  2.     include_named_queries_score=True,
  3.     query={
  4.         "bool": {
  5.             "should": [
  6.                 {
  7.                     "match": {
  8.                         "name.first": {
  9.                             "query": "shay",
  10.                             "_name": "first"
  11.                         }
  12.                     }
  13.                 },
  14.                 {
  15.                     "match": {
  16.                         "name.last": {
  17.                             "query": "banon",
  18.                             "_name": "last"
  19.                         }
  20.                     }
  21.                 }
  22.             ],
  23.             "filter": {
  24.                 "terms": {
  25.                     "name.last": [
  26.                         "banon",
  27.                         "kimchy"
  28.                     ],
  29.                     "_name": "test"
  30.                 }
  31.             }
  32.         }
  33.     },
  34. )
  35. print(resp)
  1. response = client.search(
  2.   include_named_queries_score: true,
  3.   body: {
  4.     query: {
  5.       bool: {
  6.         should: [
  7.           {
  8.             match: {
  9.               'name.first' => {
  10.                 query: 'shay',
  11.                 _name: 'first'
  12.               }
  13.             }
  14.           },
  15.           {
  16.             match: {
  17.               'name.last' => {
  18.                 query: 'banon',
  19.                 _name: 'last'
  20.               }
  21.             }
  22.           }
  23.         ],
  24.         filter: {
  25.           terms: {
  26.             'name.last' => [
  27.               'banon',
  28.               'kimchy'
  29.             ],
  30.             _name: 'test'
  31.           }
  32.         }
  33.       }
  34.     }
  35.   }
  36. )
  37. puts response
  1. const response = await client.search({
  2.   include_named_queries_score: "true",
  3.   query: {
  4.     bool: {
  5.       should: [
  6.         {
  7.           match: {
  8.             "name.first": {
  9.               query: "shay",
  10.               _name: "first",
  11.             },
  12.           },
  13.         },
  14.         {
  15.           match: {
  16.             "name.last": {
  17.               query: "banon",
  18.               _name: "last",
  19.             },
  20.           },
  21.         },
  22.       ],
  23.       filter: {
  24.         terms: {
  25.           "name.last": ["banon", "kimchy"],
  26.           _name: "test",
  27.         },
  28.       },
  29.     },
  30.   },
  31. });
  32. console.log(response);
  1. GET /_search?include_named_queries_score
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "should": [
  6.         { "match": { "name.first": { "query": "shay", "_name": "first" } } },
  7.         { "match": { "name.last": { "query": "banon", "_name": "last" } } }
  8.       ],
  9.       "filter": {
  10.         "terms": {
  11.           "name.last": [ "banon", "kimchy" ],
  12.           "_name": "test"
  13.         }
  14.       }
  15.     }
  16.   }
  17. }

This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead. For example, named queries in combination with a top_hits aggregation on many buckets may lead to longer response times.