Text reranking
==============

Use the ``aidb.rerank_text()`` function to reorder a set of candidate
text passages by their relevance to a query. Reranking is typically
applied as a post-retrieval step — after an initial set of candidates
has been retrieved from a knowledge base — to surface the most relevant
results at the top.

**Step 1: Register a reranking model**

.. code:: sql

   - - Remote: NVIDIA NIM
   SELECT aidb.create_model(
       my_reranker,
       nim_reranking,
       config => aidb.nim_reranking_config(
           api_key => nvapi-...,  -- or use create_models own credentials_env parameter instead, to avoid storing this
           model   => nvidia/nv-rerankqa-mistral-4b-v3
       )
   );

   - - Local: llama.cpp (GGUF), no API key required
   SELECT aidb.create_model(
       my_reranker,
       llamacpp_reranking,
       config => jsonb_build_object(
           model, gpustack/bge-reranker-v2-m3-GGUF,
           model_file, bge-reranker-v2-m3-Q4_K_M.gguf,
           n_ctx, 2048
       )
   );

**Step 2: Rerank a set of candidates**

.. code:: sql

   SELECT * FROM aidb.rerank_text(
       model_name => my_reranker,
       query      => What is retrieval-augmented generation?,
       input      => ARRAY[
           RAG combines retrieval and generation to produce grounded answers.,
           Vector databases store high-dimensional embeddings for similarity search.,
           RAG systems retrieve relevant documents before generating a response.
       ]
   ) ORDER BY logit_score DESC;

   __OUTPUT__
                                 text                              | logit_score | id
   - ---------------------------------------------------------------+-------------+----
    RAG systems retrieve relevant documents before generating ...  |        0.97 |  2
    RAG combines retrieval and generation to produce grounded ...  |        0.91 |  0
    Vector databases store high-dimensional embeddings for ...     |        0.43 |  1
   (3 rows)

The ``id`` column is the zero-based index of each string in the
``input`` array, so you can join back to the original data.

For the full parameter reference, see :ref:`Models reference <Models reference>`  .

Using reranking after knowledge base retrieval
----------------------------------------------

A typical pattern is to retrieve an initial candidate set from a
knowledge base and then rerank the results:

.. code:: sql

   WITH candidates AS (
       SELECT key, value
       FROM aidb.retrieve_text(my_kb, What is RAG?, topk => 20)
   )
   SELECT c.key, c.value, r.logit_score
   FROM candidates c
   JOIN aidb.rerank_text(
       model_name => my_reranker,
       query      => What is RAG?,
       input      => ARRAY(SELECT value FROM candidates ORDER BY key)
   ) r ON r.text = c.value
   ORDER BY r.logit_score DESC
   LIMIT 5;

!!!note Reranking models score passages against a query but don’t
generate text. To register a reranking model, use the appropriate
:ref:`Model config helpers <Model config helpers>`  for your provider. For example,
``aidb.nim_reranking_config()`` for NVIDIA NIM reranking endpoints.
``llamacpp_reranking`` has no config helper yet; build ``config`` with
``jsonb_build_object()`` instead, as shown above. See :ref:`Local models <Local models>`  .

!!!note ``logit_score`` ’s scale depends on the provider: some return a
normalized score in a fixed range (as in the example above), while
``llamacpp_reranking`` returns a raw, unbounded model logit. Compare
scores within one ``aidb.rerank_text()`` call and provider, not across
different providers or calls.