SOLR-18245: Add reRankCutoff output on LTR queries

[shawdm]

https://issues.apache.org/jira/browse/SOLR-18245

Description

When using LTR, a client may need to know the sort score that a document would have required to have been eligible for rerank by LTR.

Solution

This PR adds a echoReRankCutoff local parameter to the LTR rerank query (e.g. {!ltr model=myModel reRankDocs=100 echoReRankCutoff=true}. When this parameter is set to true, the responseHeader will include a reRankCutoff field which will return the score of the lowest ranked document that was included for rerank. When multiple sorts are used (e.g. sort=price desc,discount asc), the response header contains the cutoff value for each sort, in order.

Example Response

"responseHeader": {
  "status": 0,
  "QTime": 1,
  "reRankCutoff": [
    11.99,
    2.20
  ]
}

Tests

• Tests added to TestLTRQParserPlugin to test core functionality.
• New test class TestLTRReRankCutoffOnSolrCloud added to test for sharded cases. This has also meant I've extracted out shared code from TestLTROnSolrCloud in to a common AbstractLTRSolrCloudTestBase.

Checklist

Please review the following and check all that apply:

• I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
• I have created a Jira issue and added the issue ID to my pull request title.
• I have given Solr maintainers access to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
• I have developed this patch against the main branch.
• I have run ./gradlew check.
• I have added tests for my changes.
• I have added documentation for the Reference Guide
• I have added a changelog entry for my change

[shawdm]

Created this to share code between TestLTROnSolrCloud and the new TestLTRReRankCutoffOnSolrCloud. The new tests needed to be separate as the existing one can create a SolrCloud with a single shard and I want to assert behaviour when there are multiple shards.

[shawdm]

The tests are timing out on the setup stage (removing previous clone). @mkhludnev I can see you retried this and it timed out again. I don't have the option to retry...

I don't think this is related to the PR itself, it's not actually running the tests, but is there something I've done or missed to cause this failure? Or something I can do to fix it?

[shawdm]

@mkhludnev thanks for the review and re-running the tests. Are you able to merge this? Or anything else I need to do before you can?

[mkhludnev]

Hello @shawdm, thanks for your contribution.
I’m okay with merging this, but I’m hesitating a little.
A second 👀 from someone with more LTR experience would be helpful. @epugh, what do you think?

[epugh]

Hello @shawdm, thanks for your contribution. I’m okay with merging this, but I’m hesitating a little. A second 👀 from someone with more LTR experience would be helpful. @epugh, what do you think?

I am not the right person for this area ;-(. I think @cpoerschke is probably the strongest person to review this, she has done the most work in this space. Maybe @alessandrobenedetti could review (or suggest someone!)

[shawdm]

Hi @cpoerschke @alessandrobenedetti have you had chance to look at this? Any thoughts or, alternatively, suggestions of who else might have the expertise?

[Copilot]

Pull request overview

Adds an optional echoReRankCutoff local parameter for LTR rerank queries so clients can see the first-pass cutoff value(s) that determined eligibility for reranking. This is implemented by capturing the cutoff in the rerank collector and exposing it in responseHeader (and, for distributed queries, aggregating shard-local values into a dedicated header field).

Changes:

• Add echoReRankCutoff support to LTR rerank parsing and propagate the request intent via request context.
• Compute and emit reRankCutoff in the response header (supporting single- and multi-sort cutoffs, including schema-aware sort value marshalling).
• For distributed queries, aggregate shard-reported cutoffs into responseHeader.reRankCutoffByShard, and add/refactor tests + reference-guide documentation + changelog entry.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
solr/solr-ref-guide/modules/query-guide/pages/learning-to-rank.adoc	Documents echoReRankCutoff, reRankCutoff, and reRankCutoffByShard with examples.
solr/modules/ltr/src/test/org/apache/solr/ltr/TestLTRWithSort.java	Adds tests for cutoff reporting when sorting by function(s).
solr/modules/ltr/src/test/org/apache/solr/ltr/TestLTRReRankCutoffOnSolrCloud.java	Adds SolrCloud/distributed coverage asserting shard-local cutoff reporting.
solr/modules/ltr/src/test/org/apache/solr/ltr/TestLTRQParserPlugin.java	Adds core LTR tests for header presence/absence and cutoff value types/order.
solr/modules/ltr/src/test/org/apache/solr/ltr/TestLTROnSolrCloud.java	Refactors to use a shared SolrCloud LTR test base.
solr/modules/ltr/src/test/org/apache/solr/ltr/AbstractLTRSolrCloudTestBase.java	New shared SolrCloud setup/index/model-loading base for LTR tests.
solr/modules/ltr/src/java/org/apache/solr/ltr/search/LTRQParserPlugin.java	Adds echoReRankCutoff local param and stores intent in request context.
solr/core/src/java/org/apache/solr/search/ReRankCollector.java	Computes cutoff from the last eligible first-pass doc and writes it to responseHeader when enabled.
solr/core/src/java/org/apache/solr/search/QueryCommand.java	Adds sortSchemaFields plumbing so cutoff sort values can be marshalled correctly.
solr/core/src/java/org/apache/solr/search/AbstractReRankQuery.java	Defines shared constants for cutoff header keys and request-context key.
solr/core/src/java/org/apache/solr/handler/component/ResponseBuilder.java	Populates QueryCommand.sortSchemaFields from SortSpec.
solr/core/src/java/org/apache/solr/handler/component/QueryComponent.java	Merges shard reRankCutoff into top-level reRankCutoffByShard for distributed queries.
changelog/unreleased/SOLR-18245-rerank-cutoff-value.yml	Adds unreleased changelog entry describing the new optional header output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mkhludnev]

@shawdm thank you.
Please create cherrypick MR to https://github.com/apache/solr/tree/branch_10x
DONE #4560

[mkhludnev]

https://ci-builds.apache.org/job/Solr/job/Solr-Test-main/14191/
so far the failed test seems like a unrelated noise . Clicked rebuild

[mkhludnev]

ok. tests passed in main https://ci-builds.apache.org/job/Solr/job/Solr-Test-main/14192/

[shawdm]

Thanks @mkhludnev - I can see you've done the cherry pick to branch_10x too - appreciate your help with this.