title: 'Reranking' sidebar_label: 'Reranking' description: 'Rerank search results using dedicated reranker models or LLM-as-reranker for improved relevance.' sidebar_position: 4 tags:
Reranking reorders a set of candidate results — from vector_search, text_search, rrf, or a plain table — using a dedicated reranker model. This produces more relevant rankings than the initial retrieval scores alone.
rerank() UDTF sends each candidate's text to a reranker model alongside the query.This two-stage pattern (retrieve then rerank) is standard in modern search and RAG pipelines.
Define dedicated reranker models in the rerankers: section of the spicepod. Supported providers:
| Provider prefix | Description |
|---|---|
cohere: | Cohere Rerank API (e.g., cohere:rerank-v3.5) |
voyage: | Voyage Rerank API (e.g., voyage:rerank-2) |
jina: | Jina Rerank API (e.g., jina:jina-reranker-v2-base-multilingual) |
http:// / https:// | Any HTTP endpoint implementing the standard rerank API schema |
huggingface: (or hf:) | A cross-encoder reranker downloaded from Hugging Face and run locally, in-process (e.g. huggingface:huggingface.co/BAAI/bge-reranker-base) |
file: | A cross-encoder reranker loaded locally from a directory of model artifacts (e.g. file:/models/bge-reranker-base) |
The huggingface: and file: prefixes run a cross-encoder reranker in-process instead of calling a hosted API. file: uses local artifacts only. huggingface: downloads model artifacts from the Hugging Face Hub, then runs scoring locally. Both are included in the default spiced build.
Both accept the same two tuning parameters:
| Parameter | Description | Default |
|---|---|---|
max_seq_length | Maximum sequence length for the (query, document) pair. When unset, the model's own configured maximum applies. | - |
truncate | How to handle a pair longer than the maximum sequence length: none rejects the request with an input-validation error, end discards the end of the pair, start discards the start. Matched case-insensitively. | none |
huggingface: rerankers additionally accept hf_token (also spelled api_key) for private or gated repositories.
Any registered chat model can also be used as a reranker without additional configuration. When a model name resolves to a chat model instead of a dedicated reranker, Spice wraps it in an LLM-based reranking adapter.
The strategy parameter controls how the LLM scores documents:
listwise (default): sends all candidates in a single prompt and asks the LLM to rank them.pointwise: sends each candidate individually and asks the LLM to score it.For the complete parameter reference, see Reranking SQL Reference (opens in a new tab).
The query is automatically extracted from the nested search UDTFs — no need to specify query explicitly.
When reranking a plain table (not a search UDTF), provide the query explicitly: