Reranking

Reranking modules reorder the search result set according to a different set of criteria or a different (e.g. more expensive) algorithm.

Additional information

Configure reranking

To rerank search results, enable a reranker module for your collection. For details, see the reranker's reference page:

• reranker-cohere
• reranker-transformers

A collection can have multiple rerankers. If multiple reranker modules are enabled, specify the module you want to use in the moduleConfig section of your schema.

Named vectors

Added in v1.24

Any vector-based search on collections with named vectors configured must include a target vector name in the query. This allows Weaviate to find the correct vector to compare with the query vector.

Python (v4)

from weaviate.classes.query import MetadataQuery

reviews = client.collections.get("WineReviewNV")
response = reviews.query.near_text(
    query="a sweet German white wine",
    limit=2,
    target_vector="title_country",  # Specify the target vector for named vector collections
    return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
    print(o.properties)
    print(o.metadata.distance)

Python (v3)

# Unfortunately, named vectors are not suppored in the v3 API / Python client.
# Please upgrade to the v4 API / Python client to use named vectors.

JS/TS (Beta)

let result 
const myCollection = client.collections.get('WineReviewNV');

result = await myCollection.query.nearText(['a sweet German white wine'],{
  limit: 2,
  targetVector: 'title_country',
  returnMetadata: ['distance']
})

for (let object of result.objects) {
  console.log(JSON.stringify(object.properties, null, 2));
  console.log(JSON.stringify(object.metadata?.distance, null, 2));
}

JS/TS

result = await client.graphql
  .get()
  .withClassName('WineReviewNV')
  .withNearText({
    concepts: ['a sweet German white wine'],
    targetVectors: ['title_country'],
  })
  .withLimit(2)
  .withFields('title review_body country')
  .do();

console.log(JSON.stringify(result, null, 2));

GraphQL

{
  Get {
    WineReviewNV(
      limit: 2
      nearText: {
        targetVectors: ["title_country"]
        concepts: ["a sweet German white wine"]
      }
    ) {
      title
      review_body
      country
    }
  }
}

Rerank vector search results

To rerank the results of a vector search, configure the object properties to sort on.

Python (v4)

from weaviate.classes.query import Rerank, MetadataQuery

jeopardy = client.collections.get("JeopardyQuestion")

response = jeopardy.query.near_text(
    query="flying",
    limit=10,
    rerank=Rerank(
        prop="question",
        query="publication"
    ),
    return_metadata=MetadataQuery(score=True)
)

for o in response.objects:
    print(o.properties)
    print(o.metadata.score)

Python (v3)

response = (
    client.query
    .get("JeopardyQuestion", ["question", "answer"])
    .with_near_text({
        "concepts": ["flying"]
    })
    .with_additional("rerank(property: \"answer\" query: \"floating\") { score }")
    .with_limit(10)
    .do()
)

print(json.dumps(response, indent=2))

JS/TS (Beta)

const myCollection = client.collections.get('JeopardyQuestion')

const result = await myCollection.query.nearText(['flying'], {
  limit: 10,
  rerank: {
    property: 'question',
    query: 'publication',
  },
  returnMetadata: ['score']
})

console.log(result.objects)

JS/TS

result = await client.graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withNearText({
    concepts: ['flying'],
  })
  .withFields('question answer _additional { distance rerank(property: "answer" query: "floating") { score } }')
  .withLimit(10)
  .do();

console.log(JSON.stringify(result, null, 2));

GraphQL

{
  Get {
    JeopardyQuestion(
      nearText: {
        concepts: "flying"
      }
      limit: 10
    ) {
      answer
      question
      _additional {
        distance
        rerank(
          property: "answer"
          query: "floating"
        ) {
          score
        }
      }
    }
  }
}

Example response

The response should look like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "_additional": {
            "distance": 0.16765535,
            "rerank": [
              {
                "score": 0.357119
              }
            ]
          },
          "answer": "on their stomachs",
          "question": "W. & O. Wright felt passengers wouldn't mind flying in this position they 1st flew in themselves"
        },
        {
          "_additional": {
            "distance": 0.17639679,
            "rerank": [
              {
                "score": 0.14010079
              }
            ]
          },
          "answer": "a hot air balloon",
          "question": "In 1783 Benjamin Franklin saw the first piloted flight of this type of transport while in Paris"
        },
        {
          "_additional": {
            "distance": 0.1866476,
            "rerank": [
              {
                "score": 0.10631887
              }
            ]
          },
          "answer": "a dirigible",
          "question": "In 1926 Roald Amundsen flew over the North Pole in the Norge, this type of craft"
        },
        {
          "_additional": {
            "distance": 0.18168795,
            "rerank": [
              {
                "score": 0.096705794
              }
            ]
          },
          "answer": "hot air balloons",
          "question": "These in the skies of Albuquerque on October 3, 1999 were a fine example of Charles' Law in action"
        },
        {
          "_additional": {
            "distance": 0.18577725,
            "rerank": [
              {
                "score": 0.096705794
              }
            ]
          },
          "answer": "hot air balloons",
          "question": "During the Cold War, 2 different families escaped over the Berlin Wall using these lighter-than-air vehicles"
        },
        {
          "_additional": {
            "distance": 0.18559676,
            "rerank": [
              {
                "score": 0.037750274
              }
            ]
          },
          "answer": "a limp blimp",
          "question": "An uninflated airship"
        },
        {
          "_additional": {
            "distance": 0.17469394,
            "rerank": [
              {
                "score": 0.036977556
              }
            ]
          },
          "answer": "flying the mail",
          "question": "In 1926 Lindbergh had to parachute out of planes 4 times while employed to do this"
        },
        {
          "_additional": {
            "distance": 0.1847046,
            "rerank": [
              {
                "score": 0.014172366
              }
            ]
          },
          "answer": "Lizards",
          "question": "In the East Indies certain species of this reptile are called flying dragons because they can glide from tree to tree"
        },
        {
          "_additional": {
            "distance": 0.18135852,
            "rerank": [
              {
                "score": 0.0025809042
              }
            ]
          },
          "answer": "Pterodactyl",
          "question": "The name of this prehistoric reptile, the largest known flying animal, means \"wing finger\""
        },
        {
          "_additional": {
            "distance": 0.17872101,
            "rerank": [
              {
                "score": 0.0018386653
              }
            ]
          },
          "answer": "a falcon",
          "question": "The fastest flying animal is the peregrine species of this bird of prey"
        }
      ]
    }
  }
}

Rerank keyword search results

To rerank the results of a keyword search, configure the object properties to sort on.

Python (v4)

from weaviate.classes.query import Rerank, MetadataQuery

jeopardy = client.collections.get("JeopardyQuestion")

response = jeopardy.query.bm25(
    query="paper",
    limit=10,
    rerank=Rerank(
        prop="question",
        query="publication"
    ),
    return_metadata=MetadataQuery(score=True)
)

for o in response.objects:
    print(o.properties)
    print(o.metadata.rerank_score)

Python (v3)

response = (
    client.query
    .get("JeopardyQuestion", ["question", "answer"])
    .with_bm25(
      query="paper"
    )
    .with_additional("rerank(property: \"question\" query: \"publication\") { score }")
    .with_limit(10)
    .do()
)

print(json.dumps(response, indent=2))

JS/TS (Beta)

const myCollection = client.collections.get('JeopardyQuestion')

const result = await myCollection.query.bm25(['paper'], {
  limit: 10,
  rerank: {
    property: 'question',
    query: 'publication',
  },
  returnMetadata: ['score']
})

console.log(result.objects)

JS/TS

result = await client.graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withBm25({
    query: 'paper',
  })
  .withFields('question answer _additional { distance rerank(property: "question" query: "publication") { score } }')
  .withLimit(10)
  .do();

console.log(JSON.stringify(result, null, 2));

GraphQL

{
  Get {
    JeopardyQuestion(
      bm25: {
        query: "paper"
      }
      limit: 10
    ) {
      answer
      question
      _additional {
        distance
        rerank(
          property: "question"
          query: "publication"
        ) {
          score
        }
      }
    }
  }
}

Example response

The response should look like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.64957863
              }
            ],
            "score": "1.917839"
          },
          "answer": "Albert Einstein",
          "question": "His 1905 paper \"On the Electrodynamics of Moving Bodies\" contained his special Theory of Relativity"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.42018318
              }
            ],
            "score": "1.8317645"
          },
          "answer": "Mark Twain",
          "question": "In 1852 his story \"The Dandy Frightening the Squatter\" appeared in The Carpet-Bag, a humorous paper"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.38139236
              }
            ],
            "score": "1.680885"
          },
          "answer": "Louis Pasteur",
          "question": "In 1857 this French chemist's theory of fermentation was first presented in a paper \"on Lactic Fermentation\""
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.14829372
              }
            ],
            "score": "1.6143973"
          },
          "answer": "Benito Mussolini",
          "question": "After being expelled as editor of the Socialist \"Avanti\" in 1914, he founded his own fascist paper"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.13974822
              }
            ],
            "score": "1.917839"
          },
          "answer": "Bookworm",
          "question": "It can be a voracious reader, or a beetle larva that feeds on paper"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.030214587
              }
            ],
            "score": "1.8317645"
          },
          "answer": "hot air balloon",
          "question": "In 1783 Joseph & Jacques Montgolfier, sons of a French paper bag maker, invented this"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.02470387
              }
            ],
            "score": "1.7530843"
          },
          "answer": "a balloon",
          "question": "The Montgolfier brothers were papermakers by profession & used paper in their early ones of these"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.018797074
              }
            ],
            "score": "1.6143973"
          },
          "answer": "New York Herald",
          "question": "This paper that had sent Stanley to find Livingstone merged with the New York Tribune in 1924"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.014672035
              }
            ],
            "score": "2.2325633"
          },
          "answer": "Scott",
          "question": "In 1907 this Phildelphia-based company introduced the paper towel"
        },
        {
          "_additional": {
            "rerank": [
              {
                "score": 0.011915022
              }
            ],
            "score": "1.917839"
          },
          "answer": "crepe",
          "question": "The flowers on this type of myrtle tree resemble the crinkly paper of the same name"
        }
      ]
    }
  }
}

Related pages

• Connect to Weaviate
• API References: GraphQL - Additional properties
• API References: GraphQL - Sorting
• Concepts: Reranking
• References: Modules: reranker-cohere
• References: Modules: reranker-transformers

Questions and feedback

If you have any questions or feedback, let us know in our user forum.

• Technical questions
• Documentation feedback