--- title: ES|QL RERANK command description: url: https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/commands/rerank products: - Elasticsearch --- # ES|QL RERANK command - Elastic Cloud Serverless: Generally available - Elastic Stack: Preview from 9.2 to 9.3 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. 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 } } ``` 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" } ``` ## Syntax ```esql RERANK [column =] query ON field [, field, ...] [WITH { "inference_id" : "my_inference_endpoint" }] ``` ## Parameters (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. The query text used to rerank the documents. This is typically the same query used in the initial search. One or more fields to use for reranking. These fields should contain the text that the reranking model will evaluate. The ID of the [inference endpoint](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/explore-analyze/elastic-inference/inference-api) to use for the task. The inference endpoint must be configured with the `rerank` task type. ## 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 10 minutes, but you can increase this limit if necessary. How you increase the timeout depends on your deployment type: - You can adjust Elasticsearch settings in the [Elastic Cloud Console](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/deploy-manage/deploy/elastic-cloud/edit-stack-settings) - You can also adjust the `search.default_search_timeout` cluster setting using [Kibana's Advanced settings](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/reference/kibana/advanced-settings#kibana-search-settings) - You can configure at the cluster level by setting `search.default_search_timeout` in `elasticsearch.yml` or updating via [Cluster Settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings) - You can also adjust the `search:timeout` setting using [Kibana's Advanced settings](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/reference/kibana/advanced-settings#kibana-search-settings) - Alternatively, you can add timeout parameters to individual queries - Requires a manual override from Elastic Support because you cannot modify timeout settings directly If you don't want to increase the timeout limit, 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](/elastic/docs-builder/docs/3028/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 |