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 model integration for your collection.

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 Client 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)

  API docs

Python Client 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.

  API docs  Deprecated (v3)

JS/TS Client v3

const myNVCollection = client.collections.get('WineReviewNV');

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

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

  API docs

JS/TS Client v2

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));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{Name: "_additional", Fields: []graphql.Field{{Name: "distance"}}},
  ).
  WithNearText((&graphql.NearTextArgumentBuilder{}).WithConcepts([]string{"flying"})).
  WithLimit(10).
  Do(ctx)

  API docs

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 Client 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)

  API docs

Python Client 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))

  API docs  Deprecated (v3)

JS/TS Client v3

const jeopardy = client.collections.get('JeopardyQuestion');

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

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

  API docs

JS/TS Client v2

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));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "rerank(property: \"answer\" query: \"floating\") { score }"},
          {Name: "score"},
        },
      },
  ).
  WithNearText((&graphql.NearTextArgumentBuilder{}).WithConcepts([]string{"flying"})).
  WithLimit(10).
  Do(ctx)

  API docs

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 Client 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)

  API docs

Python Client 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))

  API docs  Deprecated (v3)

JS/TS Client v3

const jeopardy = client.collections.get('JeopardyQuestion');

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

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

  API docs

JS/TS Client v2

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));

Go

bm25args := (&graphql.BM25ArgumentBuilder{}).WithQuery("paper")
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{

        {Name: "rerank(property: \"question\" query: \"publication\") { score }"},

        {Name: "score"},
      },
    },
  ).
  WithBM25(bm25args).
  WithLimit(10).
  Do(ctx)

  API docs

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
• Model providers integrations

Questions and feedback

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

• Technical questions
• Documentation feedback