
```yaml {applies_to}
serverless: ga
stack: preview 9.2-9.3, ga 9.4.0+
```

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} 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} 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  // Limit to top 100 results before reranking
| RERANK "search query" ON title WITH { "inference_id" : "my_rerank_endpoint" }
```
:::

::::

## Syntax

::::{applies-switch}

:::{applies-item} {"stack": "ga 9.5+", "serverless": "ga"}

```esql
RERANK [column =] query ON field [, field, ...] [WITH { "inference_id" : "my_inference_endpoint" [, "timeout" : "<timeout_duration>"] }]
```

:::

:::{applies-item} {"stack": "preview 9.2-9.3, ga 9.4.0+"}

```esql
RERANK [column =] query ON field [, field, ...] [WITH { "inference_id" : "my_inference_endpoint" }]
```

:::

::::

## Parameters

`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.

`query`
:   The query text used to rerank the documents. This is typically the same
query used in the initial search.

`field`
:   One or more fields to use for reranking. These fields should contain the
text that the reranking model will evaluate.

`inference_id`
:   (Optional) The ID of
the [inference endpoint](docs-content://explore-analyze/elastic-inference/inference-api.md)
to use for the task.
The inference endpoint must be configured with the `rerank` task type.
If not specified, defaults to the preconfigured `.rerank-v1-elasticsearch`
endpoint.

`timeout` {applies_to}`stack: ga 9.4.1+` {applies_to}`serverless: ga`
:   (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.

## Description

Use `RERANK` to re-score search results using a machine learning model for improved relevance.

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

The `RERANK` command requires an
[inference endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put)
configured with the `rerank` task type. If you omit the `inference_id` option,
`RERANK` uses the preconfigured `.rerank-v1-elasticsearch` endpoint, which is
available by default.

For improved relevance, you can use the preconfigured
`.jina-reranker-v3` endpoint, powered by the
[Elastic Inference Service (EIS)](docs-content://explore-analyze/elastic-inference/eis.md).
To use a different model, create a `rerank` inference endpoint and specify
its ID in the `WITH` clause. Refer to
[semantic reranking](docs-content://solutions/search/ranking/semantic-reranking.md)
for a full list of supported reranking models.

### 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}`stack: ga 9.5+` {applies_to}`serverless: ga`
```esql
RERANK "search query" ON title 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 `RERANK` command
* Split complex operations into multiple simpler queries
* Configure your HTTP client's response timeout (Refer to [HTTP client configuration](/reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration))


## Examples

### Rerank with a single field

:::{include} ../../generated/x-pack-esql/commands/examples/rerank.csv-spec/simple-query.md
:::

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

:::{include} ../../generated/x-pack-esql/commands/examples/rerank.csv-spec/two-queries.md
:::

### Combine original score with reranked score

:::{include} ../../generated/x-pack-esql/commands/examples/rerank.csv-spec/combine.md
:::

### Rerank using document snippets

:::{include} ../../generated/x-pack-esql/commands/examples/rerank.csv-spec/rerank-top-snippets.md
:::
