[ES|QL] Implementing rerank on multi values. by afoucret · Pull Request #140672 · elastic/elasticsearch

afoucret · 2026-01-14T16:39:11Z

Summary

This PR changes how the ES|QL RERANK command handles input fields for reranking.
Multi-value fields are now processed natively, with each value sent individually to the reranking model.

Closes: #136865

Functional Changes

Multi-value field handling

When a rerank field contains multiple values (e.g., a multi-valued author field), each value is now sent separately to the inference service for scoring and the max score is returned.
Previously, vlaues fields were combined into a single YAML document before being sent to the model.

Example:

FROM books
| WHERE title:"Leo Tolstoy"
| RERANK "Leo Tolstoy" ON author WITH { "inference_id" : "my_reranker" }}

If a document has author: ["John Hockenberry", "Leo Tolstoy", "Pat Conroy"], each author value is now scored independently rather than being formatted as a YAML list.

Rerank fields restricted to string types only

The RERANK command now only accepts string fields. Numeric and boolean fields are no longer supported as rerank inputs.

Can use an expression without a name as a RERANK field

In previous version it was required to specify the name of the computed field when using and expression as a rerank field:

| RERANK "my query" ON truncated_description = SUBSTRING(description, 0, 100)

Now that we do not use an intermediary YAML, it is not necessary anymore and you can use the expression directly:

| RERANK "my query" ON SUBSTRING(description, 0, 100)

…h instead of the string length.

elasticsearchmachine · 2026-01-14T16:39:36Z

Hi @afoucret, I've created a changelog YAML for you.

afoucret · 2026-01-15T10:35:25Z

x-pack/plugin/esql/qa/testFixtures/src/main/resources/rerank.csv-spec

-reranker using a non text fields
-required_capability: rerank
-required_capability: match_operator_colon
-
-FROM books METADATA _score
-| WHERE title:"war and peace" AND author:"Tolstoy"
-| RERANK "war and peace" ON ratings WITH { "inference_id" : "test_reranker" }
-| EVAL _score=ROUND(_score, 2), ratings = ROUND(ratings, 2)
-| SORT _score DESC, book_no ASC
-| KEEP book_no, title, ratings, _score
-;
-
-book_no:keyword | title:text                                            | ratings:double | _score:double
-2776            | The Devil and Other Stories (Oxford World's Classics) | 5.0            | 0.33
-4536            | War and Peace (Signet Classics)                       | 4.75           | 0.25
-5327            | War and Peace                                         | 3.84           | 0.06
-9032            | War and Peace: A Novel (6 Volumes)                    | 3.81           | 0.06
-;
-
-


ℹ️ Now impossible to rerank a number.

x-pack/plugin/esql/qa/testFixtures/src/main/resources/rerank.csv-spec

afoucret · 2026-01-15T10:38:16Z

x-pack/plugin/esql/src/main/antlr/EsqlBaseParser.g4


 rerankCommand
-    : RERANK (targetField=qualifiedName ASSIGN)? queryText=constant ON rerankFields commandNamedParameters
+    : RERANK (targetField=qualifiedName ASSIGN)? queryText=constant ON  rerankFields=fields commandNamedParameters


Cleaning the grammar of the useless rerankFields that was required only to implement that we do not have nameless expression (not required anymore)

.../plugin/esql/src/main/java/org/elasticsearch/xpack/esql/inference/rerank/RerankOperator.java

elasticsearchmachine · 2026-01-15T10:41:05Z

Pinging @elastic/es-search-relevance (Team:Search Relevance)

github-actions · 2026-01-15T15:54:47Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

tteofili

LGTM

tteofili · 2026-01-27T15:29:13Z

.../esql/src/main/java/org/elasticsearch/xpack/esql/inference/rerank/RerankRequestIterator.java

-        this.totalPositions = textBlock.getPositionCount();
+        this.totalPositions = inputBlocks[0].getPositionCount();


maybe a null check here?

I think this should "never" happen - so I added an assertion.

mridula-s109

LGTM.

I do have one question would it be nice if the docs explicitly cover the breaking changes mentioned in the PR description:

String fields only: Add clear statement that numeric/boolean fields are no longer supported
Multi-value max score: Document that multi-value fields use max score (not YAML aggregation)

Suggested location: docs/reference/query-languages/esql/_snippets/commands/layout/rerank.md

pmpailis

LGTM!

pmpailis · 2026-01-28T08:43:38Z

.../esql/src/main/java/org/elasticsearch/xpack/esql/inference/rerank/RerankRequestIterator.java

-            // Filter out empty and whitespace-only strings
-            if (Strings.hasText(inputText)) {
-                inputs.add(inputText);
+            if (textBlock.isNull(position)) {


Similarly to the ctor, is it possible for textBlock to be null here?

I think this should never happen - so I added an assertion instead

pmpailis · 2026-01-28T09:07:11Z

.../src/test/java/org/elasticsearch/xpack/esql/inference/rerank/RerankRequestIteratorTests.java

+     * Tests that when one block is null at a position but another block has a value,
+     * only the non-null block's values are included in the input.
+     */
+    public void testMultipleInputBlocksWithPartialNulls() throws Exception {


pmpailis · 2026-01-28T09:50:39Z

...in/esql/src/test/java/org/elasticsearch/xpack/esql/inference/rerank/RerankOperatorTests.java

+            );
+
+            // Verify factory is created correctly
+            assertNotNull(factory);


maybe we could update this to test actual input/output for 2 blocks? Something similar to RerankRequestIteratorTests#testMultipleInputBlocksWithPartialNulls

good suggestion - I updated the test

ioanatia · 2026-01-28T14:34:45Z

@mridula-s109 I will update the docs separately when we also mark RERANK as GA - it's a good idea.

afoucret added 2 commits January 14, 2026 17:28

Update the way inference test service compute rerank score: use a has…

5d707e6

…h instead of the string length.

Implement rerank using muli-value fields.

d2ab99d

afoucret added >enhancement :Search Relevance/ES|QL Search functionality in ES|QL v9.4.0 labels Jan 14, 2026

afoucret and others added 4 commits January 14, 2026 17:39

Update docs/changelog/140672.yaml

e78a783

Fix a test.

8f6e07f

Fix a CSV tests.

4671732

Allow to use an expression without naming it in RERANK.

1f0d939

afoucret commented Jan 15, 2026

View reviewed changes

afoucret marked this pull request as ready for review January 15, 2026 10:40

elasticsearchmachine added the Team:Search Relevance Meta label for the Search Relevance team in Elasticsearch label Jan 15, 2026

Add a test cases to use rerank with snippets.

d4d7753

afoucret mentioned this pull request Jan 15, 2026

[ES|QL][Rerank]Chunking support in the RERANK command #136865

Closed

4 tasks

afoucret and others added 4 commits January 15, 2026 14:12

Fixing bad field name in tests.

5c16a38

Merge branch 'main' into esql-mv-rerank

eaf4b55

Small fix on tests.

54e1ab7

Update the doc.

a5ef68d

Merge branch 'main' into esql-mv-rerank

1335684

ioanatia mentioned this pull request Jan 22, 2026

ES|QL: Refactor RERANK syntax #141104

Merged

ioanatia self-assigned this Jan 26, 2026

ioanatia added 3 commits January 27, 2026 11:26

Merge remote-tracking branch 'elasticsearch/main' into esql-mv-rerank

45ddff8

Revert field name rename

a3d2d84

Fix tests

27ec9ca

ioanatia requested review from carlosdelest, pmpailis and tteofili January 27, 2026 14:58

tteofili approved these changes Jan 27, 2026

View reviewed changes

mridula-s109 approved these changes Jan 27, 2026

View reviewed changes

pmpailis approved these changes Jan 28, 2026

View reviewed changes

ioanatia and others added 2 commits January 28, 2026 14:24

Address review feedback

5189c0e

Merge branch 'main' into esql-mv-rerank

4d6e6b7

ioanatia merged commit 8974ffc into elastic:main Jan 28, 2026
35 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ES|QL] Implementing rerank on multi values.#140672

[ES|QL] Implementing rerank on multi values.#140672
ioanatia merged 17 commits intoelastic:mainfrom
afoucret:esql-mv-rerank

afoucret commented Jan 14, 2026 •

edited

Loading

elasticsearchmachine commented Jan 14, 2026

afoucret Jan 15, 2026

Uh oh!

afoucret Jan 15, 2026

Uh oh!

elasticsearchmachine commented Jan 15, 2026

github-actions bot commented Jan 15, 2026

When to use applies_to tags:

What NOT to do:

tteofili left a comment

tteofili Jan 27, 2026

ioanatia Jan 28, 2026

mridula-s109 left a comment

pmpailis left a comment

pmpailis Jan 28, 2026

ioanatia Jan 28, 2026

pmpailis Jan 28, 2026

pmpailis Jan 28, 2026 •

edited

Loading

ioanatia Jan 28, 2026

ioanatia commented Jan 28, 2026

Uh oh!

Labels

6 participants

		this.totalPositions = textBlock.getPositionCount();
		this.totalPositions = inputBlocks[0].getPositionCount();

Conversation

afoucret commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Functional Changes

Multi-value field handling

Rerank fields restricted to string types only

Can use an expression without a name as a RERANK field

elasticsearchmachine commented Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticsearchmachine commented Jan 15, 2026

github-actions bot commented Jan 15, 2026

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

tteofili left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mridula-s109 left a comment

Choose a reason for hiding this comment

pmpailis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmpailis Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ioanatia commented Jan 28, 2026

Uh oh!

Labels

6 participants

afoucret commented Jan 14, 2026 •

edited

Loading

pmpailis Jan 28, 2026 •

edited

Loading