Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 43 ยท Searching

Bool Queries and Compound Logic

Combine Elasticsearch queries with bool: must, filter, should and must_not, plus constant_score, dis_max, function_score and boosting.

Real searches combine many conditions: the text must match, the product must be in stock, the price must be under a limit, a brand you promote should rank higher, and archived items must disappear. Elasticsearch handles this with compound queries. The most important one by far is the bool query, and the rest (constant_score, dis_max, function_score, boosting) refine how scores are produced.

The key idea is that a clause either affects the score or it does not. Clauses that only decide "is this document in or out" are cheap and cacheable. Clauses that contribute to ranking are scored. This lesson shows the four bool clauses, the scoring rules, and the other compound queries. Real requests are read-only; a JavaScript stand-in implements a small bool scorer so you can see the arithmetic.

The four bool clauses

must Has to match. Adds to the score.
filter Has to match. No score, cacheable.
should Nice to have. Raises the score.
must_not Must not match. No score.

Think of filter and must_not as yes/no gates.

1 / 2

The bool query

A bool query holds lists of clauses. Each clause is itself a query, so you can nest them as deeply as you need:

JSON
GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "name": "wireless headphones" } }
      ],
      "filter": [
        { "term": { "in_stock": true } },
        { "range": { "price": { "lte": 150 } } }
      ],
      "should": [
        { "term": { "brand": "acme" } }
      ],
      "must_not": [
        { "term": { "status": "discontinued" } }
      ]
    }
  }
}

Read it as a sentence: find products whose name matches "wireless headphones", only those in stock and priced up to 150, prefer the brand acme, and never show discontinued items.

How each clause behaves

Clause Must match? Contributes to score? Cached?
must Yes Yes No
filter Yes No (filter context) Often
should Depends (see below) Yes No
must_not Must NOT match No (filter context) Often

Elasticsearch calls the "no score" mode the filter context, introduced in Query DSL Basics. Put every yes/no condition (status, range, tenant, category) in filter. Only text relevance belongs in must or should. This is not just tidiness: filters skip score computation and their results can be cached as bitsets, which is a big part of the advice in Query Performance and Tuning.

should is subtle

What should does depends on whether the bool query has must or filter clauses:

  • With no must and no filter clause, at least one should clause must match.
  • With a must or filter clause, should clauses are optional. They only boost the score of documents that match them.

You can override this with minimum_should_match. For example "minimum_should_match": 2 means at least two of the should clauses must match.

JSON
{
  "query": {
    "bool": {
      "should": [
        { "match": { "title": "elasticsearch" } },
        { "match": { "title": "search" } },
        { "match": { "title": "tutorial" } }
      ],
      "minimum_should_match": 2
    }
  }
}

This is how a match query with or operator is built internally: one should clause per token.

How the score is combined

For a document that matches, the final score is the sum of the scores of the matching must and should clauses. The filter and must_not clauses add nothing. Each clause can carry a boost to scale its contribution:

JSON
{
  "bool": {
    "must": { "match": { "name": "headphones" } },
    "should": [
      { "term": { "brand": { "value": "acme", "boost": 2.0 } } },
      { "term": { "featured": { "value": true, "boost": 0.5 } } }
    ]
  }
}

A document that matches the name and both should clauses gets the name score plus 2.0 times the brand clause score plus 0.5 times the featured clause score. The brand and featured scores themselves come from BM25 (see Relevance Scoring with BM25), so boosts are multipliers, not fixed bonuses. If you want a fixed bonus, wrap the query in constant_score.

Try it: a tiny bool scorer

The stand-in below evaluates filter, must_not, must and should over a few products. To keep the arithmetic readable, a matching text clause scores 1 per matching word and a matching should clause scores its boost. The real BM25 scores would differ, but the structure is the same.

JS A bool scorer

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that should changes the order but not the set of results. #3 (out of stock), #4 (discontinued) and #5 (too expensive) never show up in either list because filters and must_not remove them.

constant_score

constant_score runs a query in filter context and gives every match the same score, equal to its boost:

JSON
{
  "query": {
    "constant_score": {
      "filter": { "term": { "category": "audio" } },
      "boost": 1.2
    }
  }
}

Use it when you want a fixed contribution inside a bigger bool, for example a flat bonus for "featured" items that should not depend on term statistics.

dis_max

dis_max ("disjunction max") takes several queries and scores a document by its best-matching query, plus an optional tie_breaker share of the others:

JSON
{
  "query": {
    "dis_max": {
      "queries": [
        { "match": { "title": "search engine" } },
        { "match": { "body": "search engine" } }
      ],
      "tie_breaker": 0.3
    }
  }
}

If a document matches strongly in title and weakly in body, the title score wins and the body adds 30% of its score. Plain should clauses would add the two scores, so a document with the phrase mentioned weakly in many fields could beat one with a strong match in a single field. multi_match with best_fields (see Full-Text Queries) is built from dis_max.

function_score

function_score changes the score of a query using functions: a fixed weight, a field value, a decay by distance or date, a random value, or a script. It is the tool for "relevance plus business signals":

JSON
{
  "query": {
    "function_score": {
      "query": { "match": { "title": "elasticsearch" } },
      "functions": [
        {
          "field_value_factor": {
            "field": "likes",
            "modifier": "log1p",
            "factor": 2,
            "missing": 0
          }
        },
        {
          "gauss": {
            "published": { "origin": "now", "scale": "30d", "decay": 0.5 }
          }
        }
      ],
      "score_mode": "multiply",
      "boost_mode": "multiply"
    }
  }
}

Three concepts matter:

  • score_mode says how the function results combine with each other (multiply, sum, avg, max, first...).
  • boost_mode says how the combined function result merges with the query score (multiply, sum, replace...).
  • Use a dampening modifier such as log1p for counters. Multiplying a text score by a raw like count would let a viral document beat every relevant one.

The gauss decay shown above halves the weight of a document when its date is 30 days away from now. Fresher documents get a higher weight.

Prefer simple tools first. function_score is flexible, but scripts are slow and tuning is hard. Newer versions also offer rank_feature fields for popularity-like signals, which are much cheaper than a script. Check what your version supports before building a custom solution.

The boosting query

Sometimes you want to demote documents rather than remove them. The boosting query keeps results matching positive, and multiplies the score of those that also match negative by negative_boost (a number between 0 and 1):

JSON
{
  "query": {
    "boosting": {
      "positive": { "match": { "title": "apple" } },
      "negative": { "match": { "title": "pie recipe" } },
      "negative_boost": 0.3
    }
  }
}

A search for apple (the company) still shows pie articles but ranks them lower. A must_not would delete them completely, which might hide the one result the user wanted.

Try it: dis_max, tie_breaker and boosting

This stand-in compares adding scores (what should does) with taking the maximum (dis_max), and shows a demotion by negative_boost. The scores are hand-set field scores so the numbers are easy to follow.

JS dis_max versus sum, and demotion

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With plain addition, B wins because it matches somewhere in both fields. With dis_max and no tie breaker, A wins on its single strong field. A tie breaker keeps some credit for secondary matches. This is exactly the trade-off you choose when you pick between most_fields and best_fields.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which bool clauses do NOT contribute to the score?

    filter and must_not run in filter context: they include or exclude documents without scoring, and their results can be cached.
  2. 2. A bool query has one must clause and two should clauses, and no minimum_should_match. What do the should clauses do?

    When a must or filter clause exists, should clauses are optional by default. Use minimum_should_match to require some of them.
  3. 3. Why use dis_max instead of adding the scores of several field queries?

    dis_max uses the best query score (plus an optional tie_breaker share of the rest), so one strong match is not outweighed by several weak ones.
  4. 4. You want articles about pie recipes to still appear for apple, but lower in the list. What fits best?

    must_not would remove them. The boosting query keeps them and multiplies their score by negative_boost.

Summary

  • bool combines must, filter, should and must_not; put yes/no conditions in filter and relevance in must/should.
  • should is optional next to must or filter, unless you set minimum_should_match.
  • The score is the sum of matching must and should clauses; boost scales a clause.
  • constant_score gives a flat score, dis_max takes the best clause, function_score blends in business signals, and boosting demotes instead of removing.

Next: Sorting and Pagination.