From bc304a80b3039d3eba128d95dbeedaeed45bb5f9 Mon Sep 17 00:00:00 2001 From: afoucret Date: Thu, 31 Jul 2025 14:36:18 +0200 Subject: [PATCH 1/2] ES|QL Rerank command doc. --- .../_snippets/commands/layout/completion.md | 1 - .../esql/_snippets/commands/layout/rerank.md | 160 ++++++++++++++++++ .../_snippets/lists/processing-commands.md | 1 + .../esql/commands/processing-commands.md | 3 + 4 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/completion.md b/docs/reference/query-languages/esql/_snippets/commands/layout/completion.md index 70c25861294ce..519c4db93db70 100644 --- a/docs/reference/query-languages/esql/_snippets/commands/layout/completion.md +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/completion.md @@ -137,7 +137,6 @@ FROM movies | KEEP title, summary, rating ``` - | title:keyword | summary:keyword | rating:double | | --- | --- | --- | | The Shawshank Redemption | A tale of hope and redemption in prison. | 9.3 | diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md b/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md new file mode 100644 index 0000000000000..5d8c8f39d86dc --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md @@ -0,0 +1,160 @@ +## `RERANK` [esql-rerank] + +```yaml {applies_to} +serverless: preview +stack: preview 9.2.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. + +**Syntax** + +```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. + +`my_inference_endpoint` +: 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. + +**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. + +**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: + +::::{tab-set} +:::{tab-item} {{ech}} + +* You can adjust {{es}} settings in + the [Elastic Cloud Console](docs-content://deploy-manage/deploy/elastic-cloud/edit-stack-settings.md) +* You can also adjust the `search.default_search_timeout` cluster setting + using [Kibana's Advanced settings](kibana://reference/advanced-settings.md#kibana-search-settings) + ::: + +:::{tab-item} Self-managed + +* 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](kibana://reference/advanced-settings.md#kibana-search-settings) +* Alternatively, you can add timeout parameters to individual queries + ::: + +:::{tab-item} {{serverless-full}} + +* 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](/reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration)) + +**Examples** + +Rerank search results using a simple query and a single field: + +```esql +FROM books +| WHERE MATCH(title, "science fiction") +| SORT _score DESC +| LIMIT 100 +| RERANK "science fiction" ON (title) WITH { "inference_id" : "my_reranker" } +| LIMIT 3 +| KEEP title, _score +``` + +| title:keyword | _score:double | +|---------------|---------------| +| Neuromancer | 0.98 | +| Dune | 0.95 | +| Foundation | 0.92 | + +Rerank search results using a query and multiple fields, and store the new score +in a column named `rerank_score`: + +```esql +FROM movies +| WHERE MATCH(title, "dystopian future") OR MATCH(synopsis, "dystopian future") +| SORT _score DESC +| LIMIT 100 +| RERANK rerank_score = "dystopian future" ON (title, synopsis) WITH { "inference_id" : "my_reranker" } +| SORT rerank_score DESC +| LIMIT 5 +| KEEP title, _score, rerank_score +``` + +| title:keyword | _score:double | rerank_score:double | +|-----------------|---------------|---------------------| +| Blade Runner | 8.75 | 0.99 | +| The Matrix | 9.12 | 0.97 | +| Children of Men | 8.50 | 0.96 | +| Akira | 8.99 | 0.94 | +| Gattaca | 8.65 | 0.91 | + +Combine the original score with the reranked score: + +```esql +FROM movies +| WHERE MATCH(title, "dystopian future") OR MATCH(synopsis, "dystopian future") +| SORT _score DESC +| LIMIT 100 +| RERANK rerank_score = "dystopian future" ON (title, synopsis) WITH { "inference_id" : "my_reranker" } +| EVAL original_score = _score, _score = rerank_score + original_score +| SORT _score DESC +| LIMIT 2 +| KEEP title, original_score, rerank_score, _score +``` + +| title:keyword | original_score:double | rerank_score:double | _score:double | +|---------------|-----------------------|---------------------|---------------| +| The Matrix | 9.12 | 0.97 | 10.09 | +| Akira | 8.99 | 0.94 | 9.93 | + + diff --git a/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md b/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md index 8bfcd2a20ac33..6c929895987f2 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md +++ b/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md @@ -11,6 +11,7 @@ * [`LOOKUP JOIN`](../../commands/processing-commands.md#esql-lookup-join) * [preview] [`MV_EXPAND`](../../commands/processing-commands.md#esql-mv_expand) * [`RENAME`](../../commands/processing-commands.md#esql-rename) +* [preview] [`RERANK`](../../commands/processing-commands.md#esql-rerank) * [preview] [`SAMPLE`](../../commands/processing-commands.md#esql-sample) * [`SORT`](../../commands/processing-commands.md#esql-sort) * [`STATS`](../../commands/processing-commands.md#esql-stats-by) diff --git a/docs/reference/query-languages/esql/commands/processing-commands.md b/docs/reference/query-languages/esql/commands/processing-commands.md index 1f07e8b3b8c2c..daa8fd88b416a 100644 --- a/docs/reference/query-languages/esql/commands/processing-commands.md +++ b/docs/reference/query-languages/esql/commands/processing-commands.md @@ -56,6 +56,9 @@ mapped_pages: :::{include} ../_snippets/commands/layout/rename.md ::: +:::{include} ../_snippets/commands/layout/rerank.md +::: + :::{include} ../_snippets/commands/layout/sample.md ::: From 486329f8cbd5e74d9374ae4f3bd1a89a52a661bc Mon Sep 17 00:00:00 2001 From: afoucret Date: Thu, 31 Jul 2025 14:47:19 +0200 Subject: [PATCH 2/2] Fix typo. --- .../query-languages/esql/_snippets/commands/layout/rerank.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md b/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md index 5d8c8f39d86dc..f0b422393cd07 100644 --- a/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md @@ -11,7 +11,7 @@ for an initial set of documents, directly within your ES|QL queries. **Syntax** ```esql -RERANK [column =] query ON field [, field, ...] (WITH { "inference_id" : "my_inference_endpoint" }) +RERANK [column =] query ON field [, field, ...] [WITH { "inference_id" : "my_inference_endpoint" }] ``` **Parameters**