bool must/should/filter/must_not, Minimum Should Match, Filter Context, and Cacheability

Learning outcomes

AtlasMart's product endpoint must combine “how well does this match?” with “is this product eligible at all?”. A Boolean query is the boundary between those concerns. Misplacing a clause can change ranking, matching, cache eligibility and even the meaning of should. This lesson makes that logic explicit and testable.

1. Translate requirements into two questions

For each AtlasMart criterion, ask: must this affect relevance? If yes, it belongs in query context such as must/should. If it is a binary eligibility rule such as inventory availability, category, tenant, price or policy status, place it in filter context when semantics allow. Filters skip relevance scoring and may benefit from caching/bitset reuse according to engine heuristics.

2. One Boolean request, with clause names

GET atlasmart-products-query-v1/_search
{
  "query": {
    "bool": {
      "must": [
        { "multi_match": {
          "query": "noise cancelling",
          "fields": ["name^3", "description"],
          "_name": "lexical"
        }}
      ],
      "filter": [
        { "term":  { "available": { "value": true, "_name": "in_stock" } } },
        { "range": { "price": { "lte": 150, "_name": "budget" } } }
      ],
      "should": [
        { "term": { "brand": { "value": "Auralux", "_name": "preferred_brand" } } }
      ]
    }
  }
}

For the fixture, p4 is the deterministic eligible lexical hit: it matches “noise cancelling”, is available, and costs at most 150. The brand preference can affect score but is not required because a must/filter exists and no explicit minimum_should_match was set.

3. The should default changes with surrounding clauses

If a Boolean query has one or more should clauses and no must or filter, the default minimum_should_match is 1. If a must or filter clause exists, the default becomes 0. This is convenient for relevance boosts but dangerous when an API designer meant “at least one selected preference is required.” Make the requirement explicit.

GET atlasmart-products-query-v1/_search
{
  "query": {
    "bool": {
      "filter": [ { "term": { "available": true } } ],
      "should": [
        { "term": { "brand": "Auralux" } },
        { "term": { "category": "office/accessories" } }
      ],
      "minimum_should_match": 1
    }
  }
}

Conditional and percentage forms are available, but complexity should follow a tested business rule. “75% sounds relevant” is not a requirement.

4. must_not is filter context, not negative scoring

must_not excludes documents that match its clauses; it does not merely decrease their score. If you need a soft penalty, that is a relevance-design problem for Chapter 07. Confusing exclusion with demotion can silently remove valid products.

GET atlasmart-products-query-v1/_search
{
  "query": {
    "bool": {
      "filter": { "term": { "available": true } },
      "must_not": { "term": { "category": "sports/running" } }
    }
  }
}

5. Cacheability is observable, not promised per clause

Filter context avoids score calculation and can enable reusable cached structures, but engines decide what to cache based on query shape, segment state, frequency and other heuristics. Do not write a design document that says “all filters are cached.” Use node/index query-cache statistics and representative repeated workloads if cache behavior matters. Separate the shard-level request cache from query/filter caching concepts, and do not benchmark with one warmed query then claim general p99 improvement.

6. Debug Boolean logic with names before score tuning

Name important clauses uniquely. For each expected hit, record which names matched and which eligibility rules were applied. This catches logic errors such as a should clause accidentally becoming optional after a new filter was added. If a query behaves unexpectedly, simplify it to one clause at a time before opening Profile.

Production judgment

Encode eligibility and relevance separately in application code. Make minimum_should_match explicit when business meaning depends on it. Give each externally visible filter a typed allowlist and bounds, and monitor clause growth because deeply nested Boolean trees and large term lists can become resource problems even if each leaf looks harmless.

Summary and next step

Boolean Query DSL is now a translation of product intent rather than a bag of clauses. Next, preserve object correlation with nested queries, add geographic constraints, and isolate scripts/expensive queries behind stronger guardrails.

Authoritative references

• Elastic: Query DSL overview — Current leaf/compound query, query/filter context, and expensive-query reference.
• Elastic: full-text queries — Current full-text query families and analyzed-input semantics.
• Elastic: term-level queries — Exact-value and structured-query semantics.
• Elastic: bool query — must/should/filter/must_not, minimum_should_match, and named-query behavior.
• Elastic: query and filter context — Scoring versus binary filtering semantics.
• OpenSearch: Query DSL — Current OpenSearch query categories and expensive-query controls.
• OpenSearch: bool query — Boolean clause semantics and minimum_should_match behavior.
• OpenSearch: wildcard query — Wildcard cost, rewrite behavior, and search.allow_expensive_queries interaction.
• OpenSearch: script query — Painless script-query behavior and cost warning.