---
title: BM25 Scoring
description: BM25 scores sort the result set by relevance
canonical: https://www.paradedb.com/docs/reference/full-text/score
---
For optimal performance on top K queries ordered by BM25 score, consider
setting `pnorms=true` when creating your index. See [Faster BM25
Queries](/reference/indexing/faster-bm25-queries) for setup and tradeoffs.
Available in versions `0.26.0` and above.
BM25 scores measure how relevant a document is for a given query. Higher scores indicate higher relevance.
To adjust term frequency saturation and length normalization per field, see [BM25 Parameters](/reference/indexing/create-index#bm25-parameters).
## Basic Usage
The `pdb.score()` function produces a BM25 score and can be added to any query where any of the ParadeDB operators are present.
Pass an indexed column from the table being searched, such as `id`.
```sql SQL
SELECT id, pdb.score(id)
FROM mock_items
WHERE description ||| 'shoes'
ORDER BY pdb.score(id) DESC
LIMIT 5;
```
```ts Drizzle
import { desc } from "drizzle-orm";
import { search } from "@paradedb/drizzle-paradedb";
await db
.select({
id: mockItems.id,
score: search.score(mockItems.id),
})
.from(mockItems)
.where(search.matchAny(mockItems.description, "shoes"))
.orderBy(desc(search.score(mockItems.id)))
.limit(5);
```
```python Django
from paradedb import MatchAny, ParadeDB, Score
MockItem.objects.filter(
description=ParadeDB(MatchAny('shoes'))
).annotate(
score=Score()
).values('id', 'score').order_by('-score')[:5]
```
```python SQLAlchemy
from sqlalchemy import desc, select
from sqlalchemy.orm import Session
from paradedb.sqlalchemy import pdb, search
stmt = (
select(MockItem.id, pdb.score(MockItem.id).label("score"))
.where(search.match_any(MockItem.description, "shoes"))
.order_by(desc("score"))
.limit(5)
)
with Session(engine) as session:
session.execute(stmt).all()
```
```ruby Rails
MockItem.search(:description)
.match_any("shoes")
.with_score
.select(:id)
.order(search_score: :desc)
.limit(5)
```
```cs EF Core
await dbContext
.MockItems.Where(item => EF.Functions.MatchAny(item.Description, "shoes"))
.Select(item => new { item.Id, Score = EF.Functions.Score(item.Id) })
.OrderByDescending(item => item.Score)
.Take(5)
.ToListAsync();
```
In order for a field to be factored into the BM25 score, it must be present in the ParadeDB index. For instance,
consider this query:
```sql SQL
SELECT id, pdb.score(id)
FROM mock_items
WHERE description ||| 'keyboard' OR rating < 2
ORDER BY pdb.score(id) DESC
LIMIT 5;
```
```ts Drizzle
import { desc, lt, or } from "drizzle-orm";
import { search } from "@paradedb/drizzle-paradedb";
await db
.select({
id: mockItems.id,
score: search.score(mockItems.id),
})
.from(mockItems)
.where(
or(
search.matchAny(mockItems.description, "keyboard"),
lt(mockItems.rating, 2),
),
)
.orderBy(desc(search.score(mockItems.id)))
.limit(5);
```
```python Django
from django.db.models import Q
from paradedb import MatchAny, ParadeDB, Score
MockItem.objects.filter(
Q(description=ParadeDB(MatchAny('keyboard'))) | Q(rating__lt=2)
).annotate(
score=Score()
).values('id', 'score').order_by('-score')[:5]
```
```python SQLAlchemy
from sqlalchemy import desc, or_, select
from sqlalchemy.orm import Session
from paradedb.sqlalchemy import pdb, search
stmt = (
select(MockItem.id, pdb.score(MockItem.id).label("score"))
.where(or_(search.match_any(MockItem.description, "keyboard"), MockItem.rating < 2))
.order_by(desc("score"))
.limit(5)
)
with Session(engine) as session:
session.execute(stmt).all()
```
```ruby Rails
MockItem.search(:description)
.match_any("keyboard")
.or(MockItem.where(rating: ...2))
.with_score
.select(:id)
.order(search_score: :desc)
.limit(5)
```
```cs EF Core
await dbContext
.MockItems.Where(item =>
EF.Functions.MatchAny(item.Description, "keyboard") || item.Rating < 2
)
.Select(item => new { item.Id, Score = EF.Functions.Score(item.Id) })
.OrderByDescending(item => item.Score)
.Take(5)
.ToListAsync();
```
While BM25 scores will be returned as long as `description` is indexed, including `rating` in the ParadeDB index definition will allow results matching
`rating < 2` to rank higher than those that do not match.
A row-level security policy restricts which rows a user may see and adds nothing to the score. A row scores the same for every user and in every plan, whatever the policy's shape.
## Joined Scores
First, let's create a second table called `orders` that can be joined with `mock_items`:
```sql
CALL paradedb.create_paradedb_test_table(
schema_name => 'public',
table_name => 'orders',
table_type => 'Orders'
);
ALTER TABLE orders
ADD CONSTRAINT foreign_key_product_id
FOREIGN KEY (product_id)
REFERENCES mock_items(id);
CREATE INDEX orders_idx ON orders
USING paradedb (order_id, product_id, order_quantity, order_total, customer_name);
```
Next, let's compute a combined BM25 score over a join across both tables:
```sql SQL
SELECT
o.order_id,
o.customer_name,
m.description,
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'
OR m.description ||| 'running shoes'
ORDER BY score DESC, o.order_id
LIMIT 5;
```
```ts Drizzle
import { desc, eq, or, sql } from "drizzle-orm";
import { search } from "@paradedb/drizzle-paradedb";
const score =
sql`${search.score(orders.orderId)} + ${search.score(mockItems.id)}`.as(
"score",
);
const results = await db
.select({
orderId: orders.orderId,
customerName: orders.customerName,
description: mockItems.description,
score,
})
.from(orders)
.innerJoin(mockItems, eq(orders.productId, mockItems.id))
.where(
or(
search.matchAny(orders.customerName, "Johnson"),
search.matchAny(mockItems.description, "running shoes"),
),
)
.orderBy(desc(score), orders.orderId)
.limit(5);
```
```python Django
from django.db.models import F, Q
from paradedb import MatchAny, ParadeDB, Score
results = list(
Order.objects.filter(
Q(customer_name=ParadeDB(MatchAny("Johnson")))
| Q(product__description=ParadeDB(MatchAny("running shoes")))
)
.annotate(
score=Score("order_id") + Score("product__description"),
description=F("product__description"),
)
.values("order_id", "customer_name", "description", "score")
.order_by("-score", "order_id")[:5]
)
```
```python SQLAlchemy
from sqlalchemy import or_, select
from sqlalchemy.orm import Session
from paradedb.sqlalchemy import pdb, search
score = (pdb.score(Order.order_id) + pdb.score(MockItem.id)).label("score")
stmt = (
select(Order.order_id, Order.customer_name, MockItem.description, score)
.join(MockItem, MockItem.id == Order.product_id)
.where(
or_(
search.match_any(Order.customer_name, "Johnson"),
search.match_any(MockItem.description, "running shoes"),
)
)
.order_by(score.desc(), Order.order_id)
.limit(5)
)
with Session(engine) as session:
results = session.execute(stmt).all()
```
```ruby Rails
orders = Order.arel_table
products = MockItem.arel_table
score = Arel::Nodes::Addition.new(
Arel::Nodes::NamedFunction.new("pdb.score", [orders[:order_id]]),
Arel::Nodes::NamedFunction.new("pdb.score", [products[:id]])
)
results = Order.joins(:mock_item)
.search(:customer_name).match_any("Johnson")
.or(Order.joins(:mock_item).search(products[:description]).match_any("running shoes"))
.select(orders[:order_id], orders[:customer_name],
products[:description], score.as("score"))
.order(score.desc, orders[:order_id])
.limit(5).to_a
```
```cs EF Core
var results = await (
from order in dbContext.Orders
join item in dbContext.MockItems on order.ProductId equals item.Id
where EF.Functions.MatchAny(order.CustomerName, "Johnson")
|| EF.Functions.MatchAny(item.Description, "running shoes")
let score = EF.Functions.Score(order.OrderId) + EF.Functions.Score(item.Id)
orderby score descending, order.OrderId
select new
{
order.OrderId,
order.CustomerName,
item.Description,
Score = score,
}
).Take(5).ToListAsync();
```
Each `pdb.score()` call evaluates the BM25 score for that table's predicates, and `+` sums the per-table scores in the same way a single-table BM25 query sums its clauses. You can weight one table relative to another with positive multipliers such as `2.0 * pdb.score(m.id) + pdb.score(o.order_id)`. When a joined row does not match an `OR` branch on one table, that table's `pdb.score(...)` returns `0.0`; on null-extended rows of an outer join, `pdb.score(...)` on the unmatched table is `NULL` (wrap it in `COALESCE(pdb.score(...), 0)` when summing).
For pushdown requirements on score-ordered joins, see [Score-Ordered Joins](/reference/joins/overview#score-ordered-joins). For how splitting fields across tables affects BM25 corpus statistics, see [Schema Modeling](/reference/indexing/schema-modeling#how-schema-shape-affects-bm25-scoring).
To combine full text and vector search, where scores operate on different
scales, see [Reciprocal Rank Fusion](/reference/hybrid/rrf).
## Deterministic Sorting
Ordering by `pdb.score` alone is not sufficient to guarantee deterministic query results when there are multiple documents with the same score.
To ensure stable output, we recommend adding a tiebreaker column (such as the primary key) after the score:
```sql
SELECT id, pdb.score(id)
FROM mock_items
WHERE description ||| 'shoes'
ORDER BY pdb.score(id) DESC, id ASC
LIMIT 5;
```
Note that to receive this [Top K optimization](/reference/full-text/top-k), all tiebreaker columns must be indexed.
## Score Explanation
To see how a row got its score, add `pdb.explain_score()` to the query. It takes the same column as `pdb.score`,
and it returns the explanation as `jsonb`.
```sql SQL
SELECT id, pdb.score(id), jsonb_pretty(pdb.explain_score(id))
FROM mock_items
WHERE description ||| 'shoes'
ORDER BY pdb.score(id) DESC, id ASC
LIMIT 1;
```
```ts Drizzle
import { asc, desc, sql } from "drizzle-orm";
import { search } from "@paradedb/drizzle-paradedb";
await db
.select({
id: mockItems.id,
score: search.score(mockItems.id),
explanation: sql`pdb.explain_score(${mockItems.id})`,
})
.from(mockItems)
.where(search.matchAny(mockItems.description, "shoes"))
.orderBy(desc(search.score(mockItems.id)), asc(mockItems.id))
.limit(1);
```
```python Django
from django.db.models import JSONField
from django.db.models.expressions import RawSQL
from paradedb import MatchAny, ParadeDB, Score
MockItem.objects.filter(
description=ParadeDB(MatchAny('shoes'))
).annotate(
score=Score(),
explanation=RawSQL(
'pdb.explain_score(mock_items.id)', [], output_field=JSONField()
),
).values('id', 'score', 'explanation').order_by('-score', 'id')[:1]
```
```python SQLAlchemy
from sqlalchemy import desc, func, select
from sqlalchemy.orm import Session
from paradedb.sqlalchemy import pdb, search
stmt = (
select(
MockItem.id,
pdb.score(MockItem.id).label("score"),
func.pdb.explain_score(MockItem.id).label("explanation"),
)
.where(search.match_any(MockItem.description, "shoes"))
.order_by(desc("score"), MockItem.id)
.limit(1)
)
with Session(engine) as session:
session.execute(stmt).all()
```
```ruby Rails
MockItem.search(:description)
.match_any("shoes")
.with_score
.select(:id, "pdb.explain_score(mock_items.id) AS explanation")
.order(search_score: :desc, id: :asc)
.limit(1)
```
```cs EF Core
await dbContext
.Database.SqlQuery(
$"""
SELECT pdb.explain_score(id)::text AS "Value"
FROM mock_items
WHERE description ||| 'shoes'
ORDER BY pdb.score(id) DESC, id ASC
LIMIT 1
"""
)
.ToListAsync();
```
```ini Expected Response
{
"value": 2.8772602,
"context": [
"Term=Term(field=6, type=Str, \"shoes\")"
],
"details": [
{
"value": 2.2,
"description": "(K1+1)"
},
{
"value": 2.4849067,
"details": [
{
"value": 3.0,
"description": "n, number of docs containing this term"
},
{
"value": 41.0,
"description": "N, total number of docs"
}
],
"description": "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5))"
},
{
"value": 0.52631575,
"details": [
{
"value": 1.0,
"description": "freq, occurrences of term within document"
},
{
"value": 1.2,
"description": "k1, term saturation parameter"
},
{
"value": 0.75,
"description": "b, length normalization parameter"
},
{
"value": 2.0,
"description": "dl, length of field"
},
{
"value": 3.0,
"description": "avgdl, average length of field"
}
],
"description": "freq / (freq + k1 * (1 - b + b * dl / avgdl))"
}
],
"description": "TermQuery, product of..."
}
```
`value` is the score of the row, and `details` holds the parts that make it. For one term, the parts are how rare the term
is in the index (`idf`), how often the row has it (`freq`), and the length of the field against the average length. A query
with several terms has one entry for each term that the row matches.
With [synonyms](/reference/tokenizers/synonyms), a group of single words is one `SynonymQuery` entry. Its `freq` is a sum,
and it lists each word of the group that the row holds.
`pdb.explain_score` has these limits:
- The query has to search the table with a ParadeDB operator, as for `pdb.score`.
- It works in the `SELECT` list, and not in `WHERE`.
- In a join, each call explains the score from the search on its own table, and the query does not use
[join pushdown](/reference/joins/overview).
- It costs more than a score, because ParadeDB reads the terms of the row again. Ask for it on a few rows, for example
with a `LIMIT`.
- The explanation is for you to read while you tune a query. Its keys and its wording can change between releases, so
don't make application code depend on them.
## Score Refresh
The scores generated by the ParadeDB 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 mock_items;
```
This can be automated with [autovacuum](/operate/performance-tuning/overview).
## Scores and Row-Level Security
BM25 scores are computed from statistics over every row in the index, including rows that a row-level security policy hides from the current role. Row-level security filters which rows a query returns, but not the statistics behind their scores, so a score returned to a restricted role can depend on rows that role cannot read.
If scores must not depend on rows a role cannot read, keep those rows in a separate table with its own ParadeDB index, or do not return scores to that role.