BoolQuery for Must, Should, Filter, MustNot, and MinimumShouldMatch

bool is the main way to combine ranking clauses with hard constraints. The JSON DSL form is the primary one. The class API below is the equivalent internal TypeScript layer.

Structure

• should: contributes score
• must: required to appear
• filter: required but not intended for scoring logic
• mustNot: excluded documents

By default, should clauses are optional whenever must or filter is present. If a bool query contains only should clauses, at least one should clause must match.

{
  "query": {
    "bool": {
      "should": [
        { "match": { "title": { "query": "phrase search", "operator": "and", "boost": 3 } } },
        { "match": { "body": { "query": "phrase search", "operator": "and", "boost": 1.5 } } }
      ],
      "filter": [
        { "term": { "section": "Queries" } }
      ],
      "must_not": [
        { "term": { "level": "advanced" } }
      ]
    }
  }
}

Equivalent internal TypeScript API:

import { BoolQuery, MatchQuery, OP, TermQuery } from "@tryformation/querylight-ts";

const query = new BoolQuery({
  should: [
    new MatchQuery({ field: "title", text: "phrase search", operation: OP.AND, boost: 3.0 }),
    new MatchQuery({ field: "body", text: "phrase search", operation: OP.AND, boost: 1.5 })
  ],
  filter: [new TermQuery({ field: "section", text: "Queries" })],
  mustNot: [new TermQuery({ field: "level", text: "advanced" })]
});

minimumShouldMatch

Use minimumShouldMatch when you want a specific number of should clauses to become mandatory.

{
  "query": {
    "bool": {
      "should": [
        { "match": { "title": { "query": "vector" } } },
        { "match": { "body": { "query": "search" } } },
        { "match": { "tags": { "query": "ranking" } } }
      ],
      "minimum_should_match": 2
    }
  }
}

Good use cases

• Search content but restrict to a section.
• Hide advanced entries in an onboarding view.
• Combine phrase-heavy title matches with broader body matches.
• Promote preferred matches without filtering out the rest.
• Require two or more optional signals before a document is accepted.

Learn more

• Boolean model of information retrieval on Wikipedia