Recursive AI

Explain a BM25 search relevance score in C#

OneIndex is a free, open-source search library for .NET from Recursive AI. MIT or Apache-2.0, preview, runs in-process.

A score explanation shows which terms and field statistics put a search result in its position. OneIndex uses BM25F, the multi-field form of BM25. Call .Explain() before .Execute() to populate each hit’s Explanation.

Terminal
dotnet add package RecursiveAI.OneIndex --prerelease

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneIndex;
 
using var index =
    SearchIndex.InMemory<Note>();
index.Upsert(new Note { Text = "apple" });
index.Commit();
var hits = index.Search("apple")
    .Explain().Execute();
Console.Write(hits[0].Explanation);
 
public class Note
{
    [SearchId]
    public string Id { get; set; } = "1";
    [FullText]
    public string Text { get; set; } = "";
}
Text
0.151411623 = query word 'apple' matched 'apple' (whole word, 0 typos): typo factor 1 = 1 / (1 + typos), exactness factor 1, boost 1
  0.151411623 = term 'apple': boost 1 * idf * x / (k1 + x), k1 = 0.899999976
    0.287682086 = idf = ln(1 + (N - n + 0.5) / (n + 0.5)), n = 1, N = 1
    1 = x = sum over fields of weight * tf / ((1 - b) + b * length / avgLength)
      1 = field Text: weight 1 * tf 1 / ((1 - b) + b * length 1 / avgLength 1), b = 0.400000006

Unzip the example, then dotnet run.

The full program

The download indexes three synthetic notes. One matches in a title boosted by 3; another repeats the word in its body; the last has one match in a longer body. This example uses OneIndex 0.4.0-preview.2, a preview release.

C#
using OneIndex;
using System.Globalization;
 
CultureInfo.CurrentCulture = CultureInfo.InvariantCulture;
using var index = SearchIndex.InMemory<Note>();
index.Upsert([
    new() { Id = "title", Title = "apple", Body = "guide" },
    new() { Id = "repeat", Title = "guide", Body = "apple apple apple" },
    new() { Id = "long", Title = "guide", Body = "apple guide to growing fruit in a garden" }
]);
index.Commit();
var hits = index.Search("apple").Explain().Take(3).Execute();
foreach (var hit in hits)
{
    Console.WriteLine($"{hit.Document.Id}: {hit.Score:G9}");
    Console.Write(hit.Explanation);
}
 
public class Note
{
    [SearchId] public string Id { get; set; } = "";
    [FullText(Boost = 3)] public string Title { get; set; } = "";
    [FullText] public string Body { get; set; } = "";
}

dotnet run prints:

Text
repeat: 0.370081633
0.370081633 = query word 'apple' matched 'apple' (whole word, 0 typos): typo factor 1 = 1 / (1 + typos), exactness factor 1, boost 1
  0.370081633 = term 'apple': boost 1 * idf * x / (k1 + x), k1 = 0.899999976
    0.470003635 = idf = ln(1 + (N - n + 0.5) / (n + 0.5)), n = 2, N = 3
    3.33333325 = x = sum over fields of weight * tf / ((1 - b) + b * length / avgLength)
      3.33333325 = field Body: weight 1 * tf 3 / ((1 - b) + b * length 3 / avgLength 4), b = 0.400000006
title: 0.361541241
0.361541241 = query word 'apple' matched 'apple' (whole word, 0 typos): typo factor 1 = 1 / (1 + typos), exactness factor 1, boost 1
  0.361541241 = term 'apple': boost 1 * idf * x / (k1 + x), k1 = 0.899999976
    0.470003635 = idf = ln(1 + (N - n + 0.5) / (n + 0.5)), n = 2, N = 3
    3 = x = sum over fields of weight * tf / ((1 - b) + b * length / avgLength)
      3 = field Title: weight 3 * tf 1 / ((1 - b) + b * length 1 / avgLength 1), b = 0.400000006
long: 0.207966194
0.207966194 = query word 'apple' matched 'apple' (whole word, 0 typos): typo factor 1 = 1 / (1 + typos), exactness factor 1, boost 1
  0.207966194 = term 'apple': boost 1 * idf * x / (k1 + x), k1 = 0.899999976
    0.470003635 = idf = ln(1 + (N - n + 0.5) / (n + 0.5)), n = 2, N = 3
    0.714285672 = x = sum over fields of weight * tf / ((1 - b) + b * length / avgLength)
      0.714285672 = field Body: weight 1 * tf 1 / ((1 - b) + b * length 8 / avgLength 4), b = 0.400000006

Variations

To check the root value without printing the whole tree, replace the search and print loop with:

C#
var hits = index.Search("apple").Explain().Take(3).Execute();
foreach (var hit in hits)
    Console.WriteLine($"{hit.Document.Id}: " +
        $"{hit.Explanation!.Value == hit.Score}");
Text
repeat: True
title: True
long: True

Full-text search · Hybrid search and reranking

The short answer

Call .Explain() on a OneIndex search before executing it. Each returned hit then carries an Explanation tree. Print it to see term statistics and field contributions; its root Value equals the hit’s Score. The snippet at the top shows one document. The download uses a small corpus to make field boost, term frequency and length normalization visible side by side.

What is a BM25 score?

In this library, lexical relevance is computed with BM25F. A score combines evidence that a query term occurs in a document, how rare that term is across the indexed collection, how often it appears in each searched field, and how those field lengths compare with their averages. A field boost weights that field’s evidence before saturation. The score is a ranking value, not a probability or a percent of relevance.

Read the output from the leaves upward. The field nodes report weight, term frequency, field length, average field length and b. Their normalized contributions sum into x. The term node combines x with inverse document frequency and k1. For this single-word query, the outer query-word node shows exactness and typo factors of one, so it leaves the term score unchanged. Longer queries may add other nodes; read the tree rather than assuming every root is a bare term calculation.

How does BM25 search work?

OneIndex first forms a weighted normalized frequency across fields. For each matching field, it divides frequency times field weight by (1 - b) + b * length / avgLength, then adds those contributions. It saturates the combined evidence using boost * idf * x / (k1 + x). Saturation happens after summing across fields; separately scoring each field and adding the final scores is not the same formula. The scoring documentation gives the complete definition.

The sample’s repeat body has term frequency 3, length 3 and average body length 4. With b approximately 0.4, its normalized contribution is about 3.3333. The title note has title weight 3, frequency 1 and title length equal to its average of 1, giving a contribution of 3. Repetition in this short body therefore narrowly outranks the boosted title in this corpus. A boost is a weight, not an instruction that every title match must rank first.

The long note has only one occurrence in a body of eight tokens. With average body length 4, its normalized contribution is about 0.7143, below the other two. The explanation prints the actual floating-point values, including the default k1 near 0.9 and b near 0.4. Rounding those values for prose is useful for reading the formula, but use the returned score when comparing actual hits.

What is the BM25 score range?

There is no universal relevance scale on which a fixed value means “good enough” for every query and corpus. OneIndex’s score depends on collection statistics, boosts and the query tree. A threshold selected for these three notes is not evidence for a threshold on a different collection.

Statistics are shared across the snapshot’s segments: the stored document batches visible to that search. Documents deleted but not yet merged away still contribute to those statistics, so merges and updates can change scores. If you are investigating a surprising ranking, retain the query, schema and indexed data used to reproduce it. Compare explanations for the competing hits under the same snapshot.

All oneindex recipes