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:

The must and should clauses function as logical AND, OR operators, contributing to the scoring of results. However, these results will not be cached for faster retrieval. In contrast, the filter and must_not clauses are used to include or exclude results without impacting the score, unless used within a constant_score query.

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.

 POST _search {
  "query": {
    "bool" : {
      "must" : {
        "term" : { "user.id" : "kimchy" }
      },
      "filter": {
        "term" : { "tags" : "production" }
      },
      "must_not" : {
        "range" : {
          "age" : { "gte" : 10, "lte" : 20 }
        }
      },
      "should" : [
        { "term" : { "tags" : "env1" } },
        { "term" : { "tags" : "deployed" } }
      ],
      "minimum_should_match" : 1,
      "boost" : 1.0
    }
  }
}

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.

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:

 GET _search {
  "query": {
    "bool": {
      "filter": {
        "term": {
          "status": "active"
        }
      }
    }
  }
}

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

 GET _search {
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "term": {
          "status": "active"
        }
      }
    }
  }
}

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.

 GET _search {
  "query": {
    "constant_score": {
      "filter": {
        "term": {
          "status": "active"
        }
      }
    }
  }
}

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.

 GET /_search {
  "query": {
    "bool": {
      "should": [
        { "match": { "name.first": { "query": "shay", "_name": "first" } } },
        { "match": { "name.last": { "query": "banon", "_name": "last" } } }
      ],
      "filter": {
        "terms": {
          "name.last": [ "banon", "kimchy" ],
          "_name": "test"
        }
      }
    }
  }
}

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.

 GET /_search?include_named_queries_score {
  "query": {
    "bool": {
      "should": [
        { "match": { "name.first": { "query": "shay", "_name": "first" } } },
        { "match": { "name.last": { "query": "banon", "_name": "last" } } }
      ],
      "filter": {
        "terms": {
          "name.last": [ "banon", "kimchy" ],
          "_name": "test"
        }
      }
    }
  }
}