spiceai/docs

spiceai/

docs

Help Login

evgenii/docs-spicepod-v2

Edit on GitHub

Fork

/docs/website/versioned_docs/version-2.0.x/features/search/rerank.md

spiceai/docs | Spice Cloud Platform

evgenii/docs-spicepod-v2

Edit on GitHub

Fork

/docs/website/versioned_docs/version-2.0.x/features/search/rerank.md

spiceai/docs/README.md

title: 'Reranking' sidebar_label: 'Reranking' description: 'Rerank search results using dedicated reranker models or LLM-as-reranker for improved relevance.' sidebar_position: 4 tags:

search
features

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.

How It Works

An initial search (vector, full-text, or hybrid) retrieves candidate documents.
The rerank() UDTF sends each candidate's text to a reranker model alongside the query.
The reranker scores each document for relevance and returns them in order.

This two-stage pattern (retrieve then rerank) is standard in modern search and RAG pipelines.

Configuration

Reranker Models

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

LLM-as-Reranker

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.

SQL Usage

For the complete parameter reference, see Reranking SQL Reference.

Examples

Hybrid Recall + Rerank

The query is automatically extracted from the nested search UDTFs — no need to specify query explicitly.

Bare-Table Rerank

When reranking a plain table (not a search UDTF), provide the query explicitly:

Custom LLM Prompt

rerankers:
  - from: cohere:rerank-v3.5
    name: cohere_rr
    params:
      api_key: ${secrets:COHERE_API_KEY}

  - from: voyage:rerank-2
    name: voyage_rr
    params:
      api_key: ${secrets:VOYAGE_API_KEY}

  - from: jina:jina-reranker-v2-base-multilingual
    name: jina_rr
    params:
      api_key: ${secrets:JINA_API_KEY}

  - from: https://rerank.internal/v1/rerank
    name: byo_rr
    params:
      api_key: ${secrets:INTERNAL_RR_KEY}  # optional

rerankers:
  - from: cohere:rerank-v3.5
    name: cohere_rr
    params:
      api_key: ${secrets:COHERE_API_KEY}

  - from: voyage:rerank-2
    name: voyage_rr
    params:
      api_key: ${secrets:VOYAGE_API_KEY}

  - from: jina:jina-reranker-v2-base-multilingual
    name: jina_rr
    params:
      api_key: ${secrets:JINA_API_KEY}

  - from: https://rerank.internal/v1/rerank
    name: byo_rr
    params:
      api_key: ${secrets:INTERNAL_RR_KEY}  # optional

models:
  - from: openai:gpt-4o-mini
    name: gpt_mini

models:
  - from: openai:gpt-4o-mini
    name: gpt_mini

SELECT * FROM rerank(
  vector_search(kb, 'onboarding checklist', limit => 40),
  document => 'content',
  model    => 'gpt_mini',       -- resolves to the registered chat model
  strategy => 'pointwise',      -- or 'listwise' (default)
  limit    => 10
);

SELECT * FROM rerank(
  vector_search(kb, 'onboarding checklist', limit => 40),
  document => 'content',
  model    => 'gpt_mini',       -- resolves to the registered chat model
  strategy => 'pointwise',      -- or 'listwise' (default)
  limit    => 10
);

SELECT * FROM rerank(
  <input>,
  document => '<column>',
  model    => '<reranker_name>',
  limit    => <n>
);

SELECT * FROM rerank(
  <input>,
  document => '<column>',
  model    => '<reranker_name>',
  limit    => <n>
);

SELECT * FROM rerank(
  rrf(
    vector_search(docs, 'delta lake time travel', limit => 50),
    text_search(docs, 'delta lake time travel', limit => 50)
  ),
  document => 'content',
  model    => 'cohere_rr',
  limit    => 10
);

SELECT * FROM rerank(
  rrf(
    vector_search(docs, 'delta lake time travel', limit => 50),
    text_search(docs, 'delta lake time travel', limit => 50)
  ),
  document => 'content',
  model    => 'cohere_rr',
  limit    => 10
);

SELECT * FROM rerank(
  tickets,
  query    => 'auth failures',
  document => 'body',
  model    => 'voyage_rr',
  limit    => 5
);

SELECT * FROM rerank(
  tickets,
  query    => 'auth failures',
  document => 'body',
  model    => 'voyage_rr',
  limit    => 5
);

SELECT * FROM rerank(
  vector_search(kb, 'onboarding checklist', limit => 40),
  document        => 'content',
  model           => 'gpt_mini',
  strategy        => 'pointwise',
  prompt_template => 'Rate 0-1: is this useful for a new hire?\nQuery: {query}\nDoc: {document}',
  limit           => 10
);

SELECT * FROM rerank(
  vector_search(kb, 'onboarding checklist', limit => 40),
  document        => 'content',
  model           => 'gpt_mini',
  strategy        => 'pointwise',
  prompt_template => 'Rate 0-1: is this useful for a new hire?\nQuery: {query}\nDoc: {document}',
  limit           => 10
);