BoostingQuery for Soft Demotion Instead of Hard Exclusion

boosting models a common search need: some documents are relevant, but some of those relevant documents should rank lower because they also match a negative signal.

This is different from mustNot.

• mustNot removes documents entirely
• BoostingQuery keeps them, but reduces their score

Basic shape

BoostingQuery takes:

• a positive query
• a negative query
• a negativeBoost multiplier between 0 and 1

{
  "query": {
    "boosting": {
      "positive": {
        "match": {
          "title": {
            "query": "querylight"
          }
        }
      },
      "negative": {
        "term": {
          "tags": "deprecated"
        }
      },
      "negative_boost": 0.2
    }
  }
}

Equivalent internal TypeScript API:

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

const query = new BoostingQuery({
  positive: new MatchQuery({ field: "title", text: "querylight" }),
  negative: new TermQuery({ field: "tags", text: "deprecated" }),
  negativeBoost: 0.2
});

Here, documents matching title:querylight still qualify. If they also have the deprecated tag, their score is multiplied by 0.2.

Good uses

• Demote archived or deprecated content.
• Lower the rank of stale docs while still returning them.
• Penalize low-quality signals such as “generated”, “draft”, or “duplicate”.
• Prefer canonical documents without hiding alternates completely.

Compared with bool logic

If you already know a document should never appear, use mustNot.

If the document is still acceptable but should lose ranking priority, use BoostingQuery.

{
  "query": {
    "boosting": {
      "positive": {
        "match": {
          "body": {
            "query": "vector search"
          }
        }
      },
      "negative": {
        "bool": {
          "filter": [
            { "term": { "status": "draft" } }
          ]
        }
      },
      "negative_boost": 0.3
    }
  }
}

Tuning advice

• Start with negativeBoost around 0.2 to 0.5.
• Smaller values create harsher demotion.
• If the negative signal should behave like a strict rule, use mustNot instead.