# Reranking

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

:::accordion{title="Additional information"}
**Configure reranking**

To rerank search results, enable a reranker [model integration](../model-provider-integrations/index.md) 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.
:::

:::callout{intent="tip" title="Prefer natural language queries?"}
The [Query Agent](query-agent.md) translates plain English questions into optimized Weaviate queries automatically - no manual query construction needed.
Cloud only
:::

## Named vectors

Any vector-based search on collections with [named vectors](../reference-configuration/collections.md#multiple-vector-embeddings-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.

:::code-group{sync="languages"}
```python title="Python" {7}
from weaviate.classes.query import MetadataQuery

reviews = client.collections.use("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)
```

```typescript title="JavaScript/TypeScript" {4}
const myNVCollection = client.collections.use('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));
}
```

```go title="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)
```

```graphql title="GraphQL" {5-8}
{
  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.

:::code-group{sync="languages"}
```python title="Python"
from weaviate.classes.query import Rerank, MetadataQuery

jeopardy = client.collections.use("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)
```

```typescript title="JavaScript/TypeScript"
const jeopardy = client.collections.use('JeopardyQuestion');
```

```go title="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)
```

```graphql title="GraphQL" {13-18}
{
  Get {
    JeopardyQuestion(
      nearText: {
        concepts: "flying"
      }
      limit: 10
    ) {
      answer
      question
      _additional {
        distance
        rerank(
          property: "answer"
          query: "floating"
        ) {
          score
        }
      }
    }
  }
}
```
:::

:::accordion{title="Example response"}
The response should look like this:

```json
{
  "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.

:::code-group{sync="languages"}
```python title="Python"
from weaviate.classes.query import Rerank, MetadataQuery

jeopardy = client.collections.use("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)
```

```typescript title="JavaScript/TypeScript"
const jeopardy = client.collections.use('JeopardyQuestion');
```

```go title="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)
```

```graphql title="GraphQL" {13-18}
{
  Get {
    JeopardyQuestion(
      bm25: {
        query: "paper"
      }
      limit: 10
    ) {
      answer
      question
      _additional {
        distance
        rerank(
          property: "question"
          query: "publication"
        ) {
          score
        }
      }
    }
  }
}
```
:::

:::accordion{title="Example response"}
The response should look like this:

```json
{
  "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"
        }
      ]
    }
  }
}
```
:::

## Soft-rank with Boost

:::callout{intent="info" title="Added in `v1.38`"}
:::

For lightweight result reordering based on filters, property values, or time / numeric decay (without calling an external rerank model), use [Boost](boost.md). Rerank and Boost can be used independently. Pick rerank when you need a smarter model to re-rank the top-N, and Boost when you want to bias by simple signals already on the objects.

## Related pages

- [Connect to Weaviate](../connect-to-weaviate/index.md)
- [API References: GraphQL - Additional properties](../apis/graphql-additional-properties.md#rerank)
- [API References: GraphQL - Sorting](../apis/graphql-additional-operators.md#sorting-api)
- [Concepts: Reranking](../concepts/reranking.md)
- [Model providers integrations](../model-provider-integrations/index.md)

## Questions and feedback

Have a question or feedback? Here's how to reach us.

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.