---
title: BM25 Scoring
noindex: true
---

<Danger>
  **Legacy Docs:** This page describes our legacy API. It will be deprecated in
  a future version. Please use the [v2 API](/) where possible.
</Danger>

## Basic Usage

BM25 scores measure how relevant a score is for a given query. Higher scores indicate higher relevance.
The `pdb.score(<key_field>)` function can be added to any query where an `@@@` operator is present.

```sql
SELECT id, pdb.score(id)
FROM mock_items
WHERE description @@@ 'shoes'
ORDER BY pdb.score(id)
LIMIT 5;
```

In order for a field to be factored into the BM25 score, it must be present in the BM25 index. For instance,
consider this query:

```sql
SELECT id, pdb.score(id)
FROM mock_items
WHERE description @@@ 'keyboard' OR rating < 2
ORDER BY pdb.score(id)
LIMIT 5;
```

While BM25 scores will be returned as long as `description` is indexed, including `rating` in the BM25 index definition will allow results matching
`rating < 2` to rank higher than those that do not match.

## Joined Scores

The following query demonstrates how to compute a "combined BM25 score" over a joined search. It joins `mock_items` with `orders`,
which were both created in the [quickstart](/documentation/getting-started/quickstart).

```sql
SELECT o.order_id, pdb.score(o.order_id) + pdb.score(m.id) as score
FROM orders o
JOIN mock_items m ON o.product_id = m.id
WHERE o.customer_name @@@ 'Johnson' AND (m.description @@@ 'shoes' OR m.description @@@ 'running')
ORDER BY score DESC, o.order_id
LIMIT 5;
```

## Score Refresh

The scores generated by the BM25 index may be influenced by dead rows that have not been cleaned up by the `VACUUM` process.

Running `VACUUM` on the underlying table will remove all dead rows from the index and ensures that only rows visible to the current
transaction are factored into the BM25 score.

```sql
VACUUM <table_name>;
```