Lucene 9.11: Make AbstractKnnVectorQuery.searchLeaf() overridable to enable custom KNN instrumentation

[Kulieshova]

Description

Problem

In Lucene 9.11, the searchLeaf() method in AbstractKnnVectorQuery is declared private, preventing custom subclasses from overriding the search execution logic. This restricts the ability to build custom instrumentation or extend search behaviors.
Our team at Uber is working on improving visibility and control over KNN query execution in a fork of Lucene 9.11. We developed functionality to track exact vs. approximate search usage and fallback patterns, which is currently impossible to get from Lucene itself.
To enable this, we created a subclass of KnnFloatVectorQuery that overrides searchLeaf() to route execution through custom logic. However, due to the method’s private access modifier in 9.11, this override is not possible without modifying the core Lucene code. While we currently use a custom jar with the modified access for testing, we cannot safely ship this setup to production or rely on it long-term.

Solution

Change the access modifier of searchLeaf() method from private to public in Lucene 9.11, as already implemented in commit d279af1 on the main branch. This change is already upstream and therefore changing it with this PR presents minimal logic changes and maintains full backward compatibility with all existing usages.

[msokolov]

I think what you are asking for is already present on branch_10x and thus would be release with the next minor release (10.3), so I don't think there's anything for us to do except get a release out? You could already build with branch_10x if you like. Or .. maybe you would like to see a 9.12 or 9.11.1 release with this change? But I don't think that's likely for something like this. Maybe instead you could copy the entire AbstractKnnVectorQuery into your Uber libraries, modify it as you chose, and then switch back to Lucene's implementation once you are able to upgrade to Lucene 10?

[Kulieshova]

@msokolov You're right that this change is already present on the branch_10x, and we look forward to adopting it once we upgrade. However, our internal systems are currently tied to Lucene 9.11.1, and due to stability and compatibility constraints across teams, we do not anticipate switching from 9.11.1 in the near future.

That said, this is a very minimal change that doesn’t introduce any logic changes or risk regressions, and is already accepted upstream. However, this backporting is a key change that is needed to support critical business needs.
We currently rely on a custom jar with this patch, but would much prefer aligning with an official release for long-term maintainability and consistency. We're happy to contribute and maintain the backport PR to make this as low-effort as possible on your end.

@msfroh @yupeng9 @karthi01ec

[msfroh]

Given that it's a minimal change that reflects "the future", I don't see why we can't just apply the change in Uber's internal fork of Lucene 9.11.

Adding it to the official Lucene 9.11 branch would be a violation of release practice. Bug fixes can be backported to the Lucene 9.12 branch, but I'm not even sure if we would backport a critical fix to 9.11, since upgrading to a fixed 9.11 isn't significantly different from upgrading to a fixed 9.12. I also don't think the change warrants being backported to 9.12 either, since it's not a breakage in existing functionality.

Just fix it in Uber's internal code repo.

[jpountz]

For visibility, we are moving the decision between approximate and exact from the query to KnnVectorsFormat: #14963. This will allow Lucene to bypass the creation of the HNSW graph on small (NRT) segments and always perform an exact search.

[jpountz]

To be more explicit, the above means that it will not be possible to track approximate vs. exact statistics by extending the query. This will have to be done at the file format level.

[benwtrent]

I don't understand the benefit of tracking "exact vs approximate". I would have thought the only useful statistics would be number of vector ops for the given latency.