---
title: ES|QL RERANK command
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/3175/reference/query-languages/esql/commands/rerank
products:
  - Elasticsearch
---

# ES|QL RERANK command
<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Preview from 9.2 to 9.3
</applies-to>

The `RERANK` command uses an inference model to compute a new relevance score
for an initial set of documents, directly within your ES|QL queries.
<tab-set>
  <tab-item title="9.3.0+">
    Starting in version 9.3.0, `RERANK` automatically limits processing to **1000
    rows by default** to prevent accidental high consumption. This limit is applied
    before the `RERANK` command executes.If you need to process more rows, you can adjust the limit using the cluster setting:
    ```
    PUT _cluster/settings
    {
      "persistent": {
        "esql.command.rerank.limit": 5000
      }
    }
    ```
    You can also disable the command entirely if needed:
    ```
    PUT _cluster/settings
    {
      "persistent": {
        "esql.command.rerank.enabled": false
      }
    }
    ```
  </tab-item>

  <tab-item title="9.2.x">
    No automatic row limit is applied. **You should always use `LIMIT` before or after `RERANK` to control the number of documents processed**, to avoid accidentally reranking large datasets which can result in high latency and increased costs.For example:
    ```esql
    FROM books
    | WHERE title:"search query"
    | SORT _score DESC
    | LIMIT 100 
    | RERANK "search query" ON title WITH { "inference_id" : "my_rerank_endpoint" }
    ```
  </tab-item>
</tab-set>


## Syntax

<applies-switch>
  <applies-item title="{"stack": "ga 9.5+", "serverless": "ga"}" applies-to="Elastic Cloud Serverless: Generally available, Elastic Stack: Planned">
    ```esql
    RERANK [column =] query ON field [, field, ...] [WITH { "inference_id" : "my_inference_endpoint" [, "timeout" : "<timeout_duration>"] }]
    ```
  </applies-item>

  <applies-item title="{"stack": "preview 9.2-9.3, ga 9.4.0+"}" applies-to="Elastic Stack: Preview from 9.2 to 9.3">
    ```esql
    RERANK [column =] query ON field [, field, ...] [WITH { "inference_id" : "my_inference_endpoint" }]
    ```
  </applies-item>
</applies-switch>


## Parameters

<definitions>
  <definition term="column">
    (Optional) The name of the output column containing the reranked scores.
    If not specified, the results will be stored in a column named `_score`.
    If the specified column already exists, it will be overwritten with the new
    results.
  </definition>
  <definition term="query">
    The query text used to rerank the documents. This is typically the same
    query used in the initial search.
  </definition>
  <definition term="field">
    One or more fields to use for reranking. These fields should contain the
    text that the reranking model will evaluate.
  </definition>
  <definition term="my_inference_endpoint">
    The ID of
    the [inference endpoint](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3175/explore-analyze/elastic-inference/inference-api)
    to use for the task.
    The inference endpoint must be configured with the `rerank` task type.
  </definition>
  <definition term="timeout_duration Elastic Stack: Planned Elastic Cloud Serverless: Generally available">
    (Optional) Timeout for the inference request (for example, `"30s"`, `"1m"`).
    If not specified, the default search timeout applies. Use this to set a
    per-call timeout independent of the cluster-wide search timeout.
  </definition>
</definitions>


## Description

The `RERANK` command uses an inference model to compute a new relevance score
for an initial set of documents, directly within your ES|QL queries.
Typically, you first use a `WHERE` clause with a function like `MATCH` to
retrieve an initial set of documents. This set is often sorted by `_score` and
reduced to the top results (for example, 100) using `LIMIT`. The `RERANK`
command then processes this smaller, refined subset, which is a good balance
between performance and accuracy.
When using `RERANK` with a multivalue column, each value is ranked individually.
The score column is then assigned the maximum score resulting from ranking the
individual values.

## Requirements

To use this command, you must deploy your reranking model in Elasticsearch as
an [inference endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put)
with the
task type `rerank`.

### Handling timeouts

`RERANK` commands may time out when processing large datasets or complex
queries. The default timeout is 30 seconds.
You can set per-call timeout using the `"timeout"` option in the `WITH` clause: <applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to>
```esql
COMPLETION answer = question WITH { "inference_id": "my_inference_endpoint", "timeout": "1m" }
```

If you can't modify your timeout limits, try the following:
- Reduce data volume with `LIMIT` or more selective filters before the `COMPLETION` command
- Split complex operations into multiple simpler queries
- Configure your HTTP client's response timeout (Refer to [HTTP client configuration](/elastic/docs-builder/docs/3175/reference/elasticsearch/configuration-reference/networking-settings#_http_client_configuration))


## Examples


### Rerank with a single field

```esql
FROM books METADATA _score
| WHERE MATCH(description, "hobbit")
| SORT _score DESC
| LIMIT 100
| RERANK "hobbit" ON description WITH { "inference_id" : "test_reranker" }
| LIMIT 3
| KEEP title, _score
```


| title:text                        | _score:double         |
|-----------------------------------|-----------------------|
| Poems from the Hobbit             | 0.0015673980815336108 |
| The Lord of the Rings - Boxed Set | 0.0011135857785120606 |
| Letters of J R R Tolkien          | 0.0024999999441206455 |


### Rerank with multiple fields and a custom score column

```esql
FROM books METADATA _score
| WHERE MATCH(description, "hobbit") OR MATCH(author, "Tolkien")
| SORT _score DESC
| LIMIT 100
| RERANK rerank_score = "hobbit" ON description, author WITH { "inference_id" : "test_reranker" }
| SORT rerank_score DESC, book_no DESC
| LIMIT 3
```


| title:text                                                                 | _score:double      | rerank_score:double |
|----------------------------------------------------------------------------|--------------------|---------------------|
| The Lord of the Rings Poster Collection: Six Paintings by Alan Lee (No. 1) | 0.7976278066635132 | 0.125               |
| A Middle English Reader and Vocabulary                                     | 1.043297290802002  | 0.07692307978868484 |
| FINAL WITNESS                                                              | 1.4058171510696411 | 0.07692307978868484 |


### Combine original score with reranked score

```esql
FROM books METADATA _score
| WHERE MATCH(description, "hobbit") OR MATCH(author, "Tolkien")
| SORT _score DESC
| LIMIT 100
| RERANK rerank_score = "hobbit" ON title, description WITH { "inference_id" : "test_reranker" }
| EVAL original_score = _score, _score = rerank_score + original_score
| SORT _score
| LIMIT 3
```


| title:text                                                                 | _score:double | rerank_score:double |
|----------------------------------------------------------------------------|---------------|---------------------|
| The Lord of the Rings Poster Collection: Six Paintings by Alan Lee (No. 1) | 0.7976278     | 0.125               |
| A Middle English Reader and Vocabulary                                     | 1.043297      | 0.07692308          |
| FINAL WITNESS                                                              | 1.405817      | 0.07692308          |


### Rerank using document snippets

```esql
FROM books
| WHERE MATCH(title, "return")
| RERANK "Tolkien" ON TOP_SNIPPETS(description, "Tolkien", { "num_snippets": 3, "num_words": 25 }) WITH { "inference_id" : "test_reranker" }
```


| book_no:keyword | title:text                                                       | _score:double        |
|-----------------|------------------------------------------------------------------|----------------------|
| 2714            | Return of the King Being the Third Part of The Lord of the Rings | 0.007092198356986046 |
| 7350            | Return of the Shadow                                             | 0.012500000186264515 |