BoostingQuery for Soft Demotion Instead of Hard Exclusion

BoostingQuery 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

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.

const query = new BoostingQuery({
  positive: new MatchQuery({ field: "body", text: "vector search" }),
  negative: new BoolQuery({ filter: [new TermQuery({ field: "status", text: "draft" })] }),
  negativeBoost: 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.