Skip to content

Support findAndRerank single leg retrieval - #2678

Merged
Hazel-Datastax merged 13 commits into
mainfrom
hazel/farr-single-leg
Nov 21, 2026
Merged

Hazel-Datastax merged 13 commits into
mainfrom
hazel/farr-single-leg

Conversation

@Hazel-Datastax

@Hazel-Datastax Hazel-Datastax commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

What this PR does:
findAndRerank now supports a sort single leg retrieval: $vectorize, $vector or $lexical

  • The command reads with one leg, up to rerankCandidateLimit documents (or the configured default).
  • $vectorize and $lexical give the default rerank query and rerank field. A $vector sort needs the rerankQuery and rerankOn options. The options always win.

Out of scope:

Which issue(s) this PR fixes:
Fixes #2602

Checklist

  • Changes manually tested
  • Automated Tests added/updated
  • Documentation added/updated
  • CLA Signed: DataStax CLA

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

📈 Unit Test Coverage Delta vs Main Branch

Metric Value
Main Branch 57.12%
This PR 57.21%
Delta 🟢 +0.09%
✅ Coverage improved!

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Unit Test Coverage Report

Overall Project 57.21% -0.04% 🍏
Files changed 90.27% 🍏

File Coverage
RerankingQuery.java 100% 🍏
FindAndRerankOperationBuilder.java 95.33% 🍏
FindAndRerankPlanner.java 94.36% -5.39% 🍏

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

📈 Integration Test Coverage Delta vs Main Branch (dse69-it)

Metric Value
Main Branch 72.75%
This PR 72.92%
Delta 🟢 +0.17%
✅ Coverage improved!

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Integration Test Coverage Report (dse69-it)

Overall Project 72.92% -0.11% 🍏
Files changed 73.89% 🍏

File Coverage
FindAndRerankOperationBuilder.java 86.19% 🍏
FindAndRerankPlanner.java 78.31% -13.85% 🍏
RerankingQuery.java 76.92% -5.49% 🍏

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

📈 Integration Test Coverage Delta vs Main Branch (hcd-it)

Metric Value
Main Branch 74.21%
This PR 74.37%
Delta 🟢 +0.16%
✅ Coverage improved!

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Integration Test Coverage Report (hcd-it)

Overall Project 74.37% -0.04% 🍏
Files changed 90.27% 🍏

File Coverage
FindAndRerankOperationBuilder.java 95.33% 🍏
FindAndRerankPlanner.java 94.36% -5.39% 🍏
RerankingQuery.java 82.42% 🍏

Base automatically changed from hazel/farr-rerank-candidate-limit to main November 17, 2026 23:48
@Hazel-Datastax
Hazel-Datastax marked this pull request as ready for review November 19, 2026 02:47
@Hazel-Datastax
Hazel-Datastax requested a review from a team as a code owner November 19, 2026 02:47
/** Query came from the $vectorize sort in the user query. This is the default. */
VECTORIZE,
/** Query came from the $lexical sort in the user query, when the sort is only $lexical. */
LEXICAL,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For a $lexical sort:

  • The rerank query defaults to the $lexical text.
  • The rerank field defaults to $lexical.
  • The rerankQuery and rerankOn options replace these defaults. This is the same rule as for a $vectorize sort and a $hybrid sort.

Example 1, no options:

{"findAndRerank": {
    "filter": {"country": "nz"},
    "sort": {"$lexical": "cheese balls"},
    "options": {}
}}

Lexical read: "I like cheese!". Rerank query: "cheese balls". Rerank field: $lexical.

Example 2, with options:

{"findAndRerank": {
    "filter": {},
    "sort": {"$lexical": "I like cheese!"},
    "options": {
        "rerankQuery": "who loves cheese the most?",
        "rerankOn": "food_preferences",
        "rerankCandidateLimit": 100,
        "limit": 10
    }
}}

The lexical read uses "I like cheese!" and reads up to 100 documents. The reranker compares "who loves cheese the most?" to food_preferences and returns the top 10.

LMK if we don't want to do this

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that looks correct - the $lexical is used for the lexical sort the option.rerankQuery is sent to the rerank model

Comment on lines +196 to +207
switch (command.sortClause()) {
case FindAndRerankSort.MultiLeg ignored ->
getOrDefault(
command.options(),
FindAndRerankCommand.Options::hybridLimits,
FindAndRerankCommand.HybridLimits.DEFAULT);
case FindAndRerankSort.SingleLeg ignored -> {
var readLimit = plan.legs().getFirst().readLimit();
yield new FindAndRerankCommand.HybridLimits(
readLimit, readLimit, CommandFeatures.EMPTY);
}
});

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just reuse the hack to keep things moving, will have another PR to handle this properly.

Test: IT sortWithoutHybridReadsRerankCandidateLimitDocuments and unit test setsReadLimitOfOneLegAsHybridLimitsOnCommandContext ensure it works

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

// error order of the command: e.g. {"$hybrid": ""} with no rerankQuery fails with
// MISSING_RERANK_QUERY_TEXT, not MISSING_HYBRID_SORT_VALUE
// MISSING_RERANK_QUERY_TEXT, not MISSING_HYBRID_SORT_VALUE. And a command with no sort and no
// options fails with MISSING_RERANK_QUERY_TEXT, not UNSUPPORTED_FIND_AND_RERANK_SORT.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can have another PR to make the error order better

Comment on lines +250 to +255
case FindAndRerankSort.VectorLeg(VectorizeSortExpression ignored) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, null, null, readLimit);
case FindAndRerankSort.VectorLeg(VectorSortExpression(var vector)) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, vector, null, readLimit);
case FindAndRerankSort.LexicalLeg(LexicalSortExpression(var lexicalText)) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.LEXICAL_LEG, null, lexicalText, readLimit);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RerankLeg is an enum tag plus fields that are only valid for some tags (vector, lexicalText). The constructor checks them at runtime. We can change it to a sealed interface with one record per leg, so that an invalid leg cannot be created.

Then we do not need the nulls or the constructor checks, and the builder can switch on the leg and deconstruct it.

LMK if we think it's a good idea to have another PR to refactor

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes I think this is the sort of pattern we discussed - Enums may become hierarchies, and.... I think the inner classes having the same name makes it harder to understand. Even though the outer class has Sort or Plan in it, I think the inner classes need that as well. e.g. FindAndRerankSort.VectorLegSort and FindAndRerankPlan.RerankLegPlan

Comment on lines +322 to +324
return sort instanceof FindAndRerankSort.LexicalLeg(LexicalSortExpression(var lexicalText))
? RerankingQuery.createForLexicalSort(rerankQueryOption, lexicalText)
: RerankingQuery.createForVectorizeSort(rerankQueryOption, vectorizeText(sort));

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can make this better, I just used the simplest way to keep things moving. LMK if we want to improve.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not think decomposition was usable like this. Not sure we can make this any cleaner

Comment on lines -298 to -305
if (isVectorizeSort(command.sortClause())) {
// use the vectorize field, unless the user has overridden
finalRerankField = isRerankOn ? rerankOn : VECTOR_EMBEDDING_TEXT_FIELD;
} else if (isRerankOn) {
// user has to provide a field to rerank on
finalRerankField = rerankOn;
} else {
throw RequestException.Code.MISSING_RERANK_ON.get();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reorganized a bit to make it easier to understand, lmk if we don't want to change

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its good.

Comment on lines +258 to +259
case FindAndRerankSort.FilterLeg ignored ->
throw SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.get();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will have the next PR to support FilterLeg, to keep this PR small

@erichare

Copy link
Copy Markdown
Contributor

Thanks Hazel, a few thoughts:

  • The $lexical defaults (rerankQuery and rerankOn falling back to the $lexical text and field) feel natural to me and match how $vectorize works.
  • +1 on doing the hybridLimits hack, the error order, and FilterLeg as follow-ups. Might be worth linking findAndRerank inner reads do not select full hybridLimits number of records: #1961 on the hack so it stays tracked.
  • A sealed RerankLeg sounds like a nice follow-up. One option is to fold it into the FilterLeg PR, since that adds another leg anyway.
  • For rerankingQuery, a switch on the sort (like passageLocator) might make the FilterLeg fallback more explicit, but the ternary seems fine for now.
  • The passageLocator reorg reads clearer to me, nice job

@amorton amorton left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 I have not done a deep dive on tests though

case FindAndRerankSort.SingleLeg ignored ->
throw SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.get();
case FindAndRerankSort.SingleLeg singleLeg ->
List.of(singleLeg(singleLeg, rerankCandidateLimit));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: which singleLeg is passed to the singleLeg function ? the singleLeg or the singleLeg ? :) On a more serious note, rename the var or function to make it a little easier to read. I think rename the functions to something like build*

/**
* Validate the user-supplied rerankCandidateLimit: it cannot be used with a $hybrid sort, and
* must be inside the dynamic OperationsConfig bounds.
* The read limit for a sort without $hybrid: the user-supplied rerankCandidateLimit, or the

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: comments to explain the logic like this are better inside the function next to the code they are for. Because it is more likely to get updated and checked, it's easier to read things like "use rerankCandidateLimit from X because Y" or "not defined on Y so use it from Z"

}

/**
* The one leg of a sort without $hybrid, it reads at most <code>readLimit</code> documents.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: the comments are a bit too conversational the java standard used to be something like:

First sentence: what does this function do ?
extra paragraphs for extra explaining
@params for the params

then linline comments where they make sense.

Just watch out that code comments are for humans as well as machines.

Comment on lines +252 to +253
case FindAndRerankSort.VectorLeg(VectorSortExpression(var vector)) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, vector, null, readLimit);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 this code looks really clean :)

Comment on lines +250 to +255
case FindAndRerankSort.VectorLeg(VectorizeSortExpression ignored) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, null, null, readLimit);
case FindAndRerankSort.VectorLeg(VectorSortExpression(var vector)) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, vector, null, readLimit);
case FindAndRerankSort.LexicalLeg(LexicalSortExpression(var lexicalText)) ->
new FindAndRerankPlan.RerankLeg(RerankLegType.LEXICAL_LEG, null, lexicalText, readLimit);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes I think this is the sort of pattern we discussed - Enums may become hierarchies, and.... I think the inner classes having the same name makes it harder to understand. Even though the outer class has Sort or Plan in it, I think the inner classes need that as well. e.g. FindAndRerankSort.VectorLegSort and FindAndRerankPlan.RerankLegPlan

/** Query came from the $vectorize sort in the user query. This is the default. */
VECTORIZE,
/** Query came from the $lexical sort in the user query, when the sort is only $lexical. */
LEXICAL,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that looks correct - the $lexical is used for the lexical sort the option.rerankQuery is sent to the rerank model

*/
public static RerankingQuery create(String rerankQuery, String vectorizeText) {
public static RerankingQuery createForVectorizeSort(String rerankQuery, String vectorizeText) {
return create(rerankQuery, vectorizeText, Source.VECTORIZE);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: we dont need createFor* we can just have for* when we have a factory method like thes.

Comment on lines +196 to +207
switch (command.sortClause()) {
case FindAndRerankSort.MultiLeg ignored ->
getOrDefault(
command.options(),
FindAndRerankCommand.Options::hybridLimits,
FindAndRerankCommand.HybridLimits.DEFAULT);
case FindAndRerankSort.SingleLeg ignored -> {
var readLimit = plan.legs().getFirst().readLimit();
yield new FindAndRerankCommand.HybridLimits(
readLimit, readLimit, CommandFeatures.EMPTY);
}
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

case FindAndRerankSort.HybridText hybridText -> hybridText.text();
case FindAndRerankSort.HybridObject hybridObject -> hybridObject.vectorize();
case FindAndRerankSort.SingleLeg ignored -> null;
case FindAndRerankSort.VectorLeg(VectorizeSortExpression(var text)) -> text;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think this function, and few below should move to be default methods on the FindAndRerankSort interface ?

In a classic Object Orientated approach we would define the method as virtual and implement it in the appropirate sub classes.

In this new data orientated approach I am not 100% sure where behavour like this should sit. OR we could say "the only thing dealing with this is the planner, and we keep behaviour out of our data model". Can leave as is for now, more thinking about how we want to handle new data modeling techniques.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will rethink about this later

Comment on lines -298 to -305
if (isVectorizeSort(command.sortClause())) {
// use the vectorize field, unless the user has overridden
finalRerankField = isRerankOn ? rerankOn : VECTOR_EMBEDDING_TEXT_FIELD;
} else if (isRerankOn) {
// user has to provide a field to rerank on
finalRerankField = rerankOn;
} else {
throw RequestException.Code.MISSING_RERANK_ON.get();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its good.

@Hazel-Datastax
Hazel-Datastax merged commit e2d4a2e into main Nov 21, 2026
3 checks passed
@Hazel-Datastax
Hazel-Datastax deleted the hazel/farr-single-leg branch November 21, 2026 02:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Single-leg retrieval

3 participants