The Four Clauses of bool
The bool query is Elasticsearch's primary mechanism for combining multiple conditions, and it exposes four occurrence types, each an array of clauses. must clauses are required and contribute to the relevance score, functioning like a logical AND. should clauses are optional by default but boost the score when they match, and become required only when there is no must clause and minimum_should_match is unmet by zero matches. must_not clauses exclude documents entirely and, like filter, run in filter context with no scoring contribution. filter clauses are required like must but run in filter context, skipping scoring — making filter the correct home for any exact-match or range condition that shouldn't influence how documents are ranked.
Cricket analogy: must in a bool query is like a non-negotiable selection criterion such as 'must have played 50 first-class matches,' should is like a bonus factor such as 'has captaincy experience' that boosts a candidate's ranking without being mandatory, and must_not excludes anyone currently injured.
GET /jobs/_search
{
"query": {
"bool": {
"must": [
{ "match": { "description": "backend engineer" } }
],
"should": [
{ "match": { "description": "kubernetes" } },
{ "match": { "description": "golang" } }
],
"must_not": [
{ "term": { "status.keyword": "closed" } }
],
"filter": [
{ "range": { "posted_date": { "gte": "now-30d" } } }
],
"minimum_should_match": 1
}
}
}minimum_should_match and Nested bool Queries
When a bool query has should clauses but also has at least one must or filter clause, should clauses are purely optional score boosters by default — none of them need to match. The minimum_should_match parameter changes that, letting you require a specific count or percentage of should clauses to match, which is essential when should is being used to express 'match at least N of these optional criteria' rather than pure scoring. Because bool queries are themselves queries, they nest freely: a should clause can itself contain a nested bool with its own must and should, letting you express logic like '(category is electronics AND brand is Sony) OR (category is electronics AND brand is Bose)' as two nested bool blocks inside an outer should array.
Cricket analogy: minimum_should_match is like a selection panel requiring a candidate to tick at least 2 of 3 optional criteria — wicketkeeping ability, left-arm bowling, prior IPL experience — rather than treating all three as merely nice-to-have.
When a bool query has should clauses and no must/filter clause, at least one should must match by default (should acts like an implicit OR). Adding a must or filter clause turns should into purely optional scoring, unless you explicitly set minimum_should_match.
Boosting and Scoring Interplay
Because must and should both run in query context, their scores are summed to produce a document's overall bool score: a document matching two should clauses that each contribute a modest score will rank higher than one matching only the required must clause. This makes should a powerful tool for soft-ranking signals — like boosting recently published articles or documents mentioning a preferred brand — without excluding documents that lack those signals. Each clause can also carry an explicit boost parameter (e.g., { "match": { "title": { "query": "laptop", "boost": 3 } } }) to weight its contribution relative to sibling clauses, and the bool query itself can be nested inside a function_score query when boosting needs to depend on a computed value like popularity or recency rather than a static multiplier.
Cricket analogy: A should clause matching boosts a player's overall rating the way an all-rounder's batting score is added to their bowling score for a combined selection ranking, without either skill being mandatory on its own.
Nesting too many should clauses without minimum_should_match or a must/filter anchor can make queries slow and results noisy, since Elasticsearch must evaluate and score every optional branch against the entire dataset. Anchor broad should logic with a filter clause whenever possible.
- bool combines clauses via four occurrence types: must, should, must_not, filter.
- must and should run in query context and contribute to the relevance score; must_not and filter do not.
- should is optional scoring unless it's the only occurrence type present, or minimum_should_match forces a count.
- bool queries nest arbitrarily, letting you express OR-of-AND and AND-of-OR logic with nested bool blocks.
- should clause scores are summed into the overall bool score, making should useful for soft-ranking signals.
- The boost parameter weights an individual clause's contribution relative to its siblings.
- Anchor broad should logic with a must or filter clause to keep queries fast and precise.
Practice what you learned
1. In a bool query with a must clause present, what happens to should clauses by default?
2. What does minimum_should_match: 2 require in a bool query?
3. Which two bool occurrence types run in filter context and do not affect the relevance score?
4. How do should clause scores combine with a bool query's overall _score when a must clause is also present?
Was this page helpful?
You May Also Like
The Query DSL
A guide to Elasticsearch's JSON-based Query DSL, the request language used to build every search, filter, and aggregation.
Match and Term Queries
How Elasticsearch's two most fundamental leaf queries differ: match for analyzed full-text search and term for exact, unanalyzed matching.
Filtering vs Scoring
Why the choice between filter context and query context is a core Elasticsearch performance and relevance decision, not just a syntax preference.