You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by "adamjq (via GitHub)" <gi...@apache.org> on 2026/06/16 19:43:57 UTC

[PR] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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

   # Description
   
   The Dense Vector Search page in the Solr Ref Guide currently has a section titled `Usage in Re-Ranking Query`. However, it only contains a single example of re-ranking with the KNN query parser which has an important caveat that this initiates a second pass full KNN query. 
   
   This PR adds documentation for the more efficient re-ranking feature that rerank subsets of documents by direct vector comparisons with the [vectorSimilarity Function](https://solr.apache.org/guide/solr/latest/query-guide/function-queries.html#vectorsimilarity-function) , with some notes about motivations and tradeoffs.
   
   # Solution
   
   - Moves indentation level of `Usage in Re-Ranking Query` in Dense Vector Search ref guide 
   - Adds examples of how to use `{!func}vectorSimilarity` in a re-rank query
   - Adds note about reranking with Dense Vector Fields in Query Re-Ranking page
   
   ## Before
   
   <img width="1486" height="1066" alt="solr_dense_vector_ref_guide_before" src="https://github.com/user-attachments/assets/edee7996-3eac-4117-833b-23597ec468ec" />
   
   ## After
   
   <img width="1490" height="1119" alt="solr_dense_vector_ref_guide_changes" src="https://github.com/user-attachments/assets/3284b706-272d-46cb-ad65-e3ebf00f861f" />
   
   
   # 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.
   - [ ] 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`.
   - [ ] 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)
   - [ ] I have added a [changelog entry](https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc) for my change


-- 
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] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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


-- 
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] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -814,7 +814,37 @@ Some use cases where `includeTags` and/or `excludeTags` may be more useful then
 
 
 
-=== Usage in Re-Ranking Query
+[[vector-reranking]]
+== Usage in Re-Ranking Query
+
+Dense vector similarity scores can be used to xref:query-guide:query-re-ranking.adoc[re-rank] first pass query results.
+Possible use cases include:
+
+* Re-ranking approximate results from a quantized vector field using full fidelity float vectors.
+* Re-ranking lexical search results with dense vector similarity scores.
+
+Details about using the ReRank Query Parser can be found in the xref:query-guide:query-re-ranking.adoc[Query Re-Ranking] section.
+
+=== Re-Ranking with vectorSimilarity Function Query
+
+The xref:query-guide:function-queries.adoc#vectorsimilarity-function[vectorSimilarity()] function can be used with the `{!func}` query parser to re-rank by vector similarity.
+When used as a function query, `vectorSimilarity()` computes the exact similarity for only the candidate documents selected for re-ranking, without traversing the index graph.
+
+Here is an example of re-ranking a lexical query using a `DenseVectorField` named `vector`:
+
+[source,text]
+?q=title:phone&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])
+
+NOTE: The default `reRankOperator` is `add`, which sums the first-pass score and the vector similarity score.
+Since these scores may differ in magnitude, you can adjust `reRankWeight` to control the balance between them, or use `reRankOperator=replace` to score re-ranked documents by vector similarity alone.
+
+When using a quantized vector field type (such as `ScalarQuantizedDenseVectorField`), the KNN first pass scores are computed on the quantized vectors.
+Here is an example of re-ranking those results with exact float similarity scores, where `topK` matches `reRankDocs`:
+
+[source,text]
+?q={!knn f=vector topK=100}[1.0,2.0,3.0,4.0]&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1 reRankOperator=replace}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])

Review Comment:
   After reviewing the code again (with the help of Mr Claude):
   In short: quantised distances are used for both graph construction and graph traversal at query time.
     Full-precision distances are only available through an explicit opt-in
     (FullPrecisionFloatVectorSimilarityValuesSource) That is separate from the ANN search.
     
   In Apache Solr:
   VectorSimilaritySourceParser (VectorSimilaritySourceParser.java:108) builds v1 via
     DenseVectorField.getValueSource() → FloatKnnVectorFieldSource, which reads
         final FloatVectorValues vectorValues = reader.getFloatVectorValues(fieldName);
    and calls
     vectorValues.vectorValue(iterator.index()) — the raw, full-precision stored vector, not
     anything from the HNSW graph or the quantized codec.
     FullPrecisionFloatVectorSimilarityValuesSource.getValues() does exactly the same thing
     (ctx.reader().getFloatVectorValues(fieldName) + vectorSimilarityFunction.compare(...)).
     Both bypass quantization entirely — they're the same data path, just wrapped in two
     different Lucene abstractions (ValueSource/FunctionValues vs. DoubleValuesSource).
   
     So {!func}vectorSimilarity(vector_field, [query]) is already an exact full-precision
     similarity computation, usable today for reranking.



-- 
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] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -814,7 +814,37 @@ Some use cases where `includeTags` and/or `excludeTags` may be more useful then
 
 
 
-=== Usage in Re-Ranking Query
+[[vector-reranking]]
+== Usage in Re-Ranking Query
+
+Dense vector similarity scores can be used to xref:query-guide:query-re-ranking.adoc[re-rank] first pass query results.
+Possible use cases include:
+
+* Re-ranking approximate results from a quantized vector field using full fidelity float vectors.
+* Re-ranking lexical search results with dense vector similarity scores.
+
+Details about using the ReRank Query Parser can be found in the xref:query-guide:query-re-ranking.adoc[Query Re-Ranking] section.
+
+=== Re-Ranking with vectorSimilarity Function Query
+
+The xref:query-guide:function-queries.adoc#vectorsimilarity-function[vectorSimilarity()] function can be used with the `{!func}` query parser to re-rank by vector similarity.
+When used as a function query, `vectorSimilarity()` computes the exact similarity for only the candidate documents selected for re-ranking, without traversing the index graph.
+
+Here is an example of re-ranking a lexical query using a `DenseVectorField` named `vector`:
+
+[source,text]
+?q=title:phone&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])
+
+NOTE: The default `reRankOperator` is `add`, which sums the first-pass score and the vector similarity score.
+Since these scores may differ in magnitude, you can adjust `reRankWeight` to control the balance between them, or use `reRankOperator=replace` to score re-ranked documents by vector similarity alone.

Review Comment:
   This is incorrect, as shown by the attached screenshot in the PR description



-- 
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] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -814,7 +814,37 @@ Some use cases where `includeTags` and/or `excludeTags` may be more useful then
 
 
 
-=== Usage in Re-Ranking Query
+[[vector-reranking]]
+== Usage in Re-Ranking Query
+
+Dense vector similarity scores can be used to xref:query-guide:query-re-ranking.adoc[re-rank] first pass query results.
+Possible use cases include:
+
+* Re-ranking approximate results from a quantized vector field using full fidelity float vectors.
+* Re-ranking lexical search results with dense vector similarity scores.
+
+Details about using the ReRank Query Parser can be found in the xref:query-guide:query-re-ranking.adoc[Query Re-Ranking] section.
+
+=== Re-Ranking with vectorSimilarity Function Query
+
+The xref:query-guide:function-queries.adoc#vectorsimilarity-function[vectorSimilarity()] function can be used with the `{!func}` query parser to re-rank by vector similarity.
+When used as a function query, `vectorSimilarity()` computes the exact similarity for only the candidate documents selected for re-ranking, without traversing the index graph.
+
+Here is an example of re-ranking a lexical query using a `DenseVectorField` named `vector`:
+
+[source,text]
+?q=title:phone&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])
+
+NOTE: The default `reRankOperator` is `add`, which sums the first-pass score and the vector similarity score.
+Since these scores may differ in magnitude, you can adjust `reRankWeight` to control the balance between them, or use `reRankOperator=replace` to score re-ranked documents by vector similarity alone.
+
+When using a quantized vector field type (such as `ScalarQuantizedDenseVectorField`), the KNN first pass scores are computed on the quantized vectors.
+Here is an example of re-ranking those results with exact float similarity scores, where `topK` matches `reRankDocs`:
+
+[source,text]
+?q={!knn f=vector topK=100}[1.0,2.0,3.0,4.0]&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1 reRankOperator=replace}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])

Review Comment:
   It's interesting that this was flagged by Copilot, because it's a source of confusion in the existing documentation and I believe the claim made is incorrect. This would be true if the field used BYTE encoding (meaning int8 vectors are externally supplied), but not if Solr is quantizing vectors.
   
   `ScalarQuantizedDenseVectorField` builds the HNSW graphs using the scalar quantized representations of embeddings. The original float embeddings remain accessible via `FloatVectorValues` and the full precision vectors are used for re-quantization during segment merges.
   
   The code path for `{!func}vectorSimilarity` is:
   1. [VectorSimilaritySourceParser](https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/search/VectorSimilaritySourceParser.java#L108) - calls `getValueSource`
   2. [DenseVectorField.getValueSource](https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/schema/DenseVectorField.java#L487) returns `new FloatKnnVectorFieldSource(field.getName())`
   3. [(Lucene) FloatKnnVectorFieldSource](https://github.com/apache/lucene/blob/main/lucene/queries/src/java/org/apache/lucene/queries/function/valuesource/FloatKnnVectorFieldSource.java#L46) - reads `getFloatVectorValues(fieldName);`
   
   I was able to prove this locally via unit tests that do the following:
   - Test 1: KNN vs KNN + rerank on DenseVectorField. Scores are identical as both paths use exact floats.                                                                                      
   - Test 2: KNN vs  KNN + rerank on ScalarQuantizedDenseVectorField. Scores differ as KNN uses quantized values and the rerank uses exact floats.
   
    I can add the unit tests to the PR if that would be useful.



-- 
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] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -814,7 +814,37 @@ Some use cases where `includeTags` and/or `excludeTags` may be more useful then
 
 
 
-=== Usage in Re-Ranking Query
+[[vector-reranking]]
+== Usage in Re-Ranking Query
+
+Dense vector similarity scores can be used to xref:query-guide:query-re-ranking.adoc[re-rank] first pass query results.
+Possible use cases include:
+
+* Re-ranking approximate results from a quantized vector field using full fidelity float vectors.
+* Re-ranking lexical search results with dense vector similarity scores.
+
+Details about using the ReRank Query Parser can be found in the xref:query-guide:query-re-ranking.adoc[Query Re-Ranking] section.
+
+=== Re-Ranking with vectorSimilarity Function Query
+
+The xref:query-guide:function-queries.adoc#vectorsimilarity-function[vectorSimilarity()] function can be used with the `{!func}` query parser to re-rank by vector similarity.
+When used as a function query, `vectorSimilarity()` computes the exact similarity for only the candidate documents selected for re-ranking, without traversing the index graph.
+
+Here is an example of re-ranking a lexical query using a `DenseVectorField` named `vector`:
+
+[source,text]
+?q=title:phone&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])
+
+NOTE: The default `reRankOperator` is `add`, which sums the first-pass score and the vector similarity score.
+Since these scores may differ in magnitude, you can adjust `reRankWeight` to control the balance between them, or use `reRankOperator=replace` to score re-ranked documents by vector similarity alone.

Review Comment:
   The NOTE admonition currently only applies to the first sentence; the follow-up sentence becomes a normal paragraph. Use a NOTE block so both sentences are part of the same admonition.



##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -814,7 +814,37 @@ Some use cases where `includeTags` and/or `excludeTags` may be more useful then
 
 
 
-=== Usage in Re-Ranking Query
+[[vector-reranking]]
+== Usage in Re-Ranking Query
+
+Dense vector similarity scores can be used to xref:query-guide:query-re-ranking.adoc[re-rank] first pass query results.
+Possible use cases include:
+
+* Re-ranking approximate results from a quantized vector field using full fidelity float vectors.
+* Re-ranking lexical search results with dense vector similarity scores.
+
+Details about using the ReRank Query Parser can be found in the xref:query-guide:query-re-ranking.adoc[Query Re-Ranking] section.
+
+=== Re-Ranking with vectorSimilarity Function Query
+
+The xref:query-guide:function-queries.adoc#vectorsimilarity-function[vectorSimilarity()] function can be used with the `{!func}` query parser to re-rank by vector similarity.
+When used as a function query, `vectorSimilarity()` computes the exact similarity for only the candidate documents selected for re-ranking, without traversing the index graph.
+
+Here is an example of re-ranking a lexical query using a `DenseVectorField` named `vector`:
+
+[source,text]
+?q=title:phone&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])
+
+NOTE: The default `reRankOperator` is `add`, which sums the first-pass score and the vector similarity score.
+Since these scores may differ in magnitude, you can adjust `reRankWeight` to control the balance between them, or use `reRankOperator=replace` to score re-ranked documents by vector similarity alone.
+
+When using a quantized vector field type (such as `ScalarQuantizedDenseVectorField`), the KNN first pass scores are computed on the quantized vectors.
+Here is an example of re-ranking those results with exact float similarity scores, where `topK` matches `reRankDocs`:
+
+[source,text]
+?q={!knn f=vector topK=100}[1.0,2.0,3.0,4.0]&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1 reRankOperator=replace}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])

Review Comment:
   This section suggests you can re-rank KNN results from a quantized vector field with “exact float similarity” while using the same field (`f=vector`) in both passes. Quantized fields inherently lose float precision, so this example/wording is misleading unless you re-rank against a separate non-quantized float vector field.



-- 
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] Ref guide - Improve docs for Dense Vector reranking examples [solr]

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


##########
solr/solr-ref-guide/modules/query-guide/pages/dense-vector-search.adoc:
##########
@@ -814,7 +814,37 @@ Some use cases where `includeTags` and/or `excludeTags` may be more useful then
 
 
 
-=== Usage in Re-Ranking Query
+[[vector-reranking]]
+== Usage in Re-Ranking Query
+
+Dense vector similarity scores can be used to xref:query-guide:query-re-ranking.adoc[re-rank] first pass query results.
+Possible use cases include:
+
+* Re-ranking approximate results from a quantized vector field using full fidelity float vectors.
+* Re-ranking lexical search results with dense vector similarity scores.
+
+Details about using the ReRank Query Parser can be found in the xref:query-guide:query-re-ranking.adoc[Query Re-Ranking] section.
+
+=== Re-Ranking with vectorSimilarity Function Query
+
+The xref:query-guide:function-queries.adoc#vectorsimilarity-function[vectorSimilarity()] function can be used with the `{!func}` query parser to re-rank by vector similarity.
+When used as a function query, `vectorSimilarity()` computes the exact similarity for only the candidate documents selected for re-ranking, without traversing the index graph.
+
+Here is an example of re-ranking a lexical query using a `DenseVectorField` named `vector`:
+
+[source,text]
+?q=title:phone&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])
+
+NOTE: The default `reRankOperator` is `add`, which sums the first-pass score and the vector similarity score.
+Since these scores may differ in magnitude, you can adjust `reRankWeight` to control the balance between them, or use `reRankOperator=replace` to score re-ranked documents by vector similarity alone.
+
+When using a quantized vector field type (such as `ScalarQuantizedDenseVectorField`), the KNN first pass scores are computed on the quantized vectors.
+Here is an example of re-ranking those results with exact float similarity scores, where `topK` matches `reRankDocs`:
+
+[source,text]
+?q={!knn f=vector topK=100}[1.0,2.0,3.0,4.0]&rq={!rerank reRankQuery=$rqq reRankDocs=100 reRankWeight=1 reRankOperator=replace}&rqq={!func}vectorSimilarity(vector,[1.0,2.0,3.0,4.0])

Review Comment:
   In short your original change in the doc is correct, the copilot comment and proposed changes were wrong and confusing, I lost a lot of time understanding what was the point of such comment.  I suggest we remove the comment entirely for future readers



-- 
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