Reranking

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.

Rerank by item IDs

Prerequisites

1. An engine configured with item data
2. A list of candidate item IDs to rerank

Query example

Use the candidate_ids retrieve type to rerank a list of known items:

{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "candidate_ids",
        "item_ids": ["item_1", "item_2", "item_3", "item_4", "item_5"]
      }
    ]
  }
}

With parameters

You can also pass the item IDs as a parameter:

{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "candidate_ids",
        "item_ids": "$parameters.candidate_item_ids"
      }
    ]
  },
  "parameters": {
    "candidate_item_ids": ["item_1", "item_2", "item_3"]
  }
}

Rerank by item attributes

Prerequisites

1. An engine configured with item data
2. A list of candidate item attribute dictionaries

Query example

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

{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "candidate_attributes",
        "item_attributes": [
          { "title": "Product A", "category": "electronics" },
          { "title": "Product B", "category": "clothing" }
        ]
      }
    ]
  }
}

When to use each approach

Approach	Use when
Rerank by IDs	Items exist in your catalog and have stored features
Rerank by attributes	Items are external, temporary, or newly created without catalog entries