<commit_before>[[query-dsl-bool-query]]
=== Bool 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:

[cols="<,<",options="header",]
|=======================================================================
|Occur |Description
|`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 <<query-filter-context,filter context>>, meaning that scoring is ignored
and clauses are considered for caching.

|`should` |The clause (query) should appear in the matching document. In
a boolean query with no `must` or `filter` clauses, one or more `should` clauses
must match a document. The minimum number of should clauses to match can
be set using the
<<query-dsl-minimum-should-match,`minimum_should_match`>>
parameter.

|`must_not` |The clause (query) must not appear in the matching
documents.  Clauses are executed in <<query-filter-context,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.
|=======================================================================

[IMPORTANT]
.Bool query in filter context
========================================================================
If this query is used in a filter context and it has `should`
clauses then at least one `should` clause is required to match.
========================================================================

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.

[source,js]
--------------------------------------------------
POST _search
{
  "query": {
    "bool" : {<commit_msg>Rewrite description of `bool`'s `should` (#24342)<commit_after>[[query-dsl-bool-query]]
=== Bool 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:

[cols="<,<",options="header",]
|=======================================================================
|Occur |Description
|`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 <<query-filter-context,filter context>>, meaning that scoring is ignored
and clauses are considered for caching.

|`should` |The clause (query) should appear in the matching document. If the
`bool` query is in a <<query-filter-context,query context>> and has a `must` or
`filter` clause then a document will match the `bool` query even if none of the
`should` queries match. In this case these clauses are only used to influence
the score. If the `bool` query is a <<query-filter-context,filter context>>
or has neither `must` or `filter` then at least one of the `should` queries
must match a document for it to match the `bool` query. This behavior may be
explicitly controlled by settings the
<<query-dsl-minimum-should-match,`minimum_should_match`>> parameter.

|`must_not` |The clause (query) must not appear in the matching
documents.  Clauses are executed in <<query-filter-context,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.
|=======================================================================

[IMPORTANT]
.Bool query in filter context
========================================================================
If this query is used in a filter context and it has `should`
clauses then at least one `should` clause is required to match.
========================================================================

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.

[source,js]
--------------------------------------------------
POST _search
{
  "query": {
    "bool" : {
{'fraction_non_alphanumeric': 0.21881886293521374, 'fraction_numerical': 0.0015425297487880124, 'mean_word_length': 4.94109947643979, 'pattern_counts': {'":': 2, '<': 23, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '923745', 'n_tokens_mistral': 1125, 'n_tokens_neox': 1061, 'n_words': 549}