Skip to main content

Reranking

This page covers reranking queries for re-sorting lists of candidate items. For query fundamentals, see Query Basics.

A reranking query takes a list of candidate items and re-sorts them. Use reranking when you have candidates from an external source (e.g., a search engine, a catalog filter, or business logic) and want to reorder them.

Reranking is different from a full rank query - it only scores and reorders the provided candidates rather than retrieving new ones.

For reranking, you typically want to use a more heavy-weight scoring model like click_through_rate or similar models that can accurately predict user engagement on a smaller set of candidates.

Text reranking strategies​

Reranking commonly uses:

  • Trained scoring models like click_through_rate.
  • Zero-shot text rerankers like colbert_v2() and cross_encoder().
  • Rank fusion patterns like RRF and linear interpolation.

The reference documentation for these scoring expressions lives in ShapedQL:

Example:

SELECT *
FROM ids($candidate_item_ids)
ORDER BY score(expression='colbert_v2(item, $params.query)')
LIMIT 20

Rerank by item IDs​

Prerequisites​

  1. An engine configured with item data
  2. A trained scoring model (e.g., click_through_rate)
  3. A list of candidate item IDs to rerank
  4. Optionally, a user ID for personalized reranking

Query example​

Use the ids retriever to rerank a list of known items with a scoring model:

SELECT *
FROM ids($candidate_item_ids)
ORDER BY score(expression='click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 10

Reranking with model ensembles​

Combine multiple scoring models when reranking to balance different signals:

SELECT *
FROM ids($candidate_item_ids)
ORDER BY score(expression='0.6 * click_through_rate + 0.4 * conversion_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 10

Reranking with diversity​

You can also add diversity reordering to ensure variety in the results:

SELECT *
FROM ids($candidate_item_ids)
ORDER BY score(expression='click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
REORDER BY diversity(0.3)
LIMIT 10

Using item attributes in reranking​

Incorporate item attributes like price, rating, or review count into reranking to boost or penalize items based on business logic:

SELECT *
FROM ids($candidate_item_ids)
ORDER BY score(expression='click_through_rate - 0.05 * item.price + 0.2 * item.rating + 0.15 * item.review_count', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 10

Rerank by item attributes​

Prerequisites​

  1. An engine configured with item data
  2. A trained scoring model (e.g., click_through_rate)
  3. A list of candidate item attribute dictionaries
  4. Optionally, a user ID for personalized reranking

Query example​

Use the candidate_attributes retriever when you need to rerank items that aren't in your catalog - for example, items from an external API or newly created items:

SELECT *
FROM candidate_attributes($item_attributes)
ORDER BY score(expression='click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 10

Combining reranking with retrieval scores​

If your candidates come from a retrieval step (e.g., search or similarity), you can blend retrieval scores with model predictions:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50,
                 name='search')
WHERE item_id IN ($candidate_item_ids)
ORDER BY score(expression='0.5 * retrieval.search + 0.5 * click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 10

When to use each approach​

ApproachUse when
Rerank by IDsItems exist in your catalog and have stored features
Rerank by attributesItems are external, temporary, or newly created without catalog entries