> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Watsonx Reranker

> Rerank LanceDB search results with the IBM watsonx.ai text rerank API. Supports vector, FTS, and hybrid search with configurable models, projects, and spaces.

# Watsonx Reranker

This reranker uses the [IBM watsonx.ai](https://cloud.ibm.com/docs/apis/watsonx-ai#text-rerank) text rerank API to reorder search results. Pass `WatsonxReranker()` to the `rerank()` method on a query. Credentials come from the `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` (or `WATSONX_SPACE_ID`) environment variables, or can be passed explicitly as arguments.

> **Note:** Supported query types – Hybrid, Vector, and FTS.

```shell theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
pip install ibm-watsonx-ai
```

import os

import lancedb
from lancedb.embeddings import get\_registry
from lancedb.pydantic import LanceModel, Vector
from lancedb.rerankers import WatsonxReranker

embedder = get\_registry().get("sentence-transformers").create()
db = lancedb.connect("\~/.lancedb")

class Schema(LanceModel):
    text: str = embedder.SourceField()
    vector: Vector(embedder.ndims()) = embedder.VectorField()

data = \[
    \{"text": "hello world"},
    \{"text": "goodbye world"},
]
tbl = db.create\_table("test", schema=Schema, mode="overwrite")
tbl.add(data)

\# Credentials pulled from WATSONX\_API\_KEY and WATSONX\_PROJECT\_ID (or WATSONX\_SPACE\_ID)
reranker = WatsonxReranker(
    api\_key=os.environ\["WATSONX\_API\_KEY"],
    project\_id=os.environ\["WATSONX\_PROJECT\_ID"],
)

\# Run vector search with a reranker
result = tbl.search("hello").rerank(reranker=reranker).to\_list()

\# Run FTS search with a reranker
result = tbl.search("hello", query\_type="fts").rerank(reranker=reranker).to\_list()

\# Run hybrid search with a reranker
tbl.create\_fts\_index("text", replace=True)
result = (
    tbl.search("hello", query\_type="hybrid").rerank(reranker=reranker).to\_list()
)


## Accepted Arguments

| Argument | Type | Default | Description |
| - | - | - | - |
| `model_name` | `str` | `"cross-encoder/ms-marco-minilm-l-12-v2"` | The rerank model ID. See [supported rerank models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx#rerank). |
| `column` | `str` | `"text"` | The name of the table column to use as document input. |
| `top_n` | `int` | `None` | The number of results to return. If `None`, all results are returned. |
| `return_score` | `str` | `"relevance"` | Options are `"relevance"` or `"all"`. Controls which score columns are kept on the result. |
| `api_key` | `str` | `None` | IBM Cloud API key. Falls back to the `WATSONX_API_KEY` environment variable. |
| `project_id` | `str` | `None` | watsonx.ai project ID. Falls back to `WATSONX_PROJECT_ID`. Mutually exclusive with `space_id`. |
| `space_id` | `str` | `None` | watsonx.ai deployment space ID. Falls back to `WATSONX_SPACE_ID`. Mutually exclusive with `project_id`. |
| `url` | `str` | `"https://us-south.ml.cloud.ibm.com"` | watsonx.ai service URL. |
| `truncate_input_tokens` | `int` | `None` | Truncate each document to this many tokens before scoring. |

> [!NOTE]
>
> You must supply exactly one of `project_id` or `space_id` (either as an argument or via its environment variable). Setting both, or neither, raises a `ValueError`.

## Supported scores for each query type

You can specify the type of scores you want the reranker to return. The following are the supported scores for each query type:

### Hybrid Search

| `return_score` | Status | Description |
| - | - | - |
| `relevance` | ✅ Supported | Results only have the `_relevance_score` column. |
| `all` | ❌ Not Supported | Results have vector(`_distance`) and FTS(`score`) along with Hybrid Search score(`_relevance_score`). |

### Vector Search

| `return_score` | Status | Description |
| - | - | - |
| `relevance` | ✅ Supported | Results only have the `_relevance_score` column. |
| `all` | ✅ Supported | Results have vector(`_distance`) along with Hybrid Search score(`_relevance_score`). |

### FTS Search

| `return_score` | Status | Description |
| - | - | - |
| `relevance` | ✅ Supported | Results only have the `_relevance_score` column. |
| `all` | ✅ Supported | Results have FTS(`score`) along with Hybrid Search score(`_relevance_score`). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.