Bool query in depth in Elasticsearch

Introduction

A bool query helps you combine many search rules together. It lets you say what must happen, what should happen, and what must not happen in your search.

You want to find documents that match several conditions at once.

You want to require some conditions but make others optional.

You want to exclude documents that have certain words or values.

You want to mix different types of queries like term, range, or match.

You want to build complex search filters for your app or website.

Syntax

Elasticsearch

{
  "bool": {
    "must": [ /* queries that must match */ ],
    "filter": [ /* queries that filter results but don't affect score */ ],
    "should": [ /* queries that should match to boost score */ ],
    "must_not": [ /* queries that must NOT match */ ]
  }
}

must means all these queries have to match.

filter is like must but faster and does not change score.

Examples

Find documents where the title has the word "apple".

Elasticsearch

{
  "bool": {
    "must": [
      { "match": { "title": "apple" } }
    ]
  }
}

Find documents with "apple" in the title but exclude those with status "sold".

Elasticsearch

{
  "bool": {
    "must": [
      { "match": { "title": "apple" } }
    ],
    "must_not": [
      { "term": { "status": "sold" } }
    ]
  }
}

Find documents that mention either "fresh" or "organic" in the description.

Elasticsearch

{
  "bool": {
    "should": [
      { "match": { "description": "fresh" } },
      { "match": { "description": "organic" } }
    ],
    "minimum_should_match": 1
  }
}

Filter documents where price is between 10 and 50, without affecting score.

Elasticsearch

{
  "bool": {
    "filter": [
      { "range": { "price": { "gte": 10, "lte": 50 } } }
    ]
  }
}

Sample Program

This query finds documents that have "coffee" in the title and "fresh" in the description. It only includes items priced between 5 and 20. It excludes items with status "sold". If the brand is "acme", the document scores higher but it is not required.

Elasticsearch

{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "coffee" } },
        { "match": { "description": "fresh" } }
      ],
      "filter": [
        { "range": { "price": { "gte": 5, "lte": 20 } } }
      ],
      "must_not": [
        { "term": { "status": "sold" } }
      ],
      "should": [
        { "match": { "brand": "acme" } }
      ],
      "minimum_should_match": 0
    }
  }
}

Important Notes

You can use minimum_should_match to say how many should queries must match.

filter clauses are cached and faster for repeated queries.

Use must_not to exclude unwanted results.

Summary

A bool query combines many queries with rules: must, should, filter, and must_not.

Use must for required matches, filter for fast filtering, should for optional boosts, and must_not to exclude.

Bool queries help build powerful and flexible searches in Elasticsearch.