rerank

Use the rerank operation to rerank search results based on relevance to a query.

Uses a reranking model to score and reorder documents relative to a query. This improves search quality by performing a more detailed comparison between the query and each candidate document.

Parameters

Parameter	Type	Value Range	Required	Default	Description	Notes
query	str	Non-empty string	Yes	No default	Search query text used as the reranking prompt.	Empty values raise a validation error.
documents	list[str]	Non-empty array of strings	Yes	No default	Candidate documents to rerank. Typically the results from query().	Must contain at least one string document.
model_name	str	Valid model identifier	Yes	No default	Name of the loaded reranking model.	Model must exist in the database schema.
model_params	dict	Object or NULL	No	None	Rerank options for the model call.	Supports top_n.
debug_flags	dict	Object or NULL	No	None	Debug or tracing flags for detailed logging.	Optional; omit unless diagnostics are needed.

model_params fields

Field	Type	Value Range	Required	Description	Notes
top_n	int	> 0	No	Number of top reranked results to return.	When omitted, the response can include the full reranked document list.

Raises Exception – If the model is not loaded or inputs are invalid.

First, perform initial search

search_results = client.query(
    table_name='documents',
    query_by={'text': 'machine learning'},
    top_k=20
)

Then rerank for better relevance

reranked = client.rerank(
    query='machine learning applications in healthcare',
    documents=[
        result.metadata["content"]
        for result in search_results.items
        if result.metadata and "content" in result.metadata
    ],
    model_name='cohere-rerank-3.5',
    model_params={'top_n': 5}
)
for item in reranked.items:
    original = search_results.items[item.index]
    print(f"{item.score:.3f} - {original.metadata['content']}")

Return type RerankResponse

Returns RerankResponse with reranked items under items. Example:

{
    "items": [
        {
            "index": 0,
            "score": 0.82
        }
    ]
}