---
title: BM25 Scoring
---

## Basic Usage

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

```sql
SELECT id, paradedb.score(id)
FROM mock_items
WHERE description @@@ 'shoes'
ORDER BY paradedb.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, paradedb.score(id)
FROM mock_items
WHERE description @@@ 'keyboard' OR rating < 2
ORDER BY paradedb.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, paradedb.score(o.order_id) + paradedb.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>;
```