Add `query_vector_builder` Support to Diversify Retriever #139094

markjhoy · 2025-12-05T01:09:39Z

(DRAFT - needs tests and docs)

Adds query_vector_builder support to the diversify retriever

…versify_retriever

github-actions · 2025-12-05T15:43:34Z

🔍 Preview links for changed docs

docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md

github-actions · 2025-12-05T15:43:35Z

ℹ️ 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

…versify_retriever

markjhoy · 2025-12-05T20:35:49Z

FYI - I added a new YAML test at x-pack/plugin/inference/src/yamlRestTest/resources/rest-api-spec/test/inference/70_semantic_text_diversifty_retriever.yml to verify the use of the query_vector_builder in a real-world scenario (as it needs inference). I'll reuse this later in additional features for the retriever.

elasticsearchmachine · 2025-12-05T20:36:47Z

Pinging @elastic/search-eng (Team:SearchOrg)

elasticsearchmachine · 2025-12-05T20:37:36Z

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

…versify_retriever

kderusso

Nice start!

kderusso · 2025-12-05T22:05:12Z

docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md

    Must be either an array of floats or a hex-encoded byte vector.
+    If you provide a `query_vector`, you cannot also provide a `query_vector_builder`.
+
+`query_vector_builder`


Please don't throw 🍅 at me 🙈

I think we should verify that we want the same query_vector_builder API here. There's some legacy API crust, for example the API asks for a model_id etc. and there's opportunity to modernize it with inference_id. This would be more work, though, so I'm not raising it as a blocker to the PR more as a discussion if that's something we want to bite off or if this is OK.

If we decide to go forward with query_vector_builder, perhaps not for this PR but the docs could use a bit of work here to define allowed parameters, and have something directly linkable.

I agree with what you're saying - but I think it's a larger, and more discrete PR (as it also touches other users of the QueryVectorBuilder). The docs however are probably a good idea.

kderusso · 2025-12-05T22:06:19Z

server/src/main/java/org/elasticsearch/search/diversification/DiversifyRetrieverBuilder.java

            && this.diversificationField.equals(other.diversificationField)
            && Objects.equals(this.lambda, other.lambda)
-            && Objects.equals(this.queryVector, other.queryVector);
+            && ((queryVector == null && other.queryVector == null)


Shouldn't Objects.equals take care of the null checks already?

Not necessarily in this case, as the query_vector is now a supplier, so we need to make sure the suppled value is equal, but if the supplier is null it'll throw when the .get() is issued.

kderusso · 2025-12-05T22:07:53Z

...amlRestTest/resources/rest-api-spec/test/inference/70_semantic_text_diversifty_retriever.yml

Nitpick: Typo in filename

kderusso · 2025-12-05T22:08:24Z

...amlRestTest/resources/rest-api-spec/test/inference/70_semantic_text_diversifty_retriever.yml

@@ -0,0 +1,127 @@
+setup:
+  - requires:
+      cluster_features: [ "retriever.result_diversification_mmr" ]


I don't think we can re-use the cluster feature here, we need a new one?

I'll double check. This was a carry over from the original YAML tests for the retriever, but may not be needed here...

kderusso · 2025-12-05T22:09:21Z

...amlRestTest/resources/rest-api-spec/test/inference/70_semantic_text_diversifty_retriever.yml

+              retriever:
+                knn:
+                  field: "textvector"
+                  query_vector: [ 0.5, 0.2, 0.4, 0.4 ]


This is using a query vector, not a query vector builder?

It's testing the query vector builder in the diversify retriever only - the inner retriever is irrelevant. But, I can change it.

kderusso · 2025-12-05T22:11:15Z

...amlRestTest/resources/rest-api-spec/test/inference/70_semantic_text_diversifty_retriever.yml

+  - length: { hits.hits: 3 }
+
+---
+"Validate query_vector or query_vector_builder but not both":


Can we also validate an incorrectly formatted query vector builder?

It should be caught by the parser, but to be sure, I'll add a test in.

Add query_vector_builder support to diversify

a9aef94

elasticsearchmachine added the v9.3.0 label Dec 5, 2025

markjhoy added 2 commits December 5, 2025 08:37

Merge branch 'main' into markjhoy/add_query_vector_builder_support_di…

fad45ae

…versify_retriever

add docs; rewrite tests; cleanups

693a432

github-actions bot deployed to docs-preview December 5, 2025 15:42 View deployment

Merge branch 'main' into markjhoy/add_query_vector_builder_support_di…

17c1081

…versify_retriever

github-actions bot deployed to docs-preview December 5, 2025 16:19 View deployment

context - return null if no query vector

9ccb78c

github-actions bot deployed to docs-preview December 5, 2025 19:23 View deployment

add yaml test to verify use query_vector_builder

d69af11

github-actions bot deployed to docs-preview December 5, 2025 20:35 View deployment

markjhoy marked this pull request as ready for review December 5, 2025 20:35

elasticsearchmachine added the needs:triage Requires assignment of a team area label label Dec 5, 2025

markjhoy added Team:SearchOrg Meta label for the Search Org (Enterprise Search) and removed needs:triage Requires assignment of a team area label labels Dec 5, 2025

markjhoy added the :SearchOrg/Relevance Label for the Search (solution/org) Relevance team label Dec 5, 2025

markjhoy requested a review from a team December 5, 2025 20:37

elasticsearchmachine added the Team:Search - Relevance The Search organization Search Relevance team label Dec 5, 2025

markjhoy added the >non-issue label Dec 5, 2025

Merge branch 'main' into markjhoy/add_query_vector_builder_support_di…

94eb716

…versify_retriever

github-actions bot deployed to docs-preview December 5, 2025 21:30 View deployment

kderusso reviewed Dec 5, 2025

View reviewed changes

Add query_vector_builder Support to Diversify Retriever #139094

Are you sure you want to change the base?

Add query_vector_builder Support to Diversify Retriever #139094

Conversation

markjhoy commented Dec 5, 2025

Uh oh!

github-actions bot commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions bot commented Dec 5, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

markjhoy commented Dec 5, 2025

Uh oh!

elasticsearchmachine commented Dec 5, 2025

Uh oh!

elasticsearchmachine commented Dec 5, 2025

Uh oh!

kderusso left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markjhoy Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add `query_vector_builder` Support to Diversify Retriever #139094

Add `query_vector_builder` Support to Diversify Retriever #139094

github-actions bot commented Dec 5, 2025 •

edited

Loading

markjhoy Dec 5, 2025 •

edited

Loading