Boost RankerCompatible with Milvus v2.6.2+

Instead of relying solely on semantic similarity calculated based on vector distances, Boost Rankers allow you to influence search results in a meaningful way. It is ideal for quickly adjusting search results using metadata filtering.

When a search request includes a Boost Ranker function, Milvus uses the optional filtering condition within the function to find matches among search result candidates and boosts the scores of those matches by applying the specified weight, helping promote or demote the rankings of the matched entities in the final result.

When to use Boost Ranker

Unlike other rankers that rely on cross-encoder models or fusion algorithms, a Boost Ranker directly injects optional metadata-driven rules into the ranking process, which makes it more suitable in the following scenarios.

Use Case	Examples	Why Boost Ranker Works Well
Business-driven content prioritization	Highlight premium products in e-commerce search results Increase visibility of content with high user engagement metrics (such as views, likes, and shares) Elevating recent content in time-sensitive search applications Prioritizing content from verified or trusted sources Boosting results that match exact phrases or high-relevance keywords	Without the need to rebuild indexes or modify vector embedding models—operations that can be time-consuming—you can instantly promote or demote specific items in search results by applying optional metadata filters in real time. This mechanism enables flexible, dynamic search rankings that easily adapt to evolving business requirements.
Strategic content downranking	Reducing the prominence of items with low inventory without removing them completely Lowering the rank of content with potentially objectionable terms without censorship Demoting older documentation while keeping it accessible in technical searches Subtly reducing the visibility of competitor products in marketplace searches Decreasing relevance of content with lower quality indications (such as formatting issues, shorter length, etc.)

You can also combine multiple Boost Rankers to implement a more dynamic and robust weight-based ranking strategy.

Mechanism of Boost Ranker

The following diagram illustrates the main workflow of Boost Rankers.

Boost Ranker Mechanism

When you insert data, Milvus distributes it across segments. During a search, each segment returns a set of candidates, and Milvus ranks these candidates from all segments to produce the final results. When a search request includes a Boost Ranker, Milvus applies it to the candidate results from each segment to prevent potential precision loss and improve recall.

Before finalizing the results, Milvus processes these candidates with the Boost Ranker as follows:

1. Applies the optional filtering expression specified in the Boost Ranker to identify the entities that match the expression.

2. Applies the weight specified in the Boost Ranker to boost the scores of the identified entities.

Examples of Boost Ranker

The following example illustrates the use of a Boost Ranker in a single-vector search that requires returning the top five most relevant entities and adding weights to the scores of entities with the abstract doc type.

1. Collect search result candidates in segments.

   The following table assumes Milvus distributes entities into two segments (0001 and 0002), with each segment returning five candidates.

   ID	DocType	Score	Rank	segment
   117	abstract	0.344	1	0001
   89	abstract	0.456	2	0001
   257	body	0.578	3	0001
   358	title	0.788	4	0001
   168	body	0.899	5	0001
   46	body	0.189	1	0002
   48	body	0265	2	0002
   561	abstract	0.366	3	0002
   344	abstract	0.444	4	0002
   276	abstract	0.845	5	0002

2. Apply the filtering expression specified in the Boost Ranker (doctype='abstract').

   As denoted by the DocType field in the following table, Milvus will mark all entities with their doctype set to abstract for further processing.

   ID	DocType	Score	Rank	segment
   117	abstract	0.344	1	0001
   89	abstract	0.456	2	0001
   257	body	0.578	3	0001
   358	title	0.788	4	0001
   168	body	0.899	5	0001
   46	body	0.189	1	0002
   48	body	0265	2	0002
   561	abstract	0.366	3	0002
   344	abstract	0.444	4	0002
   276	abstract	0.845	5	0002

3. Apply the weight specified in the Boost Ranker (weight=0.5).

   All identified entities in the previous step will be multiplied by the weight specified in the Boost Ranker, resulting in changes in their ranks.

   ID	DocType	Score	Weighted Score (= score x weight)	Rank	segment
   117	abstract	0.344	0.172	1	0001
   89	abstract	0.456	0.228	2	0001
   257	body	0.578	0.578	3	0001
   358	title	0.788	0.788	4	0001
   168	body	0.899	0.899	5	0001
   561	abstract	0.366	0.183	1	0002
   46	body	0.189	0.189	2	0002
   344	abstract	0.444	0.222	3	0002
   48	body	0.265	0.265	4	0002
   276	abstract	0.845	0.423	5	0002

   The weight must be a floating-point number that you choose. In cases like the above example, where a smaller score indicates greater relevance, use a weight less than 1. Otherwise, use a weight greater than 1.

4. Aggregate the candidates from all segments based on the weighted scores to finalize the results.

   ID	DocType	Score	Weighted Score	Rank	segment
   117	abstract	0.344	0.172	1	0001
   561	abstract	0.366	0.183	2	0002
   46	body	0.189	0.189	3	0002
   344	abstract	0.444	0.222	4	0002
   89	abstract	0.456	0.228	5	0001

Usage of Boost Ranker

In this section, you will see examples of how to use Boost Ranker to influence the results of a single-vector search.

Create a Boost Ranker

Before passing a Boost Ranker as the reranker of a search request, you should properly define the Boost Ranker as a reranking function as follows:

from pymilvus import Function, FunctionType

ranker = Function(
    name="boost",
    input_field_names=[], # Must be an empty list
    function_type=FunctionType.RERANK,
    params={
        "reranker": "boost",
        "filter": "doctype == 'abstract'",
        "random_score": { 
            "seed": 126,
            "field": "id"
        },
        "weight": 0.5
    }
)

Parameter	Required?	Description	Value/Example
name	Yes	Unique identifier for this Function	"rrf"
input_field_names	Yes	List of vector fields to apply the function to (must be empty for RRF Ranker)	[]
function_type	Yes	The type of Function to invoke; use RERANK to specify a reranking strategy	FunctionType.RERANK
params.reranker	Yes	Specifies the type of the reranker. Must be set to boost to use Boost Ranker.	"boost"
params.weight	Yes	Specifies the weight that will be multiplied by the scores of any matching entities in the raw search results. The value should be a floating-point number. To emphasize the importance of matching entities, set it to a value that boosts the scores. To demote matching entities, assign this parameter a value that lowers their scores.	1
params.filter	No	Specifies the filter expression that will be used to match entities among search result entities. It can be any valid basic filter expression mentioned in Filtering Explained. Note: Only use basic operators, such as ==, >, or <. Using advanced operators, such as text_match or phrase_match, will degrade search performance.	"doctype == 'abstract'"
params.random_score	No	Specifies the random function that generates a value between 0 and 1 randomly. It has the following two optional arguments: seed (number) Specifies an initial value used to start a pseudorandom number generator (PRNG). field (string) Specifies the name of a field whose value will be used as a random factor in generating the random number. A field with unique values will suffice. You are advised to set both seed and field to ensure consistency across generations by using the same seed and field values.	{"seed": 126, "field": "id"}

Search with a single Boost Ranker

Once the Boost Ranker function is ready, you can reference it in a search request. The following example assumes that you have already created a collection that has the following fields: id, vector, and doctype.

from pymilvus import MilvusClient

# Connect to the Milvus server
client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

# Assume you have a collection set up

# Conduct a similarity search using the created ranker
client.search(
    data=[-0.619954382375778, 0.4479436794798608, -0.17493894838751745, -0.4248030059917294, -0.8648452746018911],
    anns_field="vector",
    params={},
    output_field=["doctype"],
    ranker=ranker
)

Search with multiple Boost Rankers

You can combine multiple Boost Rankers in a single search to influence the search results. To do so, create several Boost Rankers, reference them in a FunctionScore instance, and use the FunctionScore instance as the ranker in the search request.

The following example shows how to modify the scores of all identified entities by applying a weight between 0.8 and 1.2.

from pymilvus import MilvusClient, Function, FunctionType, FunctionScore

# Create a Boost Ranker with a fixed weight
fix_weight_ranker = Function(
    name="boost",
    input_field_names=[], # Must be an empty list
    function_type=FunctionType.RERANK,
    params={
        "reranker": "boost",
        "weight": 0.8
    }
)

# Create a Boost Ranker with a randomly generated weight between 0 and 0.4
random_weight_ranker = Function(
    name="boost",
    input_field_names=[], # Must be an empty list
    function_type=FunctionType.RERANK,
    params={
        "reranker": "boost",
        "random_score": {
            "seed": 126,
        },
        "weight": 0.4
    }
)

# Create a Function Score
ranker = FunctionScore(
    functions=[
        fix_weight_ranker, 
        random_weight_ranker
    ],
    params: {
        "boost_mode": "Multiply"
        "function_mode": "Sum"
    }
)

# Conduct a similarity search using the created Function Score
client.search(
    data=[-0.619954382375778, 0.4479436794798608, -0.17493894838751745, -0.4248030059917294, -0.8648452746018911],
    anns_field="vector",
    params={},
    output_field=["doctype"],
    ranker=ranker
)

Specifically, there are two Boost Rankers: one applies a fixed weight to all found entities, while the other assigns a random weight to them. Then, we reference these two rankers in a FunctionScore, which also defines how the weights influence the scores of the found entities.

The following table lists the parameters required to create a FunctionScore instance.

Parameter	Required?	Description	Value/Example
functions	Yes	Specifies the names of the target rankers in a list.	["fix_weight_ranker", "random_weight_ranker"]
params.boost_mode	No	Specifies how the specified weights influence the scores of any matching entities. Possible values are: Multiple Indicates that the weighted value is equal to the original score of a matching entity multiplied by the specified weight. This is the default value. Sum Indicates that the weighted value is equal to the sum of the original score of a matching entity and the specified weight	"Sum"
params.function_mode	No	Specifies how the weighted values from various Boost Rankers are processed. Possible values are: Multiplify Indicates that the final score of a matching entity is equal to the product of the weighted values from all Boost Rankers. This is the default value. Sum Indicates that the final score of a matching entity is equal to the sum of the weighted values from all Boost Rankers.	"Sum"