SOLR-17715: un-deprecate CommonParams.QT and SolrQuery.setRequestHandler have been un-deprecat…

[dsmiley]

CommonParams.QT and SolrQuery.setRequestHandler have been un-deprecated.  Nonetheless, if your code makes explicit reference to "qt" when constructing a standard request, there is usually a better way.

No JIRA for un-deprecation but FYI the JIRA that originally deprecated them is: https://issues.apache.org/jira/browse/SOLR-17715 and got released to 10.0. That same JIRA was also recently used in #4397 in relation to improving QueryRequest to stop sending "qt" (will make 10.1 & 9.11). I originally thought maybe we could remove it but that's not realistic and/or is more disruptive than I want to impose on our users.

[gerlowskija]

IMO deprecation was the right decision here.

I gather from some of the discussion on SOLR-17715 that there were some wrinkles, the SolrClient.query method overloads being a tough sticking point in particular. But IMO those are solve-able problems. Potential workarounds for that:

• give SolrClient a protected QueryRequest createQueryRequest(...) that folks can extend if they want to customize how QueryRequests are constructed in these syntax-sugar methods
• give SolrClient getters/setters or builder-methods to control the 'default' query and update endpoints used by query(...), add(...), etc.
• offer users a new SolrClient implementation that wraps/delegates to an existing client except for taking and using "default" query and update endpoints

Hopefully one of those approaches would be palatable?

[dsmiley]

"qt" has uses for sub-query transformer, in solrj-streaming, and probably elsewhere. So I don't think it should be deprecated. This PR enhances documentation on it to discourage needless use of it.

That leaves SolrQuery.setRequestHandler.

I like your first two suggestions... but nonetheless I think deprecation was premature. A colleague saw the deprecation and then simply converted a usage to solrQuery.set("qt", "/ourHandler") which was particularly sad and it's the opposite outcome I hoped for -- more (explicit) use of "qt". Maybe additional deprecation words could communicate the intent. Or we just defer deprecation until more convenient methods are in-place.

[gerlowskija]

"qt" has uses for sub-query transformer, in solrj-streaming,

I'm completely unfamiliar with the sub-query transformer implementation so I won't even attempt to speak to that. But from what I know of solrj-streaming a client change like what I proposed above would allow us to remove the 'qt' usage there, wouldn't it? Or am I missing something?

I guess I understand that there are things that currently rely on 'qt'. And I agree those need thought about and addressed before we just rip 'qt' out. But that's not totally unheard of in our deprecations, and IMO it doesn't mean that the deprecation should be reversed. We just have a bit of work to do before anything can be truly removed is all.

If you're willing to pause the deprecation-reversal in this PR for a bit, I can spike out one of the approaches above to see whether its viable and how it looks as a 'qt' replacement. Wdyt?

[dsmiley]

I'm willing to descope setRequestHandler out of here.

"qt" has some uses here & there outside of it's very original and now needless scope. solrconfig.xml warming firstSearcher can use "qt". So can https://solr.apache.org/guide/solr/latest/query-guide/document-transformers.html#subquery and https://solr.apache.org/guide/solr/latest/query-guide/stream-source-reference.html and the /ping request handler to choose what underlying handler to actually use.

[rahulgoswami]

I tried to revisit my comments on SOLR-17715 and recollect hitting a wall with respect to truly being able to remove "qt" . I will need to come back to this PR once I have refreshed my memory of some of those details and correlate to @gerlowskija's suggestions.

Having said that, if the motivation behind reversing the deprecation is the unintended effect you alluded to - solrQuery.set("qt", "/ourHandler") - which I agree makes the code worse for tracking and fixing when qt is eventually removed, can this be solved by adding a message in the deprecation itself to the effect of "don't do something like this - solrQuery.set("qt", "/ourHandler") - to get around the deprecation"?

One caution against reversing the deprecation in the world of agentic coding is that un-deprecating the method might encourage usage of "qt" by LLMs since there is no directive around avoiding it, vs a clearer deprecation message which can nudge them towards a preferred pattern (request.setPath() and request.process()). I admit I am making an assumption here that LLMs do consider deprecations while using APIs.