Skip to content

Commit bc304a8

Browse files
afoucretafoucret
committed
ES|QL Rerank command doc.
1 parent 1f3039a commit bc304a8

File tree

4 files changed

+164
-1
lines changed

4 files changed

+164
-1
lines changed

‎docs/reference/query-languages/esql/_snippets/commands/layout/completion.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,6 @@ FROM movies
137137
| KEEP title, summary, rating
138138
```
139139

140-
141140
| title:keyword | summary:keyword | rating:double |
142141
| --- | --- | --- |
143142
| The Shawshank Redemption | A tale of hope and redemption in prison. | 9.3 |

‎docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
## `RERANK` [esql-rerank]
2+
3+
```yaml {applies_to}
4+
serverless: preview
5+
stack: preview 9.2.0
6+
```
7+
8+
The `RERANK` command uses an inference model to compute a new relevance score
9+
for an initial set of documents, directly within your ES|QL queries.
10+
11+
**Syntax**
12+
13+
```esql
14+
RERANK [column =] query ON field [, field, ...] (WITH { "inference_id" : "my_inference_endpoint" })
15+
```
16+
17+
**Parameters**
18+
19+
`column`
20+
: (Optional) The name of the output column containing the reranked scores.
21+
If not specified, the results will be stored in a column named `_score`.
22+
If the specified column already exists, it will be overwritten with the new
23+
results.
24+
25+
`query`
26+
: The query text used to rerank the documents. This is typically the same
27+
query used in the initial search.
28+
29+
`field`
30+
: One or more fields to use for reranking. These fields should contain the
31+
text that the reranking model will evaluate.
32+
33+
`my_inference_endpoint`
34+
: The ID of
35+
the [inference endpoint](docs-content://explore-analyze/elastic-inference/inference-api.md)
36+
to use for the task.
37+
The inference endpoint must be configured with the `rerank` task type.
38+
39+
**Description**
40+
41+
The `RERANK` command uses an inference model to compute a new relevance score
42+
for an initial set of documents, directly within your ES|QL queries.
43+
44+
Typically, you first use a `WHERE` clause with a function like `MATCH` to
45+
retrieve an initial set of documents. This set is often sorted by `_score` and
46+
reduced to the top results (for example, 100) using `LIMIT`. The `RERANK`
47+
command then processes this smaller, refined subset, which is a good balance
48+
between performance and accuracy.
49+
50+
**Requirements**
51+
52+
To use this command, you must deploy your reranking model in Elasticsearch as
53+
an [inference endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put)
54+
with the
55+
task type `rerank`.
56+
57+
#### Handling timeouts
58+
59+
`RERANK` commands may time out when processing large datasets or complex
60+
queries. The default timeout is 10 minutes, but you can increase this limit if
61+
necessary.
62+
63+
How you increase the timeout depends on your deployment type:
64+
65+
::::{tab-set}
66+
:::{tab-item} {{ech}}
67+
68+
* You can adjust {{es}} settings in
69+
the [Elastic Cloud Console](docs-content://deploy-manage/deploy/elastic-cloud/edit-stack-settings.md)
70+
* You can also adjust the `search.default_search_timeout` cluster setting
71+
using [Kibana's Advanced settings](kibana://reference/advanced-settings.md#kibana-search-settings)
72+
:::
73+
74+
:::{tab-item} Self-managed
75+
76+
* You can configure at the cluster level by setting
77+
`search.default_search_timeout` in `elasticsearch.yml` or updating
78+
via [Cluster Settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings)
79+
* You can also adjust the `search:timeout` setting
80+
using [Kibana's Advanced settings](kibana://reference/advanced-settings.md#kibana-search-settings)
81+
* Alternatively, you can add timeout parameters to individual queries
82+
:::
83+
84+
:::{tab-item} {{serverless-full}}
85+
86+
* Requires a manual override from Elastic Support because you cannot modify
87+
timeout settings directly
88+
:::
89+
::::
90+
91+
If you don't want to increase the timeout limit, try the following:
92+
93+
* Reduce data volume with `LIMIT` or more selective filters before the `RERANK`
94+
command
95+
* Split complex operations into multiple simpler queries
96+
* Configure your HTTP client's response timeout (Refer
97+
to [HTTP client configuration](/reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration))
98+
99+
**Examples**
100+
101+
Rerank search results using a simple query and a single field:
102+
103+
```esql
104+
FROM books
105+
| WHERE MATCH(title, "science fiction")
106+
| SORT _score DESC
107+
| LIMIT 100
108+
| RERANK "science fiction" ON (title) WITH { "inference_id" : "my_reranker" }
109+
| LIMIT 3
110+
| KEEP title, _score
111+
```
112+
113+
| title:keyword | _score:double |
114+
|---------------|---------------|
115+
| Neuromancer | 0.98 |
116+
| Dune | 0.95 |
117+
| Foundation | 0.92 |
118+
119+
Rerank search results using a query and multiple fields, and store the new score
120+
in a column named `rerank_score`:
121+
122+
```esql
123+
FROM movies
124+
| WHERE MATCH(title, "dystopian future") OR MATCH(synopsis, "dystopian future")
125+
| SORT _score DESC
126+
| LIMIT 100
127+
| RERANK rerank_score = "dystopian future" ON (title, synopsis) WITH { "inference_id" : "my_reranker" }
128+
| SORT rerank_score DESC
129+
| LIMIT 5
130+
| KEEP title, _score, rerank_score
131+
```
132+
133+
| title:keyword | _score:double | rerank_score:double |
134+
|-----------------|---------------|---------------------|
135+
| Blade Runner | 8.75 | 0.99 |
136+
| The Matrix | 9.12 | 0.97 |
137+
| Children of Men | 8.50 | 0.96 |
138+
| Akira | 8.99 | 0.94 |
139+
| Gattaca | 8.65 | 0.91 |
140+
141+
Combine the original score with the reranked score:
142+
143+
```esql
144+
FROM movies
145+
| WHERE MATCH(title, "dystopian future") OR MATCH(synopsis, "dystopian future")
146+
| SORT _score DESC
147+
| LIMIT 100
148+
| RERANK rerank_score = "dystopian future" ON (title, synopsis) WITH { "inference_id" : "my_reranker" }
149+
| EVAL original_score = _score, _score = rerank_score + original_score
150+
| SORT _score DESC
151+
| LIMIT 2
152+
| KEEP title, original_score, rerank_score, _score
153+
```
154+
155+
| title:keyword | original_score:double | rerank_score:double | _score:double |
156+
|---------------|-----------------------|---------------------|---------------|
157+
| The Matrix | 9.12 | 0.97 | 10.09 |
158+
| Akira | 8.99 | 0.94 | 9.93 |
159+
160+

‎docs/reference/query-languages/esql/_snippets/lists/processing-commands.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
* [`LOOKUP JOIN`](../../commands/processing-commands.md#esql-lookup-join)
1212
* [preview] [`MV_EXPAND`](../../commands/processing-commands.md#esql-mv_expand)
1313
* [`RENAME`](../../commands/processing-commands.md#esql-rename)
14+
* [preview] [`RERANK`](../../commands/processing-commands.md#esql-rerank)
1415
* [preview] [`SAMPLE`](../../commands/processing-commands.md#esql-sample)
1516
* [`SORT`](../../commands/processing-commands.md#esql-sort)
1617
* [`STATS`](../../commands/processing-commands.md#esql-stats-by)

‎docs/reference/query-languages/esql/commands/processing-commands.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,9 @@ mapped_pages:
5656
:::{include} ../_snippets/commands/layout/rename.md
5757
:::
5858

59+
:::{include} ../_snippets/commands/layout/rerank.md
60+
:::
61+
5962
:::{include} ../_snippets/commands/layout/sample.md
6063
:::
6164

0 commit comments

Comments
 (0)