---
title: "Explain a BM25 search relevance score in C#"
url: https://recursiveai.org/oneindex/cookbook/explain-search-relevance-score/
description: "Inspect a BM25F relevance score in C# with OneIndex Explain: term frequency, field boosts, length normalization and real output from a small corpus."
version: "0.4.0-preview.2"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneIndex) · [GitHub](https://github.com/recursive-ai-oss/oneindex-csharp) · [Docs](https://recursiveai.org/oneindex/docs/) · [Download example (.zip)](https://recursiveai.org/oneindex/cookbook/explain-search-relevance-score/explain-search-relevance-score.zip)

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`.

```shell
dotnet add package RecursiveAI.OneIndex --prerelease
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/oneindex/cookbook/explain-search-relevance-score/explain-search-relevance-score.zip), 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.

```csharp
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:

```csharp
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
```

## Related recipes

[Full-text search](https://recursiveai.org/oneindex/cookbook/full-text-search-csharp/) · [Hybrid search and reranking](https://recursiveai.org/oneindex/cookbook/hybrid-search-reranking-csharp/)

## 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](https://recursiveai.org/oneindex/docs/scoring/) 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.
