You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by mc...@apache.org on 2026/09/29 20:07:37 UTC

(lucene) branch main updated: Make DocAndScoreQuery public (#16686)

This is an automated email from the ASF dual-hosted git repository.

mccullocht pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/lucene.git


The following commit(s) were added to refs/heads/main by this push:
     new c857eeebe7e Make DocAndScoreQuery public (#16686)
c857eeebe7e is described below

commit c857eeebe7ea60d7952c77784d84dea7ed8755de
Author: Trevor McCulloch <mc...@gmail.com>
AuthorDate: Tue Sep 29 13:07:30 2026 -0700

    Make DocAndScoreQuery public (#16686)
    
    This is useful if you are writing your own KNN query classes and wish to share the same execution model as the existing (package private) AbstractKnnVectorQuery.
---
 lucene/CHANGES.txt                                 |  2 ++
 .../org/apache/lucene/search/DocAndScoreQuery.java | 31 +++++++++++++++++++---
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index e016c993584..652b92dcb0a 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -387,6 +387,8 @@ API Changes
 
 * GITHUB#16647: Add KnnVectorsReader.getVectorCount to read vector counts from metadata (Chris Hegarty)
 
+* GITHUB#16686: Make DocAndScoreQuery public (Trevor McCulloch)
+
 New Features
 ---------------------
 * GITHUB#16722: Support user dictionary in ThaiTokenizer and ThaiTokenizerFactory.
diff --git a/lucene/core/src/java/org/apache/lucene/search/DocAndScoreQuery.java b/lucene/core/src/java/org/apache/lucene/search/DocAndScoreQuery.java
index d4dcea8a2d4..4ba4c473359 100644
--- a/lucene/core/src/java/org/apache/lucene/search/DocAndScoreQuery.java
+++ b/lucene/core/src/java/org/apache/lucene/search/DocAndScoreQuery.java
@@ -28,11 +28,11 @@ import org.apache.lucene.index.LeafReaderContext;
 import org.apache.lucene.index.ReaderUtil;
 
 /** A query that wraps precomputed documents and scores */
-class DocAndScoreQuery extends Query {
+public class DocAndScoreQuery extends Query {
 
   /** Optional hook to explain why a doc is missing. Returns null for the generic message. */
   @FunctionalInterface
-  interface NoMatchExplainer {
+  public interface NoMatchExplainer {
     Explanation explain(LeafReaderContext context, int doc, int topN) throws IOException;
   }
 
@@ -91,11 +91,34 @@ class DocAndScoreQuery extends Query {
     this.noMatchExplainer = noMatchExplainer;
   }
 
-  static Query createDocAndScoreQuery(IndexReader reader, TopDocs topK, int reentryCount) {
+  /**
+   * Create a query that matches exactly the documents in {@code topK} with precomputed scores.
+   *
+   * @see #createDocAndScoreQuery(IndexReader, TopDocs, int, NoMatchExplainer)
+   */
+  public static Query createDocAndScoreQuery(IndexReader reader, TopDocs topK, int reentryCount) {
     return createDocAndScoreQuery(reader, topK, reentryCount, null);
   }
 
-  static Query createDocAndScoreQuery(
+  /**
+   * Create a query that matches exactly the documents in {@code topK} with precomputed scores. The
+   * docids in {@code topK} must be global docids with respect to {@code reader}, and the query may
+   * only be executed against that reader; {@link Query#createWeight(IndexSearcher, ScoreMode,
+   * float)} throws {@link IllegalStateException} otherwise.
+   *
+   * <p>The entries of {@code topK} are expected in descending score order, as produced by a
+   * nearest-neighbors search. Note that the {@link TopDocs#scoreDocs} array is sorted by docid in
+   * place, and the max score is captured from its first entry before that happens.
+   *
+   * @param reader the reader the {@code topK} docids were collected against
+   * @param topK the documents to match and their scores; must be non-empty and is modified in place
+   *     as described above
+   * @param reentryCount the number of leaves that were re-entered by the search that produced
+   *     {@code topK}, purely informational
+   * @param noMatchExplainer optional hook producing a richer explanation for documents not in
+   *     {@code topK}; may be null
+   */
+  public static Query createDocAndScoreQuery(
       IndexReader reader, TopDocs topK, int reentryCount, NoMatchExplainer noMatchExplainer) {
     int len = topK.scoreDocs.length;
     assert len > 0;