You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by "ilariapet (via GitHub)" <gi...@apache.org> on 2025/09/26 10:04:59 UTC

[PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

ilariapet opened a new pull request, #3705:
URL: https://github.com/apache/solr/pull/3705

   https://issues.apache.org/jira/browse/SOLR-17813
   
   <!--
   _(If you are a project committer then you may remove some/all of the following template.)_
   
   Before creating a pull request, please file an issue in the ASF Jira system for Solr:
   
   * https://issues.apache.org/jira/projects/SOLR
   
   For something minor (i.e. that wouldn't be worth putting in release notes), you can skip JIRA.
   To create a Jira issue, you will need to create an account there first.
   
   The title of the PR should reference the Jira issue number in the form:
   
   * SOLR-####: <short description of problem or changes>
   
   SOLR must be fully capitalized. A short description helps people scanning pull requests for items they can work on.
   
   Properly referencing the issue in the title ensures that Jira is correctly updated with code review comments and commits. -->
   
   
   # Description
   
   Apache Lucene implemented a version of knn vector query called SeededKnnVectorQuery that provides a query seed to initiate the vector search (entry points in the HNSW graph exploration) based on [Lexically-Accelerated Dense Retrieval](https://arxiv.org/pdf/2307.16779)
   
   # Solution
   
   This PR introduces a new optional parameter for the current KNN query parser: `seed`.
   The seed parameter can be any valid Solr query, allowing traditional query logic to guide the vector search in a hybrid-like fashion.
   
   Added a new method `getSeedQuery()` that parses the seed parameter and returns the corresponding Lucene Query.
   
   When a seed query is present, the KNN vector query is wrapped with SeededKnnVectorQuery:
   
   - SeededKnnVectorQuery.fromFloatQuery(...) for FLOAT32 vectors.
   
   - SeededKnnVectorQuery.fromByteQuery(...) for BYTE vectors.
   
   If no seed is provided, the parser behaves as before and executes a "standard" KNN query.
   
   Currently seed and earlyTermination parameters cannot be used together due to Lucene Issue [#14688](https://github.com/apache/lucene/pull/14688). Solr must be upgraded to a Lucene version that includes this patch.
   
   # Tests
   
   - Test to verify that when the seed parameter is provided, the SeededKnnVectorQuery is executed (both float and byte).
   - Test to verify that when the seed parameter is provided but blank, it is treated as null, and no additional seed logic is applied.
   - Test to verify that when the seed parameter is provided with an invalid value, Solr throws a BAD_REQUEST exception.
   - Test to verify that when both seed and early termination parameters are provided, Solr throws a BAD_REQUEST exception.
   
   # Checklist
   
   Please review the following and check all that apply:
   
   - [X] I have reviewed the guidelines for [How to Contribute](https://github.com/apache/solr/blob/main/CONTRIBUTING.md) and my code conforms to the standards described there to the best of my ability.
   - [X] I have created a Jira issue and added the issue ID to my pull request title.
   - [X] I have given Solr maintainers [access](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork) to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
   - [X] I have developed this patch against the `main` branch.
   - [X] I have run `./gradlew check`.
   - [X] I have added tests for my changes.
   - [X] I have added documentation for the [Reference Guide](https://github.com/apache/solr/tree/main/solr/solr-ref-guide)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "ilariapet (via GitHub)" <gi...@apache.org>.
ilariapet commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2401529198


##########
solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java:
##########
@@ -88,6 +94,17 @@ public EarlyTerminationParams getEarlyTerminationParams() {
     return new EarlyTerminationParams(enabled, saturationThreshold, patience);
   }
 
+  protected Query getSeedQuery() throws SolrException, SyntaxError {
+    String seed = localParams.get(SEED);
+    if (seed == null) return null;
+    if (seed.isBlank()) {
+      log.warn("Seed query is blank, defaulting to null");
+      return null;

Review Comment:
   Thank you very much @cpoerschke for your draft PR, which inspired me, and for your review. I was also uncertain about whether to throw the exception or leave it less restrictive, but I agree with you that it’s better to throw the exception.



##########
solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java:
##########
@@ -88,6 +94,17 @@ public EarlyTerminationParams getEarlyTerminationParams() {
     return new EarlyTerminationParams(enabled, saturationThreshold, patience);
   }
 
+  protected Query getSeedQuery() throws SolrException, SyntaxError {
+    String seed = localParams.get(SEED);
+    if (seed == null) return null;
+    if (seed.isBlank()) {
+      log.warn("Seed query is blank, defaulting to null");
+      return null;

Review Comment:
   Thank you very much @cpoerschke for your draft PR, which inspired me, and for your review. I was also uncertain about whether to throw the exception or leave it less "restrictive", but I agree with you that it’s better to throw the exception.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "cpoerschke (via GitHub)" <gi...@apache.org>.
cpoerschke commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2382911378


##########
solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java:
##########
@@ -88,6 +94,17 @@ public EarlyTerminationParams getEarlyTerminationParams() {
     return new EarlyTerminationParams(enabled, saturationThreshold, patience);
   }
 
+  protected Query getSeedQuery() throws SolrException, SyntaxError {
+    String seed = localParams.get(SEED);
+    if (seed == null) return null;
+    if (seed.isBlank()) {
+      log.warn("Seed query is blank, defaulting to null");
+      return null;

Review Comment:
   minor/subjective: perhaps `throw new SolrException` instead



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "cpoerschke (via GitHub)" <gi...@apache.org>.
cpoerschke commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2439992640


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -457,6 +457,26 @@ Here's an example of a `knn` search using the early termination with input param
 [source,text]
 ?q={!knn f=vector topK=10 earlyTermination=true saturationThreshold=0.989 patience=10}[1.0, 2.0, 3.0, 4.0]
 
+`seedQuery`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A query seed to initiate the vector search, i.e. entry points in the HNSW graph exploration. Solr relies on the Lucene’s implementation of SeededKnnVectorQuery based on https://arxiv.org/pdf/2307.16779[Lexically-Accelerated Dense Retrieval (2023)].

Review Comment:
   ```suggestion
   A query seed to initiate the vector search, i.e. entry points in the HNSW graph exploration. Solr relies on Lucene’s implementation of {lucene-javadocs}/core/org/apache/lucene/search/SeededKnnVectorQuery.html[SeededKnnVectorQuery] based on https://arxiv.org/pdf/2307.16779[Lexically-Accelerated Dense Retrieval (2023)].
   ```
   
   https://lucene.apache.org/core/10_3_1/core/org/apache/lucene/search/SeededKnnVectorQuery.html



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "ilariapet (via GitHub)" <gi...@apache.org>.
ilariapet commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2444021308


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -457,6 +457,26 @@ Here's an example of a `knn` search using the early termination with input param
 [source,text]
 ?q={!knn f=vector topK=10 earlyTermination=true saturationThreshold=0.989 patience=10}[1.0, 2.0, 3.0, 4.0]
 
+`seedQuery`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: none
+|===
++
+A query seed to initiate the vector search, i.e. entry points in the HNSW graph exploration. Solr relies on the Lucene’s implementation of SeededKnnVectorQuery based on https://arxiv.org/pdf/2307.16779[Lexically-Accelerated Dense Retrieval (2023)].

Review Comment:
   Agree, thanks.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "alessandrobenedetti (via GitHub)" <gi...@apache.org>.
alessandrobenedetti merged PR #3705:
URL: https://github.com/apache/solr/pull/3705


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "ilariapet (via GitHub)" <gi...@apache.org>.
ilariapet commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2401318989


##########
solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java:
##########
@@ -16,20 +16,25 @@
  */
 package org.apache.solr.search.neural;
 
+import java.lang.invoke.MethodHandles;
 import java.util.Optional;
 import org.apache.lucene.search.Query;
 import org.apache.solr.common.SolrException;
 import org.apache.solr.common.params.SolrParams;
 import org.apache.solr.request.SolrQueryRequest;
 import org.apache.solr.schema.DenseVectorField;
 import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
 import org.apache.solr.search.SyntaxError;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 public class KnnQParser extends AbstractVectorQParserBase {
 
   // retrieve the top K results based on the distance similarity function
   protected static final String TOP_K = "topK";
   protected static final int DEFAULT_TOP_K = 10;
+  protected static final String SEED = "seed";

Review Comment:
   seedQuery



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "ilariapet (via GitHub)" <gi...@apache.org>.
ilariapet commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2401529198


##########
solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java:
##########
@@ -88,6 +94,17 @@ public EarlyTerminationParams getEarlyTerminationParams() {
     return new EarlyTerminationParams(enabled, saturationThreshold, patience);
   }
 
+  protected Query getSeedQuery() throws SolrException, SyntaxError {
+    String seed = localParams.get(SEED);
+    if (seed == null) return null;
+    if (seed.isBlank()) {
+      log.warn("Seed query is blank, defaulting to null");
+      return null;

Review Comment:
   Thank you very much @cpoerschke for your draft PR, which inspired me, and for your review. I was also uncertain about whether to throw the error or leave it less restrictive, but I agree with you that it’s better to throw the error.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "cpoerschke (via GitHub)" <gi...@apache.org>.
cpoerschke commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2439742294


##########
solr/core/src/test/org/apache/solr/search/neural/KnnQParserTest.java:
##########
@@ -1198,4 +1198,125 @@ public void onlyOneInputParam_shouldThrowException() {
                 vectorToSearch)),
         SolrException.ErrorCode.BAD_REQUEST);
   }
+
+  @Test
+  public void knnQueryWithSeedQuery_shouldPerformSeededKnnVectorQuery() {
+    // Test to verify that when the seedQuery parameter is provided, the SeededKnnVectorQuery is
+    // executed
+    // (float).
+    String vectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+
+    assertQ(
+        req(
+            CommonParams.Q,
+            "{!knn f=vector topK=4 seedQuery='id:(1 4 7 8 9)'}" + vectorToSearch,
+            "fl",
+            "id",
+            "debugQuery",
+            "true"),
+        "//result[@numFound='4']",
+        "//str[@name='parsedquery'][.='SeededKnnVectorQuery(SeededKnnVectorQuery{seed=id:1 id:4 id:7 id:8 id:9, seedWeight=null, delegate=KnnFloatVectorQuery:vector[1.0,...][4]})']");
+  }
+
+  @Test
+  public void byteKnnQueryWithSeedQuery_shouldPerformSeededKnnVectorQuery() {
+    // Test to verify that when the seedQuery parameter is provided, the SeededKnnVectorQuery is
+    // executed
+    // (byte).
+
+    String vectorToSearch = "[2, 2, 1, 3]";
+
+    // BooleanQuery
+    assertQ(
+        req(
+            CommonParams.Q,
+            "{!knn f=vector_byte_encoding topK=4 seedQuery='id:(1 4 7 8 9)'}" + vectorToSearch,
+            "fl",
+            "id",
+            "debugQuery",
+            "true"),
+        "//result[@numFound='4']",
+        "//str[@name='parsedquery'][.='SeededKnnVectorQuery(SeededKnnVectorQuery{seed=id:1 id:4 id:7 id:8 id:9, seedWeight=null, delegate=KnnByteVectorQuery:vector_byte_encoding[2,...][4]})']");
+  }
+
+  @Test
+  public void knnQueryWithBlankSeed_shouldThrowException() {
+    // Test to verify that when the seedQuery parameter is provided but blank, Solr throws a
+    // BAD_REQUEST exception.
+    String vectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+
+    assertQEx(
+        "Blank seed query should throw Exception",
+        "'seedQuery' parameter is present but is blank: please provide a valid query",
+        req(CommonParams.Q, "{!knn f=vector topK=4 seedQuery=''}" + vectorToSearch),
+        SolrException.ErrorCode.BAD_REQUEST);
+  }
+
+  @Test
+  public void knnQueryWithInvalidSeedQuery_shouldThrowException() {
+    // Test to verify that when the seedQuery parameter is provided with an invalid value, Solr
+    // throws a
+    // BAD_REQUEST exception.
+    String vectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+
+    assertQEx(
+        "Invalid seed query should throw Exception",
+        "Cannot parse 'id:'",
+        req(CommonParams.Q, "{!knn f=vector topK=4 seedQuery='id:'}" + vectorToSearch),
+        SolrException.ErrorCode.BAD_REQUEST);
+  }
+
+  @Test
+  public void knnQueryWithKnnSeedQuery_shouldPerformSeededKnnVectorQuery() {
+    // Test to verify that when the seedQuery parameter itself is a knn query, it is correctly
+    // parsed and applied as the seed for the main knn query.
+    String mainVectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+    String seedVectorToSearch = "[0.1, 0.2, 0.3, 0.4]";
+
+    assertQ(
+        req(
+            CommonParams.Q,
+            "{!knn f=vector topK=4 seedQuery=$seedQuery}" + mainVectorToSearch,
+            "seedQuery",
+            "{!knn f=vector topK=4}" + seedVectorToSearch,

Review Comment:
   Thanks for adding this test case using [parameter dereferencing](https://solr.apache.org/guide/solr/latest/query-guide/local-params.html#parameter-dereferencing) style!
   
   How about also adding an example in that style but with non-knn seed to the https://solr.apache.org/guide/solr/latest/getting-started/tutorial-vectors.html#lets-do-some-vector-searches list of examples?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


Re: [PR] SOLR-17813: Add support for SeededKnnVectorQuery in vector search [solr]

Posted by "ilariapet (via GitHub)" <gi...@apache.org>.
ilariapet commented on code in PR #3705:
URL: https://github.com/apache/solr/pull/3705#discussion_r2444045225


##########
solr/core/src/test/org/apache/solr/search/neural/KnnQParserTest.java:
##########
@@ -1198,4 +1198,125 @@ public void onlyOneInputParam_shouldThrowException() {
                 vectorToSearch)),
         SolrException.ErrorCode.BAD_REQUEST);
   }
+
+  @Test
+  public void knnQueryWithSeedQuery_shouldPerformSeededKnnVectorQuery() {
+    // Test to verify that when the seedQuery parameter is provided, the SeededKnnVectorQuery is
+    // executed
+    // (float).
+    String vectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+
+    assertQ(
+        req(
+            CommonParams.Q,
+            "{!knn f=vector topK=4 seedQuery='id:(1 4 7 8 9)'}" + vectorToSearch,
+            "fl",
+            "id",
+            "debugQuery",
+            "true"),
+        "//result[@numFound='4']",
+        "//str[@name='parsedquery'][.='SeededKnnVectorQuery(SeededKnnVectorQuery{seed=id:1 id:4 id:7 id:8 id:9, seedWeight=null, delegate=KnnFloatVectorQuery:vector[1.0,...][4]})']");
+  }
+
+  @Test
+  public void byteKnnQueryWithSeedQuery_shouldPerformSeededKnnVectorQuery() {
+    // Test to verify that when the seedQuery parameter is provided, the SeededKnnVectorQuery is
+    // executed
+    // (byte).
+
+    String vectorToSearch = "[2, 2, 1, 3]";
+
+    // BooleanQuery
+    assertQ(
+        req(
+            CommonParams.Q,
+            "{!knn f=vector_byte_encoding topK=4 seedQuery='id:(1 4 7 8 9)'}" + vectorToSearch,
+            "fl",
+            "id",
+            "debugQuery",
+            "true"),
+        "//result[@numFound='4']",
+        "//str[@name='parsedquery'][.='SeededKnnVectorQuery(SeededKnnVectorQuery{seed=id:1 id:4 id:7 id:8 id:9, seedWeight=null, delegate=KnnByteVectorQuery:vector_byte_encoding[2,...][4]})']");
+  }
+
+  @Test
+  public void knnQueryWithBlankSeed_shouldThrowException() {
+    // Test to verify that when the seedQuery parameter is provided but blank, Solr throws a
+    // BAD_REQUEST exception.
+    String vectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+
+    assertQEx(
+        "Blank seed query should throw Exception",
+        "'seedQuery' parameter is present but is blank: please provide a valid query",
+        req(CommonParams.Q, "{!knn f=vector topK=4 seedQuery=''}" + vectorToSearch),
+        SolrException.ErrorCode.BAD_REQUEST);
+  }
+
+  @Test
+  public void knnQueryWithInvalidSeedQuery_shouldThrowException() {
+    // Test to verify that when the seedQuery parameter is provided with an invalid value, Solr
+    // throws a
+    // BAD_REQUEST exception.
+    String vectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+
+    assertQEx(
+        "Invalid seed query should throw Exception",
+        "Cannot parse 'id:'",
+        req(CommonParams.Q, "{!knn f=vector topK=4 seedQuery='id:'}" + vectorToSearch),
+        SolrException.ErrorCode.BAD_REQUEST);
+  }
+
+  @Test
+  public void knnQueryWithKnnSeedQuery_shouldPerformSeededKnnVectorQuery() {
+    // Test to verify that when the seedQuery parameter itself is a knn query, it is correctly
+    // parsed and applied as the seed for the main knn query.
+    String mainVectorToSearch = "[1.0, 2.0, 3.0, 4.0]";
+    String seedVectorToSearch = "[0.1, 0.2, 0.3, 0.4]";
+
+    assertQ(
+        req(
+            CommonParams.Q,
+            "{!knn f=vector topK=4 seedQuery=$seedQuery}" + mainVectorToSearch,
+            "seedQuery",
+            "{!knn f=vector topK=4}" + seedVectorToSearch,

Review Comment:
   It’s a good idea, thanks. I’ll just consider whether to add it here or include it in a dedicated PR.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org