Reranking Results

Reranking reorders a set of candidate documents by relevance to a query. Use it after an initial retrieval step (vector search, keyword search, or a combined approach) to surface the most relevant results at the top.

Basic usage

python

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")

documents = [
    {"text": "Apple is a technology company."},
    {"text": "The apple is a popular fruit."},
    {"text": "Pinecone is a vector database."},
]

result = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="Tell me about tech companies",
    documents=documents,
)

for doc in result.data:
    print(doc.index, doc.score, doc.document)

Pass plain strings and they are automatically wrapped as {"text": ...}:

python

result = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="machine learning",
    documents=["Neural networks are a type of ML model.", "Python is a programming language."],
)

Response: RerankResult

rerank returns a {class}~pinecone.models.inference.rerank.RerankResult containing:

.data — list of {class}~pinecone.models.inference.rerank.RankedDocument, ordered by descending score.
.model — model name used.
.usage.rerank_units — rerank units consumed.

Each {class}~pinecone.models.inference.rerank.RankedDocument has:

.index — the original position of the document in the input list.
.score — relevance score (higher is more relevant).
.document — the original document dict (None when return_documents=False).

top_n: return only the best results

Pass top_n to receive only the top N documents after reranking:

python

result = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="search query",
    documents=documents,
    top_n=3,
)
assert len(result.data) == 3

rank_fields: choose which field to score on

By default the reranker scores the "text" field. Override with rank_fields:

python

result = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="quarterly earnings",
    documents=[
        {"title": "Apple Q4 2024 results", "body": "Revenue grew 6% year over year."},
        {"title": "Banana prices rise", "body": "Fruit prices hit new highs."},
    ],
    rank_fields=["title", "body"],
)

Using the RerankModel enum

Use the {class}~pinecone.models.enums.RerankModel enum for tab-completion and typo safety:

python

from pinecone import Pinecone
from pinecone.client.inference import Inference

pc = Pinecone(api_key="your-api-key")

result = pc.inference.rerank(
    model=Inference.RerankModel.Bge_Reranker_V2_M3,
    query="machine learning",
    documents=documents,
)

Reranking in a pipeline

A typical two-stage retrieval pipeline: fetch candidates from Pinecone, then rerank.

python

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
index = pc.index("product-search")

# Stage 1: vector retrieval
query_embedding = pc.inference.embed(
    model="multilingual-e5-large",
    inputs=["best noise-cancelling headphones"],
    parameters={"input_type": "query"},
).data[0].values

matches = index.query(vector=query_embedding, top_k=20, include_metadata=True)
candidates = [
    {"text": m.metadata.get("description", ""), "id": m.id}
    for m in matches.matches
]

# Stage 2: rerank
result = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query="best noise-cancelling headphones",
    documents=candidates,
    rank_fields=["text"],
    top_n=5,
)

for doc in result.data:
    print(doc.score, doc.document)

For integrated indexes, pass rerank directly inside {meth}~pinecone.Index.search — see {doc}/how-to/integrated-records.

List available reranking models

python

models = pc.inference.model.list(type="rerank")
print(models.names())