# The BM25 rank feature

[](/en/ranking/bm25.html.md "View as Markdown") 

The [bm25 rank feature](../reference/ranking/rank-features.html#bm25) implements the [Okapi BM25](https://en.wikipedia.org/wiki/Okapi_BM25) ranking function used to estimate the relevance of a text document given a search query. It is a pure text ranking feature which operates over an [indexed string field](../reference/schemas/schemas.html#indexing-index). The feature is cheap to compute, about 3-4 times faster than [nativeRank](nativerank.html), while still providing a good rank score quality wise. It is a good candidate to use in a first phase ranking function when ranking text documents.

## Ranking function

The _bm25_ feature calculates a score for how good a query with termsq1,...,qnmatches an indexed string field _t_ in a document _D_. The score is calculated as follows:

&Sum;inIDF(qi)⋅f(qi,D)⋅(k1+1)f(qi,D)+k1⋅(1-b+b⋅field\_lenavg\_field\_len)

Where the components in the function are:

- IDF(qi): The [inverse document frequency](https://en.wikipedia.org/wiki/Tf%E2%80%93idf#Inverse_document_frequency) (_IDF_) of query term _i_ in field _t_. This is calculated as: 

- f(qi,D): The number of occurrences (term frequency) of query term _i_ in the field _t_ of document _D_. For multi-value fields we use the sum of occurrences over all elements. 
- field\_len: The field length (in number of words) of field _t_ in document _D_. For multi-value fields we use the sum of field lengths over all elements. 
- avg\_field\_len: The average field length of field _t_ among the documents on the content node. Can be configured using [rank-properties](../reference/ranking/rank-feature-configuration.html#bm25). The actual index statistic is also available as the [averageFieldLength(name)](../reference/ranking/rank-features.html#averageFieldLength(name)) rank feature. 
- k1: A parameter used to limit how much a single query term can affect the score for document _D_. With a higher value the score for a single term can continue to go up relatively more when more occurrences for that term exists. Default value is 1.2. Can be configured using [rank-properties](../reference/ranking/rank-feature-configuration.html#bm25). 
- b: A parameter used to control the effect of the field length of field _t_ compared to the average field length. Default value is 0.75. Can be configured using [rank-properties](../reference/ranking/rank-feature-configuration.html#bm25). 

## Example

In the following example we have an indexed string field _content_, and a rank profile using the _bm25_ rank feature. Note that the field must be enabled for usage with the bm25 feature by setting the _enable-bm25_ flag in the [index](../reference/schemas/schemas.html#index) section of the field definition.

```vespa-schema-language
schema example {
  document example {
    field content type string {
      indexing: index | summary
      index: enable-bm25
    }
  }
  rank-profile default {
    first-phase {
      expression {
        bm25(content)
      }
    }
  }
}
```

If the _enable-bm25_ flag is turned on after documents are already fed then [proton](../content/proton.html) performs a [memory index flush](../content/proton.html#memory-index-flush) followed by a [disk index fusion](../content/proton.html#disk-index-fusion) to prepare the posting lists for use with _bm25_.

Use the [custom component state API](../content/proton.html#custom-component-state-api) on each content node and examine `pending_urgent_flush` to determine if the preparation is still ongoing:

```
/state/v1/custom/component/documentdb/mydoctype/subdb/ready/index
```

## Scoring labeled parts of the query

`bm25(content)` sums the contribution of every query term searching _content_. When a query is built from several parts, it is often useful to score those parts separately. This is done by attaching a [label](multivalue-query-operators.html#raw-scores-and-query-item-labeling) to the query items, using the [label](../reference/querying/yql.html#label) annotation in YQL, and referring to that label from the rank profile:

```vespa-yql
select * from example where
    ({label:"must"}content contains "vespa") and
    ({label:"nice"}(content contains "ranking" or content contains "relevance"))
```

A label set on an operator enclosing others, as on the _or_ above, is inherited by every term inside it, so a label can be given per clause instead of per term.

The [bm25(field: _fieldname_, label: _label_)](../reference/ranking/rank-features.html#bm25) rank feature scores only the terms carrying the given label:

```vespa-schema-language
rank-profile labeled {
  first-phase {
    expression: bm25(field: content, label: must) + 0.5 * bm25(field: content, label: nice)
  }
}
```

### One score per label

With many labels, or when the labels are not known when the schema is written, use [bm25\_for\_labels(field)](../reference/ranking/rank-features.html#bm25_for_labels) instead. It returns a `tensor<float>(label{})` with one cell per label that scores in the field, holding the sum of the BM25 scores of that label's terms:

```vespa-schema-language
rank-profile labels {
  inputs {
    query(label_weights) tensor<float>(label{})
  }
  first-phase {
    expression: sum(bm25_for_labels(content) * query(label_weights))
  }
  match-features {
    bm25_for_labels(content)
  }
}
```

For the query above, the match feature might be returned as:

```
"bm25_for_labels(content)": {
  "type": "tensor<float>(label{})",
  "cells": {
    "must": 0.7568,
    "nice": 0.3213
  }
}
```

Other typical uses are `reduce(bm25_for_labels(content), max, label)` to rank by the best scoring labeled part, or feeding the tensor to a machine-learned model. A label only gets a cell when it actually scores, and terms without a label are not included at all, so `reduce(bm25_for_labels(content), sum, label)` equals `bm25(content)` only when every scoring term carries exactly one label.

 **Note:** A single label can be picked out with `bm25_for_labels(content){label:must}`, but `bm25(field: content, label: must)` is faster, as it does not compute the full tensor.

 Copyright © 2026 - [Cookie Preferences](#)

